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

Tài liệu tham khảo này hướng dẫn về 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 lệnh @auth(expr:) và @check(expr:).

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

Kiểm thử các biến được truyền trong 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ừ truy vấn và đột biến.

Ví dụ: bạn có thể đưa vào 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 lệnh @auth(expr:) và @check(expr:)
• Gán bằng các biểu thức máy chủ, <field>_expr.

Cả biểu thức CEL @auth(expr:) và @check(expr:) đều 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 độ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ả một 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ả một phần trong logic nhiều bước)

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 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 riêng biệt, được gán cho người dùng yêu cầu.
• token: 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 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 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 nhúng, các trường dữ liệu có thể chứa bất kỳ loại dữ liệu nào, tuỳ thuộc vào dữ liệu được yêu cầu trong truy vấn 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 mã nhận dạng duy nhất (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 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, chẳng hạn như có nhiều _insert trường, liên kết response chứa dữ liệu một 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à lệnh @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ì tổ tiên 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 đối với đườ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 là 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 sử dụng bảng sau đây làm tài liệu tham khảo cho 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: