Documentation de référence de la syntaxe du langage d'expression commun pour Data Connect

Ce guide de référence couvre la syntaxe du langage CEL (Common Expression Language) permettant de créer des expressions pour les directives @auth(expr:) et @check(expr:).

Des informations de référence complètes sur le langage CEL sont disponibles dans la spécification CEL.

Tester les variables transmises dans les requêtes et les mutations

La syntaxe @auth(expr) vous permet d'accéder aux variables des requêtes et des mutations, et de les tester.

Par exemple, vous pouvez inclure une variable d'opération, telle que $status, à l'aide de vars.status.

mutation Update($id: UUID!, $status: Any) @auth(expr: "has(vars.status)")

Données disponibles pour les expressions : requête, réponse, this

Vous utilisez des données pour :

• l'évaluation avec des expressions CEL dans les directives @auth(expr:) et @check(expr:) ;
• l'attribution à l'aide d'expressions de serveur, <field>_expr.

Les expressions CEL @auth(expr:) et @check(expr:) peuvent évaluer les éléments suivants :

• request.operationName
• vars (alias de request.variables)
• auth (alias de request.auth)

Dans les mutations, vous pouvez accéder au contenu des éléments suivants et l'attribuer :

• response (pour vérifier les résultats partiels dans une logique en plusieurs étapes)

De plus, les expressions @check(expr:) peuvent évaluer les éléments suivants :

• this (valeur du champ actuel)
• response (pour vérifier les résultats partiels dans une logique en plusieurs étapes)

Liaison request.operationName

La liaison request.operarationName stocke le type d'opération, qu'il s'agisse d'une requête ou d'une mutation.

Liaison vars (request.vars)

La liaison vars permet à vos expressions d'accéder à toutes les variables transmises dans votre requête ou mutation.

Vous pouvez utiliser vars.<variablename> dans une expression comme alias pour le complet request.variables.<variablename> :

# The following are equivalent
mutation StringType($v: String!) @auth(expr: "vars.v == 'hello'")
mutation StringType($v: String!) @auth(expr: "request.variables.v == 'hello'")

Liaison auth (request.auth)

Authentication identifie les utilisateurs qui demandent l'accès à vos données et fournit ces informations sous forme de liaison sur laquelle vous pouvez vous appuyer dans vos expressions.

Dans vos filtres et expressions, vous pouvez utiliser auth comme alias pour request.auth.

La liaison d'authentification contient les informations suivantes :

• uid : ID utilisateur unique, attribué à l'utilisateur demandeur.
• token : mappage des valeurs collectées par Authentication.

Pour en savoir plus sur le contenu de auth.token, consultez Données dans les jetons d'authentification.

Liaison response

La liaison response contient les données assemblées par le serveur en réponse à une requête ou à une mutation au fur et à mesure de leur assemblage.

Au fur et à mesure de l'opération, à chaque étape terminée, response contient les données de réponse des étapes terminées.

La liaison response est structurée en fonction de la forme de l'opération associée, y compris les champs imbriqués (multiples) et (le cas échéant) les requêtes intégrées.

Notez que lorsque vous accédez aux données de réponse de requête intégrées, les champs peuvent contenir n'importe quel type de données, en fonction des données demandées dans la requête intégrée. Lorsque vous accédez aux données renvoyées par des champs de mutation tels que _insert et _delete, ils peuvent contenir des clés UUID, un nombre de suppressions, des valeurs nulles (consultez la référence des mutations).

Exemple :

• Dans une mutation contenant une requête intégrée, la response liaison contient des données de recherche dans response.query.<fieldName>.<fieldName>...., dans ce cas, response.query.todoList et response.query.todoList.priority.

mutation CheckTodoPriority(
  $uniqueListName: String!
) {
  # This query is identified as `response.query`
  query @check(expr: "response.query.todoList.priority == 'high'", message: "This list is not for high priority items!") {
    # This field is identified as `response.query.todoList`
    todoList(where: { name: $uniqueListName }) {
      # This field is identified as `response.query.todoList.priority`
      priority
    }
  }
}

• Dans une mutation en plusieurs étapes, par exemple avec plusieurs champs _insert, la liaison response contient des données partielles dans response.<fieldName>.<fieldName>...., dans ce cas, response.todoList_insert.id.

mutation CreateTodoListWithFirstItem(
  $listName: String!,
  $itemContent: String!
) @transaction {
  # Step 1
  todoList_insert(data: {
    id_expr: "uuidV4()",
    name: $listName,
  })
  # Step 2:
  todo_insert(data: {
    listId_expr: "response.todoList_insert.id" # <-- Grab the newly generated ID from the partial response so far.
    content: $itemContent,
  })
}

Liaison this

La liaison this correspond au champ auquel la directive @check est associée. Dans un cas de base, vous pouvez évaluer les résultats de requête à valeur unique.

mutation UpdateMovieTitle (
  $movieId: UUID!,
  $newTitle: String!)
  @auth(level: USER)
  @transaction {
  # Step 1: Query and check
  query @redact {
    moviePermission( # Look up a join table called MoviePermission with a compound key.
      key: {movieId: $movieId, userId_expr: "auth.uid"}
    ) {
      # Check if the user has the editor role for the movie. `this` is the string value of `role`.
      # If the parent moviePermission is null, the @check will also fail automatically.
      role @check(expr: "this == 'editor'", message: "You must be an editor of this movie to update title")
    }
  }
  # Step 2: Act
  movie_update(id: $movieId, data: {
    title: $newTitle
  })
}

Si le champ renvoyé se produit plusieurs fois, car un ancêtre est une liste, chaque occurrence est testée avec this lié à chaque valeur.

Pour un chemin donné, si un ancêtre est null ou [], le champ n'est pas atteint et l'évaluation CEL est ignorée pour ce chemin. En d'autres termes, l'évaluation n'a lieu que lorsque this est null ou non null, mais jamais undefined.

Lorsque le champ lui-même est une liste ou un objet, this suit la même structure (y compris tous les descendants sélectionnés dans le cas d'objets), comme illustré dans l'exemple suivant.

mutation UpdateMovieTitle2($movieId: UUID!, $newTitle: String!) @auth(level: USER) @transaction {
  # Step 1: Query and check
  query {
    moviePermissions( # Now we query for a list of all matching MoviePermissions.
      where: {movieId: {eq: $movieId}, userId: {eq_expr: "auth.uid"}}
    # This time we execute the @check on the list, so `this` is the list of objects.
    # We can use the `.exists` macro to check if there is at least one matching entry.
    ) @check(expr: "this.exists(p, p.role == 'editor')", message: "You must be an editor of this movie to update title") {
      role
    }
  }
  # Step 2: Act
  movie_update(id: $movieId, data: {
    title: $newTitle
  })
}

Syntaxe des expressions complexes

Vous pouvez écrire des expressions plus complexes en les combinant avec les && et || opérateurs.

mutation UpsertUser($username: String!) @auth(expr: "(auth != null) && (vars.username == 'joe')")

La section suivante décrit tous les opérateurs disponibles.

Opérateurs et priorité des opérateurs

Utilisez le tableau suivant comme référence pour les opérateurs et leur priorité correspondante.

Compte tenu des expressions arbitraires a et b, d'un champ f et d'un index i.

Données dans les jetons d'authentification

L'objet auth.token peut contenir les valeurs suivantes :

Champs supplémentaires dans les jetons d'ID JWT

Vous pouvez également accéder aux champs auth.token suivants :