ข้อมูลอ้างอิงไวยากรณ์ Common Expression Language สำหรับ Data Connect

คู่มืออ้างอิงนี้ครอบคลุมไวยากรณ์ Common Expression Language (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:) สามารถประเมินข้อมูลต่อไปนี้ได้

  • request.operationName
  • vars (ชื่อแทนของ request.variables)
  • auth (ชื่อแทนของ request.auth)

นอกจากนี้ นิพจน์ @check(expr:) ยังประเมินสิ่งต่อไปนี้ได้

  • this (ค่าของฟิลด์ปัจจุบัน)

ออบเจ็กต์ request.operationName

ออบเจ็กต์ request.operarationName จะจัดเก็บประเภทการดำเนินการ ซึ่งอาจเป็นการค้นหาหรือการดัดแปลง

ออบเจ็กต์ 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

Authentication จะระบุผู้ใช้ที่ขอสิทธิ์เข้าถึงข้อมูลของคุณ และระบุข้อมูลดังกล่าวเป็นออบเจ็กต์ที่คุณนำไปใช้ต่อในนิพจน์ได้

ในตัวกรองและนิพจน์ คุณสามารถใช้ auth เป็นชื่อแทนของ request.auth

ออบเจ็กต์ auth มีข้อมูลต่อไปนี้

  • uid: รหัสผู้ใช้ที่ไม่ซ้ำกันซึ่งกำหนดให้กับผู้ใช้ที่ส่งคำขอ
  • token: แผนที่ค่าที่ Authentication รวบรวม

ดูรายละเอียดเพิ่มเติมเกี่ยวกับเนื้อหาของ auth.token ได้ที่ข้อมูลในโทเค็นการตรวจสอบสิทธิ์

การเชื่อมโยง 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 เท่านั้น แต่จะไม่มีการประเมินเมื่อ this เป็น 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

โอเปอเรเตอร์ คำอธิบาย การเชื่อมโยง
a[i] a() a.f ดัชนี การเรียกใช้ การเข้าถึงช่อง ซ้ายไปขวา
!a -a การปฏิเสธแบบยูนาร์ ขวาไปซ้าย
a/b a%b a*b โอเปอเรเตอร์การคูณ ซ้ายไปขวา
a+b a-b โอเปอเรเตอร์การเพิ่ม ซ้ายไปขวา
a>b a>=b a<b a<=b โอเปอเรเตอร์ที่เกี่ยวข้อง ซ้ายไปขวา
a in b มีอยู่จริงในรายการหรือแผนที่ ซ้ายไปขวา
type(a) == t การเปรียบเทียบประเภท โดยที่ t อาจเป็นบูลีน int ลอย ตัวเลข สตริง รายการ แผนที่ การประทับเวลา หรือระยะเวลา ซ้ายไปขวา
a==b a!=b โอเปอเรเตอร์การเปรียบเทียบ ซ้ายไปขวา
a && b AND แบบมีเงื่อนไข ซ้ายไปขวา
a || b OR แบบมีเงื่อนไข ซ้ายไปขวา
a ? true_value : false_value นิพจน์ Ternary ซ้ายไปขวา

ข้อมูลในโทเค็นการตรวจสอบสิทธิ์

ออบเจ็กต์ auth.token อาจมีค่าต่อไปนี้

ช่อง คำอธิบาย
email อีเมลที่เชื่อมโยงกับบัญชี (หากมี)
email_verified true หากผู้ใช้ยืนยันว่ามีสิทธิ์เข้าถึงอีเมล email ผู้ให้บริการบางรายจะยืนยันอีเมลที่ตนเป็นเจ้าของโดยอัตโนมัติ
phone_number หมายเลขโทรศัพท์ที่เชื่อมโยงกับบัญชี (หากมี)
name ชื่อที่แสดงของผู้ใช้ หากตั้งค่าไว้
sub UID Firebase ของผู้ใช้ ซึ่งต้องไม่ซ้ำกันภายในโปรเจ็กต์
firebase.identities พจนานุกรมของข้อมูลประจำตัวทั้งหมดที่เชื่อมโยงกับบัญชีของผู้ใช้รายนี้ คีย์ของพจนานุกรมอาจเป็น email, phone, google.com, facebook.com, github.com, twitter.com ก็ได้ ค่าของพจนานุกรมคืออาร์เรย์ของตัวระบุที่ไม่ซ้ำกันสำหรับผู้ให้บริการข้อมูลประจำตัวแต่ละรายที่เชื่อมโยงกับบัญชี เช่น auth.token.firebase.identities["google.com"][0] มีรหัสผู้ใช้ Google รายการแรกที่เชื่อมโยงกับบัญชี
firebase.sign_in_provider ผู้ให้บริการการลงชื่อเข้าใช้ที่ใช้รับโทเค็นนี้ โดยอาจเป็นสตริงใดก็ได้ต่อไปนี้ custom, password, phone, anonymous, google.com, facebook.com, github.com, twitter.com
firebase.tenant tenantId ที่เชื่อมโยงกับบัญชี หากมี เช่น tenant2-m6tyz

ช่องเพิ่มเติมในโทเค็นข้อมูลประจำตัว JWT

นอกจากนี้ คุณยังเข้าถึงช่อง auth.token ต่อไปนี้ได้ด้วย

การอ้างสิทธิ์โทเค็นที่กำหนดเอง
alg อัลกอริทึม "RS256"
iss ผู้ออก อีเมลบัญชีบริการของโปรเจ็กต์
sub เรื่อง อีเมลบัญชีบริการของโปรเจ็กต์
aud กลุ่มเป้าหมาย "https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit"
iat เวลาที่ออก เวลาปัจจุบันเป็นวินาทีนับตั้งแต่ Epoch ของ UNIX
exp เวลาหมดอายุ เวลาเป็นวินาทีนับตั้งแต่ Epoch ของ UNIX ที่โทเค็นจะหมดอายุ โดยช้ากว่า iat ได้สูงสุด 3,600 วินาที
หมายเหตุ: ตัวเลือกนี้จะควบคุมเฉพาะเวลาที่โทเค็นที่กำหนดเองจะหมดอายุเท่านั้น แต่หลังจากที่คุณลงชื่อเข้าใช้ผู้ใช้โดยใช้ signInWithCustomToken() ผู้ใช้จะยังคงลงชื่อเข้าใช้อุปกรณ์จนกว่าเซสชันจะใช้งานไม่ได้หรือผู้ใช้ออกจากระบบ
<claims> (ไม่บังคับ) การอ้างสิทธิ์ที่กำหนดเองซึ่งไม่บังคับที่จะรวมไว้ในโทเค็น ซึ่งเข้าถึงได้ผ่าน auth.token (หรือ request.auth.token) ในนิพจน์ ตัวอย่างเช่น หากคุณสร้างการอ้างสิทธิ์ที่กำหนดเอง adminClaim คุณจะเข้าถึงการอ้างสิทธิ์ดังกล่าวได้ด้วย auth.token.adminClaim