Referensi sintaksis Common Expression Language untuk Data Connect

Panduan referensi ini membahas sintaksis Common Expression Language (CEL) yang relevan dengan pembuatan ekspresi untuk perintah @auth(expr:) dan @check(expr:).

Informasi referensi lengkap untuk CEL disediakan dalam spesifikasi CEL.

Menguji variabel yang diteruskan dalam kueri dan mutasi

Sintaksis @auth(expr) memungkinkan Anda mengakses dan menguji variabel dari kueri dan mutasi.

Misalnya, Anda dapat menyertakan variabel operasi, seperti $status, menggunakan vars.status.

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

Data yang tersedia untuk ekspresi

Ekspresi CEL @auth(expr:) dan @check(expr:) dapat mengevaluasi hal berikut:

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

Selain itu, ekspresi @check(expr:) dapat mengevaluasi:

• this (nilai kolom saat ini)

Objek request.operationName

Objek request.operarationName menyimpan jenis operasi, baik kueri maupun mutasi.

Objek vars

Objek vars memungkinkan ekspresi Anda mengakses semua variabel yang diteruskan dalam kueri atau mutasi.

Anda dapat menggunakan vars.<variablename> dalam ekspresi sebagai alias untuk request.variables.<variablename> yang sepenuhnya memenuhi syarat:

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

Objek auth

Authentication mengidentifikasi pengguna yang meminta akses ke data Anda dan memberikan informasi tersebut sebagai objek yang dapat Anda buat dalam ekspresi.

Dalam filter dan ekspresi, Anda dapat menggunakan auth sebagai alias untuk request.auth.

Objek auth berisi informasi berikut:

• uid: ID pengguna unik, yang ditetapkan untuk pengguna yang meminta.
• token: Peta nilai yang dikumpulkan oleh Authentication.

Untuk mengetahui detail selengkapnya tentang konten auth.token, lihat Data dalam token autentikasi

Binding this

this pengikatan dievaluasi ke kolom tempat perintah @check disertakan. Dalam kasus dasar, Anda dapat mengevaluasi hasil kueri bernilai tunggal.

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

Jika kolom yang ditampilkan muncul beberapa kali karena setiap ancestor adalah daftar, setiap kejadian akan diuji dengan this yang terikat ke setiap nilai.

Untuk jalur tertentu, jika ancestor adalah null atau [], kolom tidak akan dijangkau dan evaluasi CEL akan dilewati untuk jalur tersebut. Dengan kata lain, evaluasi hanya terjadi jika this adalah null atau non-null, tetapi tidak pernah undefined.

Jika kolom itu sendiri adalah daftar atau objek, this akan mengikuti struktur yang sama (termasuk semua turunan yang dipilih jika berupa objek), seperti yang diilustrasikan dalam contoh berikut.

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

Sintaksis ekspresi kompleks

Anda dapat menulis ekspresi yang lebih kompleks dengan menggabungkannya dengan operator && dan ||.

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

Bagian berikut menjelaskan semua operator yang tersedia.

Operator dan prioritas operator

Gunakan tabel berikut sebagai referensi untuk operator dan prioritasnya yang sesuai.

Ekspresi arbitrer tertentu a dan b, kolom f, dan indeks i.

Data dalam token autentikasi

Objek auth.token dapat berisi nilai berikut:

Kolom tambahan di token ID JWT

Anda juga dapat mengakses kolom auth.token berikut: