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

Lưu ý: Firebase Data Connect đang ở dạng Bản dùng trước công khai. Data Connect sẽ tuân theo "Điều khoản áp dụng cho các sản phẩm trước giai đoạn phát hành rộng rãi" trong mục Điều khoản dành riêng cho dịch vụ của Điều khoản dịch vụ của Google Cloud Platform. Các tính năng trước khi phát hành công khai được cung cấp "nguyên trạng" và có thể bị hạn chế hỗ trợ. Để biết thêm thông tin, hãy xem nội dung mô tả về giai đoạn ra mắt.

Hướng dẫn tham khảo này trình bày cú pháp Ngôn ngữ biểu thức 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à sự thay đổi.

Ví dụ: bạn có thể đưa một biến toán tử, chẳng hạn như $status, vào 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 biểu thức

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

• request.operationName
• vars (bí danh của request.variables)
• auth (bí danh của request.auth)

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

• this (giá trị của trường hiện tại)

Đối tượng request.operationName

Đối tượng request.operarationName lưu trữ loại toán tử, truy vấn hoặc đột biến.

Đối tượng vars

Đối tượng vars cho phép 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 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'")

Đối tượng 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 đối tượng mà bạn có thể xây dựng trong 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.

Đối tượng auth chứa các 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 chi tiết về nội dung của auth.token, hãy xem phần Dữ liệu trong mã thông báo xác thực

Liên kết this

Lưu ý: Liên kết this hợp lệ cho biểu thức @check, chứ không phải biểu thức @auth.

this liên kết sẽ đánh giá thành 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 có giá trị đơn.

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ỳ thành phần mẹ nào cũng là một danh sách, thì mỗi lần xuất hiện sẽ được kiểm thử bằng this 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 thành phần 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 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 biểu thức phức tạp hơn bằng cách kết hợp với toán tử && và ||.

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

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

Toán tử và thứ tự ưu tiên của toán tử

Hãy sử dụng bảng sau đây để tham khảo các toán tử và thứ tự ưu tiên tương ứng.

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

Toán tử	Mô tả	Tính liên kết
a[i] a() a.f	Chỉ mục, lệnh gọi, quyền truy cập vào trường	từ trái sang phải
!a -a	Phủ định một ngôi	phải sang trái
a/b a%b a*b	Toán tử nhân	từ trái sang phải
a+b a-b	Toán tử cộng	từ trái sang phải
a>b a>=b a<b a<=b	Toán tử quy chiếu	từ trái sang phải
a in b	Sự tồn tại trong danh sách hoặc bản đồ	từ trái sang phải
type(a) == t	So sánh kiểu, trong đó t có thể là bool, int, float, số, chuỗi, danh sách, bản đồ, dấu thời gian hoặc thời lượng	từ trái sang phải
a==b a!=b	Toán tử so sánh	từ trái sang phải
a && b	AND có điều kiện	từ trái sang phải
a || b	Toán tử HOẶC có điều kiện	từ trái sang phải
a ? true_value : false_value	Biểu thức ba ngôi	từ trái sang phả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:

Trường	Mô tả
email	Địa chỉ email liên kết với tài khoản, nếu có.
email_verified	true nếu người dùng đã xác minh rằng họ có quyền truy cập vào địa chỉ email. Một số nhà cung cấp tự động xác minh địa chỉ email mà họ sở hữu.
phone_number	Số điện thoại được liên kết với tài khoản (nếu có).
name	Tên hiển thị của người dùng, nếu được đặt.
sub	UID Firebase của người dùng. Đây là giá trị duy nhất trong một dự án.
firebase.identities	Từ điển của tất cả danh tính được liên kết với tài khoản của người dùng này. Các khoá của từ điển có thể là bất kỳ khoá nào sau đây: email, phone, google.com, facebook.com, github.com, twitter.com. Các giá trị của từ điển là các mảng gồm giá trị nhận dạng duy nhất cho từng nhà cung cấp danh tính được liên kết với tài khoản. Ví dụ: auth.token.firebase.identities["google.com"][0] chứa mã nhận dạng người dùng Google đầu tiên được liên kết với tài khoản.
firebase.sign_in_provider	Nhà cung cấp dịch vụ đăng nhập dùng để lấy mã thông báo này. Có thể là một trong các chuỗi sau: custom, password, phone, anonymous, google.com, facebook.com, github.com, twitter.com.
firebase.tenant	tenantId được liên kết với tài khoản, nếu có. Ví dụ: tenant2-m6tyz

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:

Xác nhận quyền sở hữu mã thông báo tuỳ chỉnh
alg	Thuật toán	"RS256"
iss	Tổ chức phát hành	Địa chỉ email của tài khoản dịch vụ của dự án
sub	Chủ đề	Địa chỉ email của tài khoản dịch vụ của dự án
aud	Đối tượng	"https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
iat	Thời gian phát hành	Thời gian hiện tại, tính bằng giây kể từ thời gian bắt đầu của hệ thống UNIX
exp	Thời gian hết hạn	Thời gian (tính bằng giây kể từ thời gian bắt đầu của hệ thống UNIX) mà mã thông báo hết hạn. Thời gian này có thể muộn tối đa 3600 giây so với iat. Lưu ý: điều này chỉ kiểm soát thời điểm mã thông báo tuỳ chỉnh hết hạn. Tuy nhiên, sau khi bạn đăng nhập cho người dùng bằng signInWithCustomToken(), họ sẽ vẫn duy trì trạng thái đăng nhập vào thiết bị cho đến khi phiên của họ không hợp lệ hoặc người dùng đăng xuất.
<claims> (không bắt buộc)		Các thông báo xác nhận quyền sở hữu tuỳ chỉnh không bắt buộc để đưa vào mã thông báo. Bạn có thể truy cập thông báo xác nhận quyền sở hữu này thông qua auth.token (hoặc request.auth.token) trong biểu thức. Ví dụ: nếu tạo một đơn khiếu nại tuỳ chỉnh adminClaim, bạn có thể truy cập vào đơn khiếu nại đó bằng auth.token.adminClaim.