שימוש ב-GraphQL

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מדיניות GraphQL יכולה לנתח את מטען הנתונים של בקשת GraphQL למשתני זרימת הודעות, לאמת את הבקשה מול סכימת GraphQL או לבצע את שתי הפעולות.

מדיניות GraphQL מנתחת את נתוני ה-payload של GraphQL למשתנים של זרימת ההודעות, מאמתת בקשות GraphQL מול סכימה, או מבצעת את שתי הפעולות.

אפשר להשתמש במדיניות GraphQL כדי:

• מוודאים שממשקי ה-API מעבדים רק בקשות שתואמות לסכימה שסיפקתם.
• אפשר להגביל את מטען הנתונים על ידי הגדרת מספר מקסימלי של פרגמנטים.
• משייכים GraphQL למוצרי API.
• להשתמש בתכונות של מדיניות Oauth2,‏ VerifyAPIKey ו-Quota, בדיוק כמו ב-REST.

‫GraphQL תומך בסוגי מטען הייעודי (payload) הבאים:

• פרסום של מטען ייעודי (payload) של graphQL עם Content-Type : application/graphql
• פרסום של מטען ייעודי (payload) של graphQL עם Content-Type: applcation/json
• GET של מטען ייעודי (payload) של GraphQL שבו המטען הייעודי הוא פרמטר של שאילתה

הערה: עבור מטען ייעודי (payload) של application/json מהצורה

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

המערכת של Apigee מתעלמת כרגע מהשדות האופציונליים operationName ו-variables.

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

מידע נוסף על GraphQL זמין באתר GraphQL.org.

דוגמה

בדוגמה הבאה מוצגות הפעולות שצריך לבצע כדי להעלות סכימת GraphQL ל-Apigee ולהשתמש בה כדי לאמת בקשות עם תוכן GraphQL.

זהירות: אימות המטען הייעודי למסמך מול הסכימה הוא בדרך כלל פעולה יקרה, ולכן מומלץ לבצע אימות סכימה בזהירות. פעולות אימות סכימה יכולות להיות עתירות מעבד (CPU), במיוחד אם המטען הייעודי (payload) והסכימה מורכבים, והן עלולות לגרום לזמני אחזור משמעותיים.

הערה: אפשר לספק רק סכימה אחת לכל מדיניות. אם אתם צריכים לכלול כמה סכימות, מוסיפים כמה מדיניות GraphQL לשרת ה-Proxy.

יצירת קובץ סכימה

כדי להריץ את הדוגמה, קודם יוצרים קובץ סכימת GraphQL עם התוכן הבא:

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

שומרים את הקובץ בשם הרצוי, ואחריו מוסיפים את הסיומת .graphql.

הוספת מדיניות GraphQL בממשק המשתמש של Apigee

קודם יוצרים את מדיניות GraphQL באופן הבא:

1. בממשק המשתמש של Apigee, עוברים לדף Proxy development > API Proxies.

   מעבר אל API Proxies

2. ברשימת ה-proxies, בוחרים את ה-proxy ל-API שרוצים להשתמש במדיניות GraphQL לגביו.
3. לוחצים על הכרטיסייה פיתוח.
4. בחלונית הימנית, לוחצים על הלחצן + לצד התיקייה מדיניות.

5. בתיבת הדו-שיח Create policy (יצירת מדיניות), לוחצים על השדה Select policy type (בחירת סוג המדיניות), גוללים למטה אל Mediation (גישור) ובוחרים באפשרות GraphQL.

   

   מזינים שם לתצוגה ושם.

   לאחר מכן בוחרים קובץ סכימת GraphQL באופן הבא:

   1. לוחצים על השדה קובץ סכימה. יוצגו האפשרויות הבאות:
      • ללא סכימה. אם תבחרו באפשרות הזו, Apigee לא ישתמש בסכימה כדי לאמת בקשות.
      • ייבוא סכימת GraphQL‏ (‎.graphql)

   2. בוחרים באפשרות ייבוא סכימת GraphQL‏ (‎.graphql). מוצגות האפשרויות הבאות:

      

   3. לוחצים על בחירת קובץ ובוחרים את קובץ הסכימה שיצרתם קודם (שחייבת להיות לו הסיומת .graphql). הקובץ מופיע בשדה שם הסכימה.

      
6. לוחצים על יצירה כדי ליצור את המדיניות.

אחרי שיצרתם את מדיניות GraphQL, אתם יכולים לצרף אותה לשלב ב-PreFlow:

1. בחלונית הימנית, בוחרים באפשרות Proxy Endpoints > default > PreFlow:

   

2. לוחצים על הלחצן + לצד PreFlow בחלונית Response בפינה השמאלית התחתונה של הכלי לעריכה חזותית:

   

3. בתיבת הדו-שיח Add policy step (הוספת שלב מדיניות), בוחרים במדיניות GQL-.
   הערה: בדוגמה הזו נעשה שימוש בשם ברירת המחדל, GQL, למדיניות GraphQL. אפשר לשנות את השם ברכיב DisplayName ב-XML של המדיניות, על ידי הוספת ביטוי תיאורי אחרי GQL-. מידע נוסף על שינוי שם המדיניות
4. לוחצים על הוספה כדי לצרף את המדיניות.
5. לוחצים על שמירה כדי לשמור את השינויים בגרסה הנוכחית.
6. כדי לפרוס את השינויים, לוחצים על הכרטיסייה סקירה כללית ובוחרים באפשרות פריסה.

אפשרויות ההגדרה של מדיניות GraphQL מפורטות בקטע אפשרויות GraphQL שבהמשך.

עכשיו אפשר לבדוק את מדיניות GraphQL באמצעות הפקודה הבאה של curl:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

כאשר PROXY_BASEPATH הוא נתיב הבסיס של ה-proxy ו-HOST_NAME הוא שם ה-proxy, כולל מספר הגרסה האחרונה. כשמריצים את הפקודה, Apigee מאמת את הבקשה מול הסכימה ומחזיר את הפלט הבא.

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

דוגמה נוספת לבקשה:

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

הפעם אימות הבקשה נכשל ומופיעה הודעת השגיאה הבאה.

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

אפשרויות GraphQL

אלה האפשרויות של GraphPolicy:

• ‫OperationType: סוג הפעולה. האפשרויות הן:
  • ‫query: הגרסה המקבילה של GraphQL לפעולת REST‏ GET.
  • ‫mutation: הגרסה המקבילה של GraphQL לפעולת REST‏ PUT.
  • ‫query_mutation: גם query וגם mutation.
• ‫MaxDepth: העומק המקסימלי של השאילתה, כשהיא מיוצגת כעץ. ‫MaxDepth מאפשרת לחסום שאילתות עומק במטען הייעודי (payload), כך ש-Apigee לא צריך ליצור משתני זרימה גדולים מאוד כדי להכיל את הערכים. עם זאת, מטען הייעודי (payload) נשלח כמו שהוא, בלי קשר לערך של MaxDepth.
• ‫MaxCount: המספר המקסימלי של פרגמנטים שיכולים להיות במטען הייעודי. אפשר להשתמש בזה כדי למנוע משרת ה-GraphQL back-end של הלקוח להריץ שאילתות מורכבות מאוד, וכך לאלץ את הלקוחות לפצל את הלוגיקה שלהם למטען קטן יותר.
• ‫Action: אחת מפעולות ה-GraphQL הבאות:
  • ‫parseApigee מנתח את מטען ה-GraphQL וממיר אותו למשתני זרימה. לאחר מכן אפשר להשתמש בתוכן של משתני הזרימה במדיניות כמו JavaCallout. שימו לב ש-parse גם מאמת את מטען המידע.
  • ‫verify: Apigee מוודא שמטען ה-GraphQL תואם לסכימה שהועלתה ל-proxy. אפשר להשתמש ב-verify כדי לוודא שלא מתקבלות בקשות שלא תואמות לסכימה. כך אפשר לחסוך זמן יקר של מעבד בקצה העורפי.
  • ‫parse_verify: ניתוח המטען הייעודי (payload) ואימות שלו.
• ‫ResourceURL: הנתיב לקובץ סכימת GraphQL שמשמש את Apigee לאימות בקשת GraphQL.

מידע נוסף על האפשרויות האלה