مرجع نحو زبان Common Expression برای 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:)
• انتساب با استفاده از عبارات سرور، <field>_expr .

هر دو عبارت CEL @auth(expr:) و @check(expr:) می‌توانند موارد زیر را ارزیابی کنند:

• request.operationName
• vars (نام مستعار برای request.variables )
• auth (نام مستعار request.auth )

در جهش‌ها، می‌توانید به محتویات موارد زیر دسترسی داشته باشید و آنها را اختصاص دهید:

• response (برای بررسی نتایج جزئی در منطق چند مرحله‌ای)

علاوه بر این، عبارات @check(expr:) می‌توانند موارد زیر را ارزیابی کنند:

• this (مقدار فیلد فعلی)
• response (برای بررسی نتایج جزئی در منطق چند مرحله‌ای)

اتصال request.operationName

متغیر request.operarationName نوع عملیات، چه پرس‌وجو و چه جهش، را ذخیره می‌کند.

اتصال vars (request.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 (request.auth)

Authentication کاربرانی را که درخواست دسترسی به داده‌های شما را دارند شناسایی می‌کند و آن اطلاعات را به عنوان یک متغیر (binding) در اختیار شما قرار می‌دهد که می‌توانید در عبارات خود بر اساس آن عمل کنید.

در فیلترها و عبارات خود، می‌توانید auth به عنوان نام مستعار برای request.auth استفاده کنید.

اتصال auth شامل اطلاعات زیر است:

• uid : یک شناسه کاربری منحصر به فرد که به کاربر درخواست کننده اختصاص داده می‌شود.
• token : نقشه‌ای از مقادیر جمع‌آوری‌شده توسط Authentication .

برای جزئیات بیشتر در مورد محتویات auth.token به داده‌های موجود در توکن‌های auth مراجعه کنید.

اتصال response

اتصال response شامل داده‌هایی است که توسط سرور در پاسخ به یک پرس‌وجو یا جهش ، همزمان با جمع‌آوری داده‌ها، جمع‌آوری می‌شوند .

با پیشرفت عملیات، و با تکمیل موفقیت‌آمیز هر مرحله، response شامل داده‌های پاسخ از مراحل تکمیل‌شده با موفقیت است.

اتصال response بر اساس شکل عملیات مرتبط با آن، شامل (چندین) فیلد تو در تو و (در صورت وجود) پرس‌وجوهای تعبیه‌شده، ساختار یافته است.

توجه داشته باشید که وقتی به داده‌های پاسخ پرس‌وجوی جاسازی‌شده دسترسی پیدا می‌کنید، فیلدها می‌توانند شامل هر نوع داده‌ای باشند، بسته به داده‌های درخواست‌شده در پرس‌وجوی جاسازی‌شده؛ وقتی به داده‌های برگردانده‌شده توسط فیلدهای جهش مانند _insert s و _delete s دسترسی پیدا می‌کنید، ممکن است حاوی کلیدهای UUID، تعداد حذف‌ها، و مقادیر تهی باشند (به مرجع جهش‌ها مراجعه کنید).

برای مثال:

• در یک جهش که شامل یک کوئری جاسازی‌شده است، اتصال response شامل داده‌های جستجو در response.query.<fieldName>.<fieldName>.... است، که در این مورد، response.query.todoList و 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
    }
  }
}

• در یک جهش چند مرحله‌ای، برای مثال با چندین فیلد _insert ، اتصال response شامل داده‌های جزئی در response.<fieldName>.<fieldName>.... ، که در این مورد، 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 الزام آور است

اتصال 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 ID

همچنین می‌توانید به فیلدهای auth.token زیر دسترسی داشته باشید: