Tài liệu tham khảo cú pháp Ngôn ngữ biểu thức chung cho Data Connect

Hướng dẫn tham khảo này trình bày 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:) 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ể 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:)
• Chỉ định bằng cách sử dụng biểu thức máy chủ, <field>_expr.

Cả biểu thức @auth(expr:) và @check(expr:) CEL đều có thể đánh giá những điều sau:

• request.operationName
• vars (bí danh cho request.variables)
• auth (bí danh cho request.auth)

Trong các đột biến, bạn có thể truy cập và chỉ định 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, có thể là 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ể dùng vars.<variablename> trong một biểu thức làm bí danh cho request.variables.<variablename> đủ điều kiện:

# 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 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ể tạo 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 tên thay thế cho request.auth.

Liên kết uỷ quyền chứa những thông tin sau:

• uid: Mã nhận dạng người dùng duy nhất, được chỉ định 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 về nội dung của auth.token, hãy xem phần Dữ liệu trong mã thông báo uỷ quyền

Liên kết response

Liên kết response chứa dữ liệu mà máy chủ đang 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ó) cá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ề, các trường này có thể chứa khoá UUID, số lượt 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, liên kết response 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 trường _insert, 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à 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 có 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ỳ phần tử nào là một danh sách, thì mỗi lần xuất hiện sẽ được kiểm thử bằng 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 một phần tử 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 null, nhưng không bao giờ là undefined.

Khi chính trường này 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 cả tất cả các phần tử con được chọn trong trường hợp là đố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 toán tử && và ||.

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 trước các biểu thức tuỳ ý a và b, một trường f và một 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 nhận dạng JWT

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