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 CEL (Common Expression Language) pertinente pour la création d'expressions pour les directives @auth(expr:) et @check(expr:).

Vous trouverez des informations de référence complètes sur CEL dans la spécification CEL.

Variables de test transmises dans les requêtes et les mutations

La syntaxe @auth(expr) vous permet d'accéder aux variables à partir de requêtes et de 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

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)

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

• this (valeur du champ actuel)

Objet request.operationName

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

L'objet vars

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

Vous pouvez utiliser vars.<variablename> dans une expression comme alias du request.variables.<variablename> qualifié complet:

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

L'objet auth

Authentication identifie les utilisateurs qui demandent l'accès à vos données et fournit ces informations en tant qu'objet sur lequel vous pouvez vous appuyer dans vos expressions.

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

L'objet d'authentification contient les informations suivantes:

• uid: ID utilisateur unique attribué à l'utilisateur à l'origine de la requête.
• token: carte des valeurs collectées par Authentication.

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

Liaison this

La liaison this renvoie le 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é apparaît 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 ne sera pas atteint et l'évaluation CEL sera 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 en 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 opérateurs && et ||.

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.

Étant donné des expressions arbitraires a et b, un champ f et un indice 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: