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

In diesen Referenzleitfäden 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

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

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

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

• this (Wert des aktuellen Felds)

Das Objekt „request.operationName“

Im request.operarationName-Objekt wird der Vorgangstyp gespeichert, also „Abfrage“ oder „Mutation“.

Das vars-Objekt

Über das vars-Objekt können Ihre Ausdrücke auf alle Variablen zugreifen, die in Ihrer Abfrage oder Mutation übergeben wurden.

Sie können vars.<variablename> in einem Ausdruck als Alias für die vollständige 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'")

Das auth-Objekt

Authentication identifiziert Nutzer, die Zugriff auf Ihre Daten anfordern, und stellt diese Informationen als Objekt bereit, auf das Sie in Ihren Ausdrücken aufbauen können.

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

Das Auth-Objekt enthält die folgenden Informationen:

• uid: Eine eindeutige Nutzer-ID, die dem anfragenden Nutzer zugewiesen ist.
• token: Eine Zuordnungstabelle der von Authentication erfassten Werte.

Weitere Informationen zum Inhalt von auth.token finden Sie unter Daten in Auth-Tokens.

Die this-Bindung

Die Bindung this wird auf das Feld angewendet, an das die Anweisung @check angehängt ist. In einem einfachen Fall können Sie Ergebnisse von Abfragen mit nur einem Wert auswerten.

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 Vorfahr eine Liste ist, wird jedes Vorkommen mit this getestet, das an jeden Wert gebunden ist.

Wenn ein Vorfahr eines bestimmten Pfades null oder [] ist, wird das Feld nicht erreicht und die CEL-Bewertung für diesen Pfad übersprungen. Mit anderen Worten: Die Auswertung erfolgt 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ählter Abkömmlinge bei Objekten), wie im folgenden Beispiel dargestellt.

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 komplexer Ausdrücke

Sie können komplexere Ausdrücke formulieren, 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 Operatorrangfolge

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

Es sind beliebige Ausdrücke a und b, ein Feld f und ein Index i gegeben.

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: