Referência da sintaxe da linguagem de expressão comum para o Data Connect

Este guia de referência aborda a sintaxe da linguagem de expressão comum (CEL) relevante para criar expressões para as diretivas @auth(expr:) e @check(expr:).

As informações completas de referência da CEL estão disponíveis na especificação da CEL.

Testar variáveis transmitidas em consultas e mutações

A sintaxe @auth(expr) permite acessar e testar variáveis de consultas e mutações.

Por exemplo, é possível incluir uma variável de operação, como $status, usando vars.status.

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

Dados disponíveis para expressões

As expressões CEL @auth(expr:) e @check(expr:) podem avaliar o seguinte:

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

Além disso, as expressões @check(expr:) podem avaliar:

• this (o valor do campo atual)

O objeto request.operationName

O objeto request.operarationName armazena o tipo de operação, consulta ou mutação.

O objeto vars

O objeto vars permite que as expressões acessem todas as variáveis transmitidas na consulta ou mutação.

É possível usar vars.<variablename> em uma expressão como um alias para o request.variables.<variablename> totalmente qualificado:

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

O objeto auth

Authentication identifica os usuários que solicitam acesso aos seus dados e fornece essas informações como um objeto que pode ser usado nas suas expressões.

Nos filtros e expressões, é possível usar auth como um alias para request.auth.

O objeto de autenticação contém as seguintes informações:

• uid: um ID de usuário exclusivo, atribuído ao usuário solicitante.
• token: um mapa de valores coletados por Authentication.

Para mais detalhes sobre o conteúdo de auth.token, consulte Dados em tokens de autenticação.

A vinculação this

A vinculação this é avaliada como o campo ao qual a diretiva @check está anexada. Em um caso básico, você pode avaliar resultados de consulta de valor único.

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
  })
}

Se o campo retornado ocorrer várias vezes porque algum ancestral é uma lista, cada ocorrência será testada com this vinculado a cada valor.

Para qualquer caminho, se um ancestral for null ou [], o campo não será alcançado e a avaliação do CEL será ignorada para esse caminho. Em outras palavras, a avaliação só acontece quando this é null ou não é null, mas nunca undefined.

Quando o campo é uma lista ou um objeto, this segue a mesma estrutura (incluindo todos os descendentes selecionados no caso de objetos), conforme ilustrado no exemplo a seguir.

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
  })
}

Sintaxe de expressão complexa

É possível escrever expressões mais complexas combinando com os operadores && e ||.

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

A seção a seguir descreve todos os operadores disponíveis.

Operadores e precedência do operador

Use a tabela a seguir como referência para os operadores e a precedência correspondente.

Expressões arbitrárias fornecidas a e b, um campo f e um índice i.

Dados em tokens de autenticação

O objeto auth.token pode conter os seguintes valores:

Outros campos em tokens de ID JWT

Também é possível acessar os seguintes campos auth.token: