Dokumentacja składni języka Common Expression Language w usłudze Data Connect

Ten przewodnik zawiera informacje o składni języka Common Expression Language (CEL) przydatnej do tworzenia wyrażeń w przypadku dyrektyw @auth(expr:) i @check(expr:).

Pełne informacje referencyjne dotyczące CEL znajdziesz w specyfikacji CEL.

Testowanie zmiennych przekazywanych w zapytaniach i mutacjach

Składnia @auth(expr) umożliwia dostęp do zmiennych z zapytań i mutacji oraz ich testowanie.

Możesz na przykład użyć zmiennej operacji, takiej jak $status, za pomocą parametru vars.status.

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

Dane dostępne dla wyrażeń

Zarówno wyrażenia CEL @auth(expr:), jak i @check(expr:) mogą oceniać te elementy:

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

Dodatkowo wyrażenia @check(expr:) mogą oceniać:

• this (wartość bieżącego pola)

Obiekt request.operationName

Obiekt request.operarationName przechowuje typ operacji, czyli zapytanie lub mutację.

Obiekt vars

Obiekt vars umożliwia wyrażeniom dostęp do wszystkich zmiennych przekazanych w zapytaniu lub mutacji.

Możesz użyć w wyrażeniu atrybutu vars.<variablename> jako aliasu pełnego atrybutu request.variables.<variablename>:

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

Obiekt auth

Authentication identyfikuje użytkowników, którzy proszą o dostęp do Twoich danych, i przekazuje te informacje jako obiekt, na podstawie którego możesz budować swoje wyrażenia.

W filtrach i wyrażeniach możesz używać wartości auth jako aliasu wartości request.auth.

Obiekt auth zawiera te informacje:

• uid: unikalny identyfikator użytkownika przypisany do użytkownika przesyłającego żądanie.
• token: mapa wartości zebranych przez Authentication.

Więcej informacji o zawartości pola auth.token znajdziesz w artykule Dane w tokenach uwierzytelniania.

Powiązanie this

Powiązanie this zwraca pole, do którego jest przypisane pole dyrektywy @check. W najprostszym przypadku możesz analizować wyniki zapytania o pojedynczej wartości.

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

Jeśli zwracane pole występuje kilka razy, ponieważ każdy z jego przodków jest listą, każde wystąpienie jest testowane z użyciem this powiązanego z każdą wartością.

W przypadku dowolnej ścieżki, jeśli jeden z jej elementów jest elementem nadrzędnym null lub [], nie dojdzie do odwołania się do pola i ocena CEL zostanie pominięta. Inaczej mówiąc, sprawdzanie odbywa się tylko wtedy, gdy this ma wartość null lub nie-null, ale nigdy undefined.

Gdy samo pole jest listą lub obiektem, this ma taką samą strukturę (w tym wszystkich potomków wybranych w przypadku obiektów), jak w tym przykładzie.

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

Składnia wyrażeń złożonych

Aby tworzyć bardziej złożone wyrażenia, możesz łączyć operatory && i ||.

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

W sekcji poniżej opisujemy wszystkie dostępne operatory.

Operatory i pierwotność operatorów

Poniższa tabela zawiera informacje o operatorach i odpowiednim dla nich priorytecie.

Załóżmy dowolne wyrażenia a i b, pole f oraz indeks i.

Dane w tokenach uwierzytelniania

Obiekt auth.token może zawierać te wartości:

Dodatkowe pola w tokenach identyfikacyjnych JWT

Możesz też uzyskać dostęp do tych pól auth.token: