Syntaxreferenz für Common Expression Language für Data Connect

In diesem Referenzhandbuch wird die CEL-Syntax (Common Expression Language) behandelt, die für das Erstellen von Ausdrücken für die Direktiven @auth(expr:) und @check(expr:) relevant ist.

Vollständige Referenzinformationen zu CEL finden Sie in der CEL-Spezifikation.

Testvariablen, die in Abfragen und Mutationen übergeben werden

Mit der @auth(expr)-Syntax können Sie auf Variablen aus Abfragen und Mutationen zugreifen und sie testen.

Sie können beispielsweise eine Vorgangsvariable wie $status mit vars.status einfügen.

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

Für Ausdrücke verfügbare Daten: request, response, this

Sie verwenden Daten für:

• Auswertung mit CEL-Ausdrücken in @auth(expr:)- und @check(expr:)-Direktiven
• Zuweisung mit Serverausdrücken, <field>_expr.

Sowohl @auth(expr:)- als auch @check(expr:)-CEL-Ausdrücke können Folgendes auswerten:

• request.operationName
• vars (Alias für request.variables)
• auth (Alias für request.auth)

In Mutationen können Sie auf die Inhalte von Folgendem zugreifen und sie zuweisen:

• response (zum Prüfen von Teilergebnissen in der mehrstufigen Logik)

Außerdem können @check(expr:)-Ausdrücke Folgendes auswerten:

• this (der Wert des aktuellen Felds)
• response (zum Prüfen von Teilergebnissen in der mehrstufigen Logik)

Die Bindung „request.operationName“

Die request.operarationName-Bindung speichert den Vorgangstyp, entweder „query“ (Abfrage) oder „mutation“ (Mutation).

Die vars-Bindung (request.vars)

Mit der vars-Bindung können Ihre Ausdrücke auf alle Variablen zugreifen, die in Ihrer Abfrage oder Mutation übergeben werden.

Sie können vars.<variablename> in einem Ausdruck als Alias für den vollständig qualifizierten request.variables.<variablename> verwenden:

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

Die auth-Bindung (request.auth)

Mit Authentication werden Nutzer identifiziert, die Zugriff auf Ihre Daten anfordern. Diese Informationen werden als Bindung bereitgestellt, die Sie in Ihren Ausdrücken verwenden können.

In Ihren Filtern und Ausdrücken können Sie auth als Alias für request.auth verwenden.

Die Authentifizierungsbindung enthält die folgenden Informationen:

• uid: Eine eindeutige Nutzer-ID, die dem anfragenden Nutzer zugewiesen ist.
• token: Eine Zuordnung von Werten, die von Authentication erfasst wurden.

Weitere Informationen zum Inhalt von auth.token findest du unter Daten in Autorisierungstokens.

Die response-Bindung

Die response-Bindung enthält die Daten, die vom Server als Reaktion auf eine Abfrage oder Mutation während der Zusammenstellung zusammengestellt werden.

Im Laufe des Vorgangs enthält response nach jedem erfolgreich abgeschlossenen Schritt Antwortdaten.

Die response-Bindung ist entsprechend der Form des zugehörigen Vorgangs strukturiert, einschließlich (mehrerer) verschachtelter Felder und (falls zutreffend) eingebetteter Abfragen.

Wenn Sie auf eingebettete Abfrageantwortdaten zugreifen, können Felder je nach den in der eingebetteten Abfrage angeforderten Daten einen beliebigen Datentyp enthalten. Wenn Sie auf Daten zugreifen, die von Mutationsfeldern wie _insert und _delete zurückgegeben werden, können diese UUID-Schlüssel, die Anzahl der Löschvorgänge und Nullwerte enthalten (siehe Mutationsreferenz).

Beispiel:

• In einer Mutation, die eine eingebettete Abfrage enthält, enthält die response-Bindung Lookup-Daten unter response.query.<fieldName>.<fieldName>...., in diesem Fall response.query.todoList und 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
    }
  }
}

• Bei einer mehrstufigen Mutation, z. B. mit mehreren _insert-Feldern, enthält die response-Bindung Teildaten unter response.<fieldName>.<fieldName>...., in diesem Fall 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,
  })
}

Die this-Bindung

Die Bindung this wird zum Feld ausgewertet, an das die @check-Anweisung angehängt ist. Im einfachsten Fall werten Sie Ergebnisse von Anfragen mit einem einzelnen Wert aus.

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

Wenn das zurückgegebene Feld mehrmals vorkommt, weil ein übergeordnetes Element eine Liste ist, wird jedes Vorkommen mit this getestet, wobei this an jeden Wert gebunden ist.

Wenn ein Vorfahre für einen bestimmten Pfad null oder [] ist, wird das Feld nicht erreicht und die CEL-Auswertung für diesen Pfad wird übersprungen. Die Auswertung erfolgt also nur, wenn this null oder nicht null ist, aber nie undefined.

Wenn das Feld selbst eine Liste oder ein Objekt ist, folgt this derselben Struktur (einschließlich aller ausgewählten untergeordneten Elemente im Fall von Objekten), wie im folgenden Beispiel veranschaulicht.

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

Syntax für komplexe Ausdrücke

Sie können komplexere Ausdrücke schreiben, indem Sie sie mit den Operatoren && und || kombinieren.

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

Im folgenden Abschnitt werden alle verfügbaren Operatoren beschrieben.

Operatoren und Operator-Vorrang

In der folgenden Tabelle finden Sie eine Übersicht über die Operatoren und ihre entsprechende Priorität.

Angenommen, es gibt beliebige Ausdrücke a und b, ein Feld f und einen Index i.

Daten in Auth-Tokens

Das auth.token-Objekt kann die folgenden Werte enthalten:

Zusätzliche Felder in JWT-ID-Tokens

Sie können auch auf die folgenden auth.token-Felder zugreifen: