Referencia de sintaxis de Common Expression Language para Data Connect

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

En estas guías de referencia, se abarca la sintaxis de Common Expression Language (CEL) relevante para crear expresiones para las directivas @auth(expr:) y @check(expr:).

La información de referencia completa de CEL se proporciona en la especificación de CEL.

Prueba las variables que se pasan en las consultas y mutaciones

La sintaxis de @auth(expr) te permite acceder a variables y probarlas desde consultas y mutaciones.

Por ejemplo, puedes incluir una variable de operación, como $status, con vars.status.

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

Datos disponibles para las expresiones: request, response, this

Usas los datos para lo siguiente:

• Evaluación con expresiones CEL en directivas @auth(expr:) y @check(expr:)
• Tarea con expresiones del servidor, <field>_expr.

Las expresiones CEL @auth(expr:) y @check(expr:) pueden evaluar lo siguiente:

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

En las mutaciones, puedes acceder al contenido de los siguientes elementos y asignarlos:

• response (para verificar los resultados parciales en la lógica de varios pasos)

Además, las expresiones @check(expr:) pueden evaluar lo siguiente:

• this (el valor del campo actual)
• response (para verificar los resultados parciales en la lógica de varios pasos)

La vinculación request.operationName

La vinculación request.operarationName almacena el tipo de operación, ya sea una consulta o una mutación.

La vinculación vars (request.vars)

La vinculación vars permite que tus expresiones accedan a todas las variables que se pasan en tu consulta o mutación.

Puedes usar vars.<variablename> en una expresión como alias para el request.variables.<variablename> completamente calificado:

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

La vinculación auth (request.auth)

Authentication identifica a los usuarios que solicitan acceso a tus datos y proporciona esa información como una vinculación en la que puedes basarte en tus expresiones.

En tus filtros y expresiones, puedes usar auth como alias para request.auth.

La vinculación de autenticación contiene la siguiente información:

• uid: Un ID de usuario único, asignado al usuario solicitante.
• token: Un mapa de valores recopilados por Authentication.

Para obtener más detalles sobre el contenido de auth.token, consulta Datos en los tokens de autenticación.

La vinculación de response

La vinculación response contiene los datos que el servidor ensambla en respuesta a una consulta o mutación a medida que se ensamblan los datos.

A medida que avanza la operación y se completa cada paso de forma correcta, response contiene datos de respuesta de los pasos que se completaron correctamente.

La vinculación response se estructura según la forma de su operación asociada, incluidos los campos anidados (múltiples) y las consultas incorporadas (si corresponde).

Ten en cuenta que, cuando accedes a los datos de respuesta de la consulta incorporada, los campos pueden contener cualquier tipo de datos, según los datos solicitados en la consulta incorporada. Cuando accedes a los datos que muestran los campos de mutación, como _insert y _delete, es posible que contengan claves de UUID, la cantidad de eliminaciones y valores nulos (consulta la referencia de mutaciones).

Por ejemplo:

• En una mutación que contiene una consulta incorporada, la vinculación response contiene datos de búsqueda en response.query.<fieldName>.<fieldName>...., en este caso, response.query.todoList y 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
    }
  }
}

• En una mutación de varios pasos, por ejemplo, con varios campos _insert, la vinculación response contiene datos parciales en response.<fieldName>.<fieldName>...., en este 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,
  })
}

La vinculación de this

La vinculación this se evalúa como el campo al que se adjunta la directiva @check. En un caso básico, puedes evaluar los resultados de la consulta de un solo valor.

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 el campo que se muestra ocurre varias veces porque cualquier ancestro es una lista, cada ocurrencia se prueba con this vinculado a cada valor.

Para cualquier ruta determinada, si un ancestro es null o [], no se llegará al campo y se omitirá la evaluación de CEL para esa ruta. En otras palabras, la evaluación solo se realiza cuando this es null o no es null, pero nunca es undefined.

Cuando el campo en sí es una lista o un objeto, this sigue la misma estructura (incluidos todos los elementos secundarios seleccionados en el caso de los objetos), como se ilustra en el siguiente ejemplo.

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

Sintaxis de expresión compleja

Puedes escribir expresiones más complejas si las combinas con los operadores && y ||.

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

En la siguiente sección, se describen todos los operadores disponibles.

Operadores y prioridad de operadores

Usa la siguiente tabla como referencia para los operadores y su prioridad correspondiente.

Dadas las expresiones arbitrarias a y b, un campo f y un índice i.

Datos en los tokens de autenticación

El objeto auth.token puede contener los siguientes valores:

Campos adicionales en los tokens de ID de JWT

También puedes acceder a los siguientes campos auth.token: