Tài liệu tham khảo về cú pháp Ngôn ngữ diễn đạt thông thường cho SQL Connect

Hướng dẫn tham khảo này đề cập đến cú pháp Ngôn ngữ diễn đạt thông thường (CEL) liên quan đến việc tạo biểu thức cho các chỉ thị @auth(expr:), @check(expr:) và @refresh(onMutationExecuted:).

Thông tin tham khảo đầy đủ về CEL được cung cấp trong quy cách CEL.

Biến kiểm thử được truyền trong các truy vấn và đột biến

Cú pháp @auth(expr) cho phép bạn truy cập và kiểm thử các biến từ các truy vấn và đột biến.

Ví dụ: bạn có thể thêm một biến thao tác, chẳng hạn như $status, bằng cách sử dụng vars.status.

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

Dữ liệu có sẵn cho các biểu thức: request, response, this

Bạn sử dụng dữ liệu cho:

• Đánh giá bằng các biểu thức CEL trong chỉ thị @auth(expr:) và @check(expr:)
• Gán bằng các biểu thức máy chủ, <field>_expr.

Các biểu thức CEL @auth(expr:), @check(expr:), @refresh(onMutationExecuted:) có thể đánh giá những nội dung sau:

• request.operationName
• vars (email đại diện cho request.variables)
• auth (email đại diện cho request.auth)

Trong các đột biến, bạn có thể truy cập và gán nội dung của:

• response (để kiểm tra kết quả từng phần trong logic nhiều bước)

Ngoài ra, các biểu thức @check(expr:) có thể đánh giá:

• this (giá trị của trường hiện tại)
• response (để kiểm tra kết quả từng phần trong logic nhiều bước)

Và các biểu thức @refresh(onMutationExecuted:) có liên kết sau:

• mutation.variables
• mutation.auth

Liên kết request.operationName

Liên kết request.operarationName lưu trữ loại thao tác, truy vấn hoặc đột biến.

Liên kết vars (request.vars)

Liên kết vars cho phép các biểu thức của bạn truy cập vào tất cả các biến được truyền trong truy vấn hoặc đột biến.

Bạn có thể sử dụng vars.<variablename> trong một biểu thức làm bí danh cho đủ điều kiện 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'")

Liên kết auth (request.auth)

Authentication xác định những người dùng yêu cầu quyền truy cập vào dữ liệu của bạn và cung cấp thông tin đó dưới dạng một liên kết mà bạn có thể xây dựng trong các biểu thức.

Trong bộ lọc và biểu thức, bạn có thể sử dụng auth làm bí danh cho request.auth.

Liên kết xác thực chứa các thông tin sau:

• uid: Mã nhận dạng người dùng duy nhất, được gán cho người dùng yêu cầu.
• token: Một bản đồ các giá trị do Authentication thu thập.

Để biết thêm thông tin chi tiết về nội dung của auth.token, hãy xem Dữ liệu trong mã thông báo xác thực

Liên kết response

Liên kết response chứa dữ liệu đang được máy chủ tập hợp để phản hồi một truy vấn hoặc đột biến khi dữ liệu đó đang được tập hợp.

Khi thao tác diễn ra, khi mỗi bước được hoàn tất thành công, response sẽ chứa dữ liệu phản hồi từ các bước đã hoàn tất thành công.

Liên kết response được cấu trúc theo hình dạng của thao tác được liên kết, bao gồm (nhiều) trường lồng nhau và (nếu có) truy vấn được nhúng.

Xin lưu ý rằng khi bạn truy cập vào dữ liệu phản hồi truy vấn được nhúng, các trường có thể chứa mọi loại dữ liệu, tuỳ thuộc vào dữ liệu được yêu cầu trong truy vấn được nhúng; khi bạn truy cập vào dữ liệu do các trường đột biến như _insert và _delete trả về, chúng có thể chứa các khoá UUID, số lần xoá, giá trị rỗng (xem tài liệu tham khảo về đột biến).

Ví dụ:

• Trong một đột biến chứa truy vấn được nhúng, response liên kết chứa dữ liệu tra cứu tại response.query.<fieldName>.<fieldName>...., trong trường hợp này là response.query.todoList và 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
    }
  }
}

• Trong một đột biến nhiều bước, ví dụ: với nhiều _insert trường, liên kết response chứa dữ liệu từng phần tại response.<fieldName>.<fieldName>...., trong trường hợp này là 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,
  })
}

Liên kết this

Liên kết this đánh giá trường mà chỉ thị @check được đính kèm. Trong trường hợp cơ bản, bạn có thể đánh giá kết quả truy vấn một giá trị.

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

Nếu trường được trả về xuất hiện nhiều lần vì bất kỳ tổ tiên nào là một danh sách, thì mỗi lần xuất hiện sẽ được kiểm thử với this được liên kết với từng giá trị.

Đối với bất kỳ đường dẫn nào, nếu đối tượng cấp trên là null hoặc [], thì trường sẽ không được truy cập và quá trình đánh giá CEL sẽ bị bỏ qua cho đường dẫn đó. Nói cách khác, quá trình đánh giá chỉ diễn ra khi this là null hoặc không phải null, nhưng không bao giờ là undefined.

Khi chính trường đó là một danh sách hoặc đối tượng, this sẽ tuân theo cùng một cấu trúc (bao gồm tất cả các phần tử con được chọn trong trường hợp đối tượng), như minh hoạ trong ví dụ sau.

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

Cú pháp biểu thức phức tạp

Bạn có thể viết các biểu thức phức tạp hơn bằng cách kết hợp với các && và || toán tử.

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

Phần sau đây mô tả tất cả các toán tử có sẵn.

Toán tử và mức độ ưu tiên của toán tử

Hãy tham khảo bảng sau đây để biết các toán tử và mức độ ưu tiên tương ứng của chúng.

Cho các biểu thức tuỳ ý a và b, trường f và chỉ mục i.

Dữ liệu trong mã thông báo xác thực

Đối tượng auth.token có thể chứa các giá trị sau:

Các trường bổ sung trong mã thông báo JWT ID

Bạn cũng có thể truy cập vào các trường auth.token sau: