מסמך עזר בנושא תחביר של 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)")

נתונים שזמינים לביטויים: request, ‏ response, ‏ this

אתם משתמשים בנתונים כדי:

• הערכה באמצעות ביטויים של CEL בהוראות @auth(expr:) ו-@check(expr:)
• הקצאה באמצעות ביטויים של שרת, <field>_expr.

גם ביטוי ה-CEL @auth(expr:) וגם ביטוי ה-CEL @check(expr:) יכולים להעריך את האפשרויות הבאות:

• request.operationName
• vars (כתובת אימייל חלופית ל-request.variables)
• auth (כתובת אימייל חלופית ל-request.auth)

ב-mutations אפשר לגשת לתוכן של:

• response (כדי לבדוק תוצאות חלקיות בלוגיקה של כמה שלבים)

בנוסף, ביטויים של @check(expr:) יכולים להעריך:

• this (הערך של השדה הנוכחי)
• response (כדי לבדוק תוצאות חלקיות בלוגיקה של כמה שלבים)

הקישור request.operationName

קישור request.operarationName שומר את סוג הפעולה, שאמורה להיות שאילתה או שינוי.

קישור vars (request.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 (request.auth)

Authentication מזהה משתמשים שמבקשים גישה לנתונים שלכם ומספק את המידע הזה כקישור שאפשר להשתמש בו בביטויים שלכם.

אפשר להשתמש ב-auth ככינוי ל-request.auth במסננים ובביטויים.

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

• uid: מזהה משתמש ייחודי שהוקצה למשתמש מבצע הבקשה.
• token: מפה של ערכים שנאספו על ידי Authentication.

פרטים נוספים על התוכן של auth.token זמינים במאמר נתונים באסימוני אימות.

הקישור response

קישור response מכיל את הנתונים שהשרת אוסף בתגובה לשאילתה או למוטציה בזמן שהנתונים האלה נאספים.

ככל שהפעולה מתקדמת, אחרי שכל שלב מסתיים בהצלחה, השדה response מכיל נתוני תגובה מהשלבים שהושלמו בהצלחה.

קישור response מובנה בהתאם לצורת הפעולה המשויכת, כולל שדות (מרובים) בתצוגת עץ ושאילתות מוטמעות (אם רלוונטי).

חשוב לזכור שכאשר ניגשים לנתוני התשובה של השאילתה המוטמעת, השדות יכולים להכיל כל סוג נתונים, בהתאם לנתונים שביקשת בשאילתה המוטמעת. כשניגשים לנתונים שמוחזרים על ידי שדות המוטציה, כמו _insert ו-_delete, הם עשויים להכיל מפתחות UUID, מספר מחיקות, ערכים null (ראו חומר העזר בנושא מוטציות).

לדוגמה:

• במוּטאציה שמכילה שאילתה מוטמעת, קישור response מכיל נתוני חיפוש ב-response.query.<fieldName>.<fieldName>...., במקרה הזה response.query.todoList ו-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
    }
  }
}

• במוטציה בכמה שלבים, למשל עם כמה שדות _insert, קישור response מכיל נתונים חלקיים ב-response.<fieldName>.<fieldName>...., במקרה הזה 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,
  })
}

הקישור 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 הבאים: