מדיניות GraphQL

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

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

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

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

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

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

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

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

רכיב <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>	אופציונלי	הגודל המקסימלי של מטען ייעודי (payload) בקילובייט.
<OperationType>	חובה	מציין את סוג הבקשה שאפשר לנתח: query,‏ mutation או query_mutation (כלומר, כל אחת מהאפשרויות).
<ResourceURL>	אופציונלי	תיאור. המיקום של קובץ סכימת GraphQL.
<Source>	חובה	request

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

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

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

<Action>

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

• ‫parse: Apigee מנתח את מטען ה-GraphQL הייעודי למשתני זרימת הודעות. במאמר דוגמאות לייצוג משתנים של זרימת הודעות מוסבר על המשתנים שמוגדרים כש-Action מוגדר כ-parse. כך אפשר לחסוך זמן יקר של מעבד (CPU) בקצה העורפי. שימו לב ש-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). אפשר להשתמש בזה כדי למנוע משרת ה-backend של GraphQL של הלקוח להריץ שאילתות מורכבות מאוד, וכך לאלץ את הלקוחות לפצל את הלוגיקה שלהם למטען נתונים קטן יותר.

ערך ברירת המחדל	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) בקילובייט. אפשר להשתמש בזה כדי להגביל את גודל המטען הייעודי (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