مرجع بنية لغة التعبير الشائعة لخدمة Data Connect

تتناول أدلة البيانات المرجعية هذه بنية لغة التعبير الشائعة (CEL) ذات الصلة بمحاولة إنشاء تعبيرات للتوجيهَين @auth(expr:) و@check(expr:).

تتوفّر معلومات مرجعية كاملة حول "الوضع المتقدّم" (CEL) في مواصفات CEL.

متغيّرات الاختبار التي تم تمريرها في طلبات البحث والطفرات

يتيح لك أسلوب @auth(expr) الوصول إلى المتغيّرات واختبارها من طلبات البحث والطفرات.

على سبيل المثال، يمكنك تضمين متغيّر عملية، مثل $status، باستخدام vars.status.

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

البيانات المتاحة للتعبيرات

يمكن لكل من تعبيرَي CEL @auth(expr:) و@check(expr:) تقييم العناصر التالية:

• request.operationName
• vars (الاسم المستعار لـ request.variables)
• auth (الاسم المستعار لـ request.auth)

بالإضافة إلى ذلك، يمكن لتعبيرات @check(expr:) تقييم ما يلي:

• this (قيمة الحقل الحالي)

عنصر request.operationName

يخزِّن عنصر request.operarationName نوع العملية، سواء كان طلب بحث أو عملية تعديل.

عنصر vars

يسمح عنصر vars للتعبيرات بالوصول إلى جميع المتغيّرات المُمرَّرة في طلب البحث أو عملية التحويل.

يمكنك استخدام vars.<variablename> في تعبير كاسم مستعار ل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'")

عنصر auth

يحدِّد Authentication المستخدِمين الذين يطلبون الوصول إلى بياناتك ويقدِّم هذه المعلومات كعنصر يمكنك الاستفادة منه في تعبيراتك.

في الفلاتر والتعابير، يمكنك استخدام auth كعنوان بديل ل request.auth.

يحتوي عنصر المصادقة على المعلومات التالية:

• ‫uid: معرّف مستخدم فريد تمّ تعيينه للمستخدم الذي قدّم الطلب.
• token: خريطة للقيم التي جمعها Authentication

لمزيد من التفاصيل حول محتوى auth.token، يُرجى الاطّلاع على البيانات في الرموز المميّزة لمنح الأذونات.

عملية ربط this

يتم تقييم الربط this على أنّه الحقل الذي يتم إرفاق التوجيه @check به. في الحالة الأساسية، يمكنك تقييم نتائج الاستعلامات ذات القيمة الواحدة.

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

إذا كان الحقل المعروض يظهر عدة مرات لأنّ أيّ سلف هو قائمة، يتم اختبار كل موضع باستخدام this مقيّد بكل قيمة.

بالنسبة إلى أي مسار معيّن، إذا كان أحد الأسلاف هو null أو []، لن يتم الوصول إلى الحقل وسيتم تخطّي تقييم CEL لهذا المسار. بعبارة أخرى، لا يتم التقييم إلا عندما يكون this هو null أو غير null، ولكن لا يتم أبدًا undefined.

عندما يكون الحقل نفسه قائمة أو عنصرًا، يتّبع this البنية نفسها (بما في ذلك جميع العناصر الفرعية المحدّدة في حال الكائنات)، كما هو موضّح في المثال التالي.

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

بنية التعبيرات المعقدة

يمكنك كتابة عبارات أكثر تعقيدًا من خلال دمجها مع عاملَي التشغيل && و||.

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

يوضّح القسم التالي جميع عوامل التشغيل المتاحة.

عوامل التشغيل وترتيبها في الأولوية

استخدِم الجدول التالي كمرجع لعوامل التشغيل وترتيبها المُعترَف به.

يتمّ منح تعبيرَين عشوائيَين a وb، وحقل f، وفهرس i.

البيانات في الرموز المميّزة للمصادقة

قد يحتوي عنصر auth.token على القيم التالية:

حقول إضافية في الرموز المميّزة لتعريف JWT

يمكنك أيضًا الوصول إلى حقول auth.token التالية: