שימוש ב-GraphQL

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

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

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

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

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

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

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

• פרסום של מטען ייעודי (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.

זהירות: אימות המטען הייעודי (payload) מול הסכימה הוא בדרך כלל פעולה יקרה, ולכן מומלץ לבצע אימות סכימה בזהירות. פעולות אימות סכימה יכולות להיות עתירות מעבד (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: המספר המקסימלי של פרגמנטים שיכולים להיות במטען הייעודי. אפשר להשתמש בזה כדי למנוע משרת ה-backend של GraphQL של הלקוח להריץ שאילתות מורכבות מאוד, וכך לאלץ את הלקוחות לפצל את הלוגיקה שלהם למטען קטן יותר.
• ‫Action: אחת מפעולות ה-GraphQL הבאות:
  • ‫parseApigee מנתח את מטען ה-GraphQL הייעודי למשתני התהליך. ‫You can then use the contents of the flow variables in policies such as JavaCallout. שימו לב ש-parse מאמת גם את מטען הנתונים.
  • ‫verify: Apigee מוודא שמטען ה-GraphQL תואם לסכימה שהועלתה לשרת ה-proxy. אתם יכולים להשתמש ב-verify כדי לוודא שלא תקבלו בקשות שלא תואמות לסכימה שלכם. כך אפשר לחסוך זמן יקר של מעבד בקצה העורפי.
  • ‫parse_verify: ניתוח המטען הייעודי (payload) ואימות שלו.
• ‫ResourceURL: הנתיב לקובץ סכימת GraphQL שמשמש את Apigee לאימות בקשת GraphQL.

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