SQL Connect için Common Expression Language söz dizimi referansı

Bu referans kılavuzunda, @auth(expr:), @check(expr:) ve @refresh(onMutationExecuted:) yönergeleri için ifade oluşturmayla ilgili Common Expression Language (CEL) söz dizimi ele alınmaktadır.

CEL ile ilgili tüm referans bilgileri CEL spesifikasyonunda verilmiştir.

Sorgularda ve mutasyonlarda iletilen test değişkenleri

@auth(expr) söz dizimi, sorgulardan ve mutasyonlardan değişkenlere erişmenize ve bunları test etmenize olanak tanır.

Örneğin, vars.status kullanarak $status gibi bir işlem değişkeni ekleyebilirsiniz.

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

İfadeler için kullanılabilen veriler: request, response, this

Verileri şu amaçlarla kullanıyorsunuz:

  • @auth(expr:) ve @check(expr:) yönergelerinde CEL ifadeleriyle değerlendirme
  • Sunucu ifadeleri kullanılarak yapılan atama: <field>_expr.

@auth(expr:), @check(expr:), @refresh(onMutationExecuted:) CEL ifadeleri aşağıdakileri değerlendirebilir:

  • request.operationName
  • vars (request.variables için takma ad)
  • auth (request.auth için takma ad)

Mutasyonlarda, aşağıdakilerin içeriğine erişebilir ve bunları atayabilirsiniz:

  • response (çok adımlı mantıktaki kısmi sonuçları kontrol etmek için)

Ayrıca @check(expr:) ifadeleri şunları değerlendirebilir:

  • this (mevcut alanın değeri)
  • response (çok adımlı mantıktaki kısmi sonuçları kontrol etmek için)

And @refresh(onMutationExecuted:) ifadeleri aşağıdaki bağlamaya sahiptir:

  • mutation.variables
  • mutation.auth

request.operationName bağlaması

request.operarationName bağlaması, işlemin türünü (sorgu veya mutasyon) depolar.

vars bağlaması (request.vars)

vars bağlaması, ifadelerinizin sorgunuzda veya mutasyonunuzda iletilen tüm değişkenlere erişmesine olanak tanır.

Tam nitelikli request.variables.<variablename> için bir ifade içinde takma ad olarak vars.<variablename> kullanabilirsiniz:

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

auth bağlaması (request.auth)

Authentication, verilerinize erişim isteyen kullanıcıları tanımlar ve bu bilgileri, ifadelerinizde kullanabileceğiniz bir bağlama olarak sunar.

Filtrelerinizde ve ifadelerinizde request.auth için takma ad olarak auth kullanabilirsiniz.

Kimlik doğrulama bağlaması aşağıdaki bilgileri içerir:

  • uid: İstekte bulunan kullanıcıya atanan benzersiz kullanıcı kimliği.
  • token: Authentication tarafından toplanan değerlerin haritası.

auth.token içeriği hakkında daha fazla bilgi için Kimlik doğrulama jetonlarındaki veriler başlıklı makaleyi inceleyin.

response bağlaması

response bağlaması, bir sorguya veya mutasyona yanıt olarak sunucu tarafından bir araya getirilen verileri bu veriler bir araya getirilirken içerir.

İşlem devam ederken her adım başarıyla tamamlandığında response, başarıyla tamamlanan adımlardan gelen yanıt verilerini içerir.

response bağlaması, ilişkili işleminin şekline göre yapılandırılır. Buna (birden fazla) iç içe yerleştirilmiş alan ve (varsa) yerleşik sorgular dahildir.

Yerleştirilmiş sorgu yanıt verilerine eriştiğinizde alanların, yerleştirilmiş sorguda istenen verilere bağlı olarak herhangi bir veri türünü içerebileceğini unutmayın. _insert ve _delete gibi mutasyon alanları tarafından döndürülen verilere eriştiğinizde bunlar UUID anahtarları, silme sayısı ve boş değerler içerebilir (mutasyon referansına bakın).

Örneğin:

  • Yerleşik sorgu içeren bir mutasyonda response bağlaması, response.query.<fieldName>.<fieldName>.... konumunda arama verileri içerir. Bu örnekte bu veriler response.query.todoList ve response.query.todoList.priority şeklindedir.
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
    }
  }
}
  • Birden fazla _insert alanı içeren çok adımlı bir mutasyonda, response bağlaması response.<fieldName>.<fieldName>.... (bu örnekte response.todoList_insert.id) konumunda kısmi veriler içerir.
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,
  })
}

this bağlaması

this bağlaması, @check yönergesinin eklendiği alan olarak değerlendirilir. Temel bir durumda, tek değerli sorgu sonuçlarını değerlendirebilirsiniz.

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

Döndürülen alan, herhangi bir üst öğe liste olduğu için birden çok kez gerçekleşirse her gerçekleşme, her değere bağlı this ile test edilir.

Belirli bir yol için üst öğe null veya [] ise alana ulaşılamaz ve bu yol için CEL değerlendirmesi atlanır. Başka bir deyişle, değerlendirme yalnızca this, null veya null olmayan bir değer olduğunda gerçekleşir ancak hiçbir zaman undefined olmaz.

Alan bir liste veya nesne olduğunda this, aşağıdaki örnekte gösterildiği gibi aynı yapıyı (nesneler söz konusu olduğunda seçilen tüm alt öğeler dahil) izler.

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

Karmaşık ifade söz dizimi

&& ve || operatörleriyle birleştirerek daha karmaşık ifadeler yazabilirsiniz.

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

Aşağıdaki bölümde, kullanılabilen tüm operatörler açıklanmaktadır.

Operatörler ve operatör önceliği

Operatörler ve bunlara karşılık gelen öncelik için aşağıdaki tabloyu referans olarak kullanın.

Rastgele ifadeler a ve b, bir alan f ve bir dizin i verildiğinde.

Operatör Açıklama Birleşme özelliği
a[i] a() a.f Dizin, çağrı, alan erişimi soldan sağa
!a -a Tekli olumsuzlama sağdan sola
a/b a%b a*b Çarpma operatörleri soldan sağa
a+b a-b Toplama operatörleri soldan sağa
a>b a>=b a<b a<=b İlişkisel operatörler soldan sağa
a in b Listede veya haritada bulunma soldan sağa
type(a) == t t değerinin bool, int, float, sayı, dize, liste, eşleme, zaman damgası veya süre olabileceği tür karşılaştırması soldan sağa
a==b a!=b Karşılaştırma operatörleri soldan sağa
a && b Koşullu VE soldan sağa
a || b Koşullu VEYA soldan sağa
a ? true_value : false_value Üçlü ifade soldan sağa

Kimlik doğrulama jetonlarındaki veriler

auth.token nesnesi aşağıdaki değerleri içerebilir:

Alan Açıklama
email Varsa hesapla ilişkili e-posta adresi.
email_verified Kullanıcı, email adresine erişimi olduğunu doğruladıysa true. Bazı sağlayıcılar, sahip oldukları e-posta adreslerini otomatik olarak doğrular.
phone_number Hesapla ilişkili telefon numarası (varsa)
name Kullanıcının görünen adı (ayarlanmışsa).
sub Kullanıcının Firebase UID'si. Bu, proje içinde benzersizdir.
firebase.identities Bu kullanıcının hesabıyla ilişkili tüm kimliklerin sözlüğü. Sözlüğün anahtarları şunlardan biri olabilir: email, phone, google.com, facebook.com, github.com, twitter.com. Sözlüğün değerleri, hesapla ilişkili her kimlik sağlayıcı için benzersiz tanımlayıcı dizileridir. Örneğin, auth.token.firebase.identities["google.com"][0], hesapla ilişkili ilk Google kullanıcı kimliğini içerir.
firebase.sign_in_provider Bu jetonu almak için kullanılan oturum açma sağlayıcısı. Şu dizelerden biri olabilir: custom, password, phone, anonymous, google.com, facebook.com, github.com, twitter.com.
firebase.tenant Hesapla ilişkili tenantId (varsa). Örneğin, tenant2-m6tyz

JWT kimlik jetonlarındaki ek alanlar

Aşağıdaki auth.token alanlarına da erişebilirsiniz:

Özel Jeton Talepleri
alg Algoritma "RS256"
iss Düzenleyen Projenizin hizmet hesabı e-posta adresi
sub Konu Projenizin hizmet hesabı e-posta adresi
aud Kitle "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
iat Oluşturulma zamanı Unix epoch'tan bu yana geçen geçerli saat (saniye cinsinden)
exp Geçerlilik süresi Jetonun süresinin dolduğu zaman (UNIX epoch'tan bu yana geçen saniye cinsinden). iat değerinden en fazla 3.600 saniye sonra olabilir.
Not: Bu, yalnızca özel jetonun süresinin dolacağı zamanı kontrol eder. Ancak bir kullanıcının oturumunu signInWithCustomToken() kullanarak açtığınızda, oturumu geçersiz kılınana veya kullanıcı oturumu kapatana kadar cihazda oturumu açık kalır.
<claims> (isteğe bağlı) İfadelere auth.token (veya request.auth.token) aracılığıyla erişilebilen, jetona dahil edilecek isteğe bağlı özel hak talepleri. Örneğin, adminClaim adlı özel bir hak talebi oluşturursanız bu hak talebine auth.token.adminClaim ile erişebilirsiniz.