מדיניות 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