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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Este guia de referência abrange 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 de referência completas sobre a 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: request, response, this

Você usa dados para:

• Avaliação com expressões CEL em diretivas @auth(expr:) e @check(expr:)
• Atribuição usando expressões do servidor, <field>_expr.

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)

Nas mutações, é possível acessar e atribuir o conteúdo de:

• response (para verificar resultados parciais na lógica de várias etapas)

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

• this (o valor do campo atual)
• response (para verificar resultados parciais na lógica de várias etapas)

A vinculação request.operationName

A vinculação request.operarationName armazena o tipo de operação, consulta ou mutação.

A vinculação vars (request.vars)

A vinculação 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'")

A vinculação auth (request.auth)

Authentication identifica os usuários que solicitam acesso aos seus dados e fornece essas informações como uma vinculação que pode ser usada nas suas expressões.

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

A vinculação 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 response

A vinculação response contém os dados que estão sendo montados pelo servidor em resposta a uma consulta ou mutação enquanto esses dados estão sendo montados.

À medida que a operação avança e cada etapa é concluída, response contém dados de resposta das etapas concluídas.

A vinculação response é estruturada de acordo com a forma da operação associada, incluindo (vários) campos aninhados e (se aplicável) consultas embutidas.

Quando você acessa dados de resposta de consulta incorporados, os campos podem conter qualquer tipo de dados, dependendo dos dados solicitados na consulta incorporada. Quando você acessa dados retornados por campos de mutação, como _inserts e _deletes, eles podem conter chaves UUID, número de exclusões e valores nulos (consulte a referência de mutações).

Exemplo:

• Em uma mutação que contém uma consulta incorporada, a vinculação response contém dados de pesquisa em response.query.<fieldName>.<fieldName>...., neste caso, response.query.todoList e 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
    }
  }
}

• Em uma mutação em várias etapas, por exemplo, com vários campos _insert, a vinculação response contém dados parciais em response.<fieldName>.<fieldName>...., neste caso, 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,
  })
}

A vinculação this

A vinculação this é avaliada para 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 abaixo.

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: