מסמך עזר בנושא תחביר של 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:) וגם ביטוי ה-CEL @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.

אובייקט האימות מכיל את הפרטים הבאים:

• 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, אבל אף פעם 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.

נתונים בטוקני אימות

האובייקט auth.token יכול להכיל את הערכים הבאים:

שדות נוספים באסימונים מזהים מסוג JWT

אפשר גם לגשת לשדות auth.token הבאים: