מדיניות GraphQL

מדיניות רגילה

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

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

מדיניות 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
• שאילתות ושינויים
• הסבר על משתני Flow

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

דוגמה לשימוש במדיניות הזו מופיעה במאמר בנושא שימוש ב-GraphQL.

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

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

רכיב <GraphQL>

הגדרה של מדיניות <GraphQL>.

ערך ברירת המחדל	מידע נוסף מופיע בכרטיסייה מדיניות ברירת המחדל שבהמשך
חובה?	חובה
סוג	סוג
רכיב הורה	לא רלוונטי
רכיבי צאצא	<Action> <MaxDepth> <MaxCount> <MaxPayloadSizeInBytes> <OperationType> <Source> <ResourceURL>

תחביר

רכיב <GraphQL> משתמש בתחביר הבא:

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
  <OperationType>[query|mutuation|all]</OperationType>
  <MaxDepth>MAX_DEPTH</MaxDepth>
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
  // [Start maxpayloadsize]
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES&lt/MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL>PATH/TO/SCHEMA.xsd</ResourceURL>
</GraphQL>

מדיניות ברירת המחדל

בדוגמה הבאה מוצגות הגדרות ברירת המחדל כשמוסיפים מדיניות <GraphQL> לתהליך בממשק המשתמש של Apigee:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GraphQL name="GraphQLParser">
  <Source>request</Source>
  <OperationType>query</OperationType>
  <MaxDepth>10</MaxDepth>
  <MaxCount>10</MaxCount>
  <MaxPayloadSizeInBytes></MaxPayloadSizeInBytes>
  <Action>parse</Action>
  <ResourceURL></ResourceURL>
</GraphQL>

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

מאפיין	ברירת מחדל	חובה?	תיאור
name	לא רלוונטי	חובה	השם הפנימי של המדיניות. הערך של מאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול לחרוג מ-255 תווים. אפשר להשתמש ברכיב <DisplayName> כדי לתת למדיניות תווית בשם אחר בשפה טבעית בכלי לעריכת פרוקסי בממשק הניהול.
continueOnError	FALSE	אופציונלי	מגדירים את הערך false כדי להחזיר שגיאה אם המדיניות נכשלת. זו התנהגות צפויה ברוב המקרים. הגדרה ל-true מאפשרת להמשיך את הביצוע של התהליך גם אחרי שמדיניות נכשלת. מאמרים קשורים: הפעלת כללי תקלות מתבצעת רק במצב שגיאה (מידע על continueOnError) טיפול בתקלות בתהליך הנוכחי
enabled	TRUE	אופציונלי	מגדירים את המדיניות למצב true כדי לאכוף אותה. מגדירים את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.
async	FALSE	הוצא משימוש	המאפיין הזה הוצא משימוש.

בטבלה הבאה מופיע תיאור כללי של רכיבי הצאצא של <GraphQL>:

רכיב צאצא	חובה?	תיאור
פעולות נפוצות
<Action>	אופציונלי	מציינים את הפעולה שרוצים לבצע לגבי הבקשה: parse, verify או parse_verify (שניהם).
<MaxCount>	אופציונלי	המספר המקסימלי של שאילתות או קטעים שבקשת GraphQL יכולה ליצור. ערך ברירת המחדל הוא 10.
<MaxDepth>	אופציונלי	העומק המקסימלי של העץ בשאילתה. ערך ברירת המחדל הוא 4.
<MaxPayloadSizeInBytes>	אופציונלי	הגודל המקסימלי של מטען ייעודי בקילובייט.
<OperationType>	חובה	מציין את סוג הבקשה שאפשר לנתח: query,‏ mutation או query_mutation (כלומר, כל אחת מהאפשרויות).
<ResourceURL>	אופציונלי	תיאור. המיקום של קובץ סכימת GraphQL.
<Source>	חובה	request

כל אחד מרכיבי הצאצא האלה מתואר בקטעים הבאים.

הפניה לרכיב צאצא

בקטע הזה מתוארים רכיבי הבן של <GraphQL>.

<Action>

הפעולה מייצגת אחת מהפעולות הבאות של GraphQL:

• parse: Apigee מנתח את מטען ה-GraphQL הייעודי למשתני זרימת הודעות. במאמר דוגמאות לייצוגים של משתנים של זרימת הודעות מוסבר על המשתנים שמוגדרים כש-Action מוגדר ל-parse. כך אפשר לחסוך זמן יקר של מעבד בקצה העורפי. שימו לב ש-verify מנתח גם את מטען הנתונים.
• ‫verify: Apigee מוודא שמטען ה-GraphQL תואם לסכימה שהועלתה לשרת ה-proxy.
• ‫parse_verify: Apigee מנתח ומאמת את בקשת GraphQL.

ערך ברירת המחדל	parse
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <Action> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Action>parse</Action>
</GraphQL>

<MaxCount>

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

ערך ברירת המחדל	10
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <MaxCount> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxCount>MAX_NUMBER_OF_QUERIES</MaxCount>
</GraphQL>

<MaxDepth>

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

הערה: התג MaxDepth פועל כשהרכיב Action מוגדר לערך parse או parse-verify. מומלץ להשתמש בפעולה MaxDepth עם הפעולות האלה כדי לבדוק את העומק, במקום להשתמש בפעולה verify שהיא יקרה יותר.

ערך ברירת המחדל	10
חובה?	אופציונלי
סוג	מספר שלם
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <MaxDepth> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxDepth>MAX_DEPTH</MaxDepth>
</GraphQL>

<MaxPayloadSizeInBytes>

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

הערה: אם הערך MaxPayloadSizeInByte לא מצוין במדיניות, לא נאכפת הגבלת גודל.

ערך ברירת המחדל	request
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <MaxPayloadSizeInBytes> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <MaxPayloadSizeInBytes>MAX_PAYLOAD_SIZE_IN_BYTES</MaxPayloadSizeInBytes>
</GraphQL>

<OperationType>

מציין את סוג הבקשה שאפשר לנתח:

• ‫query: שאילתת GraphQL.
• ‫mutation: מוטציה של GraphQL
• ‫query_mutation: שאילתת GraphQL או מוטציה.

אם היקף ההרשאות הוא query ומועברת בקשת שינוי, הבקשה נכשלת ומוחזרת השגיאה 4xx.

ערך ברירת המחדל	query
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <OperationType> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <OperationType>[query|mutation|query_mutation]</OperationType>
</GraphQL>

<ResourceURL>

הנתיב לקובץ סכימת GraphQL שמשמש לאימות הבקשות על ידי מדיניות GraphQL. בקטע דוגמה אפשר לראות דוגמה להעלאת סכימת GraphQL ל-Apigee.

אם השם של קובץ הסכימה שהעליתם הוא my-schema.graphql, אז רכיב <ResourceURL> יהיה

<ResourceURL>graphql://my-schema.graphql</ResourceURL>

ערך ברירת המחדל	לא רלוונטי
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב ResourceURL משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <ResourceURL>PATH/TO/SCHEMA.graphql</ResourceURL>
</GraphQL>

<Source>

המקור שבו המדיניות הזו מופעלת.

הערה: המקור צריך להיות מחרוזת השאילתה הגולמית של graphql, ולא שאילתת graphql שעטופה ב-JSON.

ערך ברירת המחדל	request
חובה?	אופציונלי
סוג	String
רכיב אב	<GraphQL>
רכיבי צאצא	ללא

רכיב <Source> משתמש בתחביר הבא:

תחביר

<GraphQL
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="POLICY_NAME" >
  <Source>request</Source>
</GraphQL>

מנתח GraphQL

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

המבנה של בקשת GraphQL

הדיאגרמה הבאה מציגה את המבנה של בקשת GraphQL.

ייצוג של הגדרות פעולה בזרימת ההודעות

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

המשתנים של זרימת ההודעות פועלים לפי המוסכמה הבאה:

graphql.(root-index).(root definition)[(sub-indices).(child-definitions)…]

where:

• ‫graphql: קידומת סטטית שמציינת שמדובר במשתני זרימת הודעות שקשורים ל-GraphQL
• ‫root-Index: אינדקס מבוסס שמציין את האינדקס של הגדרות השאילתה ברמת הבסיס (ברירת מחדל עד 4 לכל בקשה)
• ‫root-definition: גוף ההודעה של בקשת GraphQL ברמת הבסיס, ארגומנטים, הערכים שלהם
• ‫sub-indices: אינדקסים של רכיבי צאצא
• ‫child-definitions: הגדרות ברמת העלה שמתאימות לשדות ספציפיים ולערכים שלהם

ייצוג של הגדרות פעולה במשתנה של זרימת ההודעות

שדות בהודעה	סוג	תיאור
name	String	שם פעולת ה-GraphQL. השם הזה לא קשור לשם שמופיע בזרימת ההודעות.
הגדרה	מחרוזת – פעולה	מציין שהפרמטר הזה מכיל את גוף ההודעה הראשי של בקשת השאילתה
operationType	שאילתה או מוטציה	סוג הפעולה שמבוצעת.
variableDefinition	מספר שלם	הם פועלים בדיוק כמו הגדרות הארגומנטים של פונקציה בשפה מוקלדת. היא מציגה רשימה של כל המשתנים, עם הקידומת $ ואחריהם הסוג שלהם.
הוראות	מספר שלם	‫@include ו-@skip הן שתי ההוראות שזמינות כרגע, שאפשר לסנן באמצעותן על סמך ערכים שמועברים באופן דינמי.
selectionSet	מספר שלם	קיבוץ לוגי ברמה אחת של כל המאפיינים שמשויכים לאובייקט.

ייצוג של הגדרות פרגמנט בזרימת ההודעות

שם המשתנה של זרימת ההודעות	סוג	תיאור
name	String	שם הפרגמנט.
הגדרה	מחרוזת – מקטע	מציין שגוף הבקשה הוא קטע מהבקשה הראשית.
typeCondition	String	התנאי שבו מופעלת הפונקציה.
variableDefinition	מספר שלם	הגדרת המשתנים שמועברת כארגומנטים לקטע.

דוגמאות לייצוגים של משתנים של זרימת הודעות

בדוגמאות הבאות מוצגים משתני זרימת ההודעות עבור מטען ייעודי (payload) של בקשות לדוגמה.

שאילתה לדוגמה 1

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

{
 employee(id: 123) {
   id
   firstName
   lastName
 }
}

בטבלה מוצגים הייצוגים המקבילים של משתני זרימת ההודעות.

משתנה של זרימת הודעות	ערך
graphql.operation.operationType	QUERY
graphql.fragment.count	1
graphql.operation.selectionSet.count	1
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.name	employee
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	id
graphql.operation.selectionSet.1.argument.1.value	IntValue{value=123}
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.selectionSet.count	3
graphql.operation.selectionSet.1.selectionSet.1.name	id
graphql.operation.selectionSet.1.selectionSet.2.name	firstName
graphql.operation.selectionSet.1.selectionSet.3.name	lastName

דוגמה לשאילתה 2

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

query Characters($episode: Episode, $withFriends: Boolean!) {
   friends @include(if: $withFriends) {
     friendsName
    }
}

בטבלה הבאה מוצגות הייצוגים של משתני זרימת ההודעות.

משתנה של זרימת הודעות	ערך
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	1
graphql.operation.name	Characters
graphql.fragment.count	0
graphql.operation.selectionSet.1.name	friends
graphql.operation.variableDefinitions.count	2
graphql.operation.variableDefinitions.1.name	episode
graphql.operation.variableDefinitions.1.type	TypeName{name='Episode'}
graphql.operation.variableDefinitions.2.name	withFriends
graphql.operation.variableDefinitions.2.type	NonNullType{type=TypeName{name='Boolean'}}
graphql.operation.selectionSet.1.argument.count	0
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	friendsName
graphql.operation.selectionSet.1.directive.count	1
graphql.operation.selectionSet.1.directive.1.argument.1.name	if
graphql.operation.selectionSet.1.directive.1.argument.1.value	VariableReference{name='withFriends'}

דוגמה לשאילתה 3

בדוגמה הזו יש הגדרת משתנה עם כינוי.

query getUsers {
  admins: users(role: ADMIN) {
    lastName
  }
  accountants: users(role: ACCOUNTANT) {
    firstName
  }
}

בטבלה הבאה מוצגות הייצוגים של משתני זרימת ההודעות.

משתנה של זרימת הודעות	ערך
graphql.operation.operationType	QUERY
graphql.operation.selectionSet.count	2
graphql.operation.selectionSet.1.name	users
graphql.operation.selectionSet.1.alias	admins
graphql.operation.variableDefinitions.count	0
graphql.operation.selectionSet.1.argument.count	1
graphql.operation.selectionSet.1.argument.1.name	role
graphql.operation.selectionSet.1.argument.1.value	EnumValue{name='ADMIN'}
graphql.operation.selectionSet.1.argument.2.name	null
graphql.operation.selectionSet.1.argument.2.value	null
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.count	1
graphql.operation.selectionSet.1.selectionSet.1.name	lastName
graphql.operation.selectionSet.1.selectionSet.1.alias	null
graphql.operation.selectionSet.1.selectionSet.2.name	null
graphql.operation.selectionSet.1.selectionSet.2.alias	null
graphql.operation.selectionSet.1.directive.count	0
graphql.operation.selectionSet.1.directive.1.argument.1.name	null
graphql.operation.selectionSet.1.directive.1.argument.1.value	null
graphql.operation.selectionSet.2.name	users
graphql.operation.selectionSet.2.alias	accountants
graphql.operation.selectionSet.2.argument.count	1
graphql.operation.selectionSet.2.argument.1.name	role
graphql.operation.selectionSet.2.argument.1.value	EnumValue{name='ACCOUNTANT'}
graphql.operation.selectionSet.2.selectionSet.count	1
graphql.operation.selectionSet.2.selectionSet.1.name	firstName
graphql.operation.selectionSet.2.directive.count	0
graphql.operation.selectionSet.2.selectionSet.1.alias	null
graphql.operation.selectionSet.2.selectionSet.2.name	null
graphql.operation.selectionSet.2.selectionSet.2.alias	null
graphql.operation.selectionSet.2.directive.count	0

נושאים קשורים

שימוש ב-GraphQL