Referencia de sintaxis de Common Expression Language para Data Connect

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

En la especificación de CEL, se proporciona información de referencia completa sobre este lenguaje.

Variables de prueba que se pasan en consultas y mutaciones

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

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 de CEL en las directivas @auth(expr:) y @check(expr:)
• Asignación con expresiones del servidor, <field>_expr.

Ambas 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 a los contenidos 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 consulta o mutación.

La vinculación de 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 de 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 de auth (request.auth)

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

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

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

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

Para obtener más detalles sobre el contenido de auth.token, consulta Datos en tokens de autorizació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 esos datos.

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

La vinculación de 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 devuelven los campos de mutación, como _inserts y _deletes, pueden contener claves de UUID, cantidad de eliminaciones, 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 en el campo al que se adjunta la directiva @check. En un caso básico, puedes evaluar los resultados de la búsqueda 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 devuelto aparece varias veces porque algún elemento superior es una lista, cada aparición se prueba con this vinculado a cada valor.

Para cualquier ruta determinada, si un elemento superior es null o [], no se accederá al campo y se omitirá la evaluación de CEL para esa ruta. En otras palabras, la evaluación solo se lleva a cabo cuando this es null o no es null, pero nunca 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 expresiones complejas

Puedes escribir expresiones más complejas combinándolas 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 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 de auth.token: