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

Bu referans kılavuzda, @auth(expr:) ve @check(expr:) yönergeleri için ifadeler 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, sorgulardaki ve mutasyonlardaki değişkenlere erişmenize ve bunları test etmenize olanak tanır.

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

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

İfadelerde kullanılabilen veriler: request, response, this

Verileri şu amaçlarla kullanırsınız:

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

Hem @auth(expr:) hem de @check(expr:) CEL ifadeleri aşağıdakileri değerlendirebilir:

• request.operationName
• vars (request.variables için diğer ad)
• auth (request.auth için diğer ad)

Değişikliklerde aşağıdakilerin içeriklerine 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 (geçerli alanın değeri)
• response (çok adımlı mantıktaki kısmi sonuçları kontrol etmek için)

The request.operationName bağlaması

request.operarationName bağlaması, işlem 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.

vars.<variablename> ifadesini, tam nitelikli request.variables.<variablename> için takma ad olarak 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ğlama (request.auth)

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

Filtrelerinizde ve ifadelerinizde auth yerine request.auth takma adını kullanabilirsiniz.

Yetkilendirme 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 veriler oluşturulurken oluşturulan verileri içerir.

İşlem devam ederken her adım başarıyla tamamlandıkça 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. Bu yapılandırmaya iç içe yerleştirilmiş (birden fazla) alanlar ve (varsa) yerleştirilmiş 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 bu veriler UUID anahtarları, silme sayısı ve boş değerler içerebilir (bkz. mutasyon referansı).

Örneğin:

• Yerleştirilmiş bir sorgu içeren bir mutasyonda, response bağlama, response.query.<fieldName>.<fieldName>.... konumunda arama verileri içerir. Bu durumda response.query.todoList ve 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
    }
  }
}

• Çok adımlı bir mutasyonda (ör. birden fazla _insert alanı içeren) response bağlaması, response.<fieldName>.<fieldName>.... konumunda kısmi veriler içerir. Bu örnekte 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,
  })
}

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 oluşuyorsa her oluşum, her değere bağlı this ile test edilir.

Belirli bir yolda, bir ü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 yapılır ancak hiçbir zaman undefined olduğunda yapılmaz.

Alan kendisi 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 karşılık gelen öncelikleri için aşağıdaki tabloyu referans olarak kullanın.

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

Kimlik doğrulama jetonlarındaki veriler

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

JWT kimlik jetonlarındaki ek alanlar

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