מדיניות בנושא IntegrationCallout

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

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

המדיניות IntegrationCallout מאפשרת להפעיל Application Integration עם טריגר API. עם זאת, לפני שמריצים שילוב, צריך להריץ את מדיניות SetIntegrationRequest. המדיניות SetIntegrationRequest יוצרת אובייקט בקשה והופכת את האובייקט לזמין למדיניות IntegrationCallout כמשתנה של זרימת נתונים. אובייקט הבקשה כולל את פרטי השילוב, כמו שם הטריגר של ה-API, מזהה פרויקט השילוב, שם השילוב ופרטים אחרים שהוגדרו במדיניות SetIntegrationRequest. המדיניות IntegrationCallout משתמשת במשתנה של אובייקט הבקשה כדי להריץ את האינטגרציה. אפשר להגדיר את המדיניות IntegrationCallout כדי לשמור את התגובה להרצת השילוב במשתנה של זרימת העבודה.

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

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

הערה: כדי להריץ את מדיניות IntegrationCallout, צריך אסימון אימות. עם זאת, אין רכיב Authentication מפורש בהגדרת המדיניות. Apigee מוסיף אסימון אימות לבקשה מאחורי הקלעים. כדי שמדיניות IntegrationCallout תאמת את עצמה בהצלחה, צריך לפרוס את proxy ל-API עם חשבון שירות שיש לו את תפקידי ה-IAM הנדרשים להרצת שילוב. מידע על התפקידים הנדרשים זמין במאמר תפקידי IAM לשילובים. פרטים נוספים על פריסת proxy ל-API זמינים במאמר פריסה ב-Apigee.

<IntegrationCallout>

מציינת את המדיניות IntegrationCallout.

ערך ברירת המחדל	לא רלוונטי
חובה?	חובה
סוג	סוג מורכב
רכיב אב	לא רלוונטי
רכיבי צאצא	<DisplayName> <AsyncExecution> <Request> <Response>

בטבלה הבאה מפורטים רכיבי המשנה של <IntegrationCallout>:

רכיב צאצא	חובה?	תיאור
<DisplayName>	אופציונלי	שם מותאם אישית למדיניות.
<AsyncExecution>	אופציונלי	המדיניות הזו קובעת אם השילוב צריך לפעול במצב סינכרוני או במצב אסינכרוני.
<Request>	חובה	משתנה ה-flow שמכיל את אובייקט הבקשה שנוצר על ידי מדיניות SetIntegrationRequest.
<Response>	אופציונלי	משתנה התהליך לשמירת התגובה של השילוב.

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

תחביר

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

דוגמה

בדוגמה הבאה מוצגת ההגדרה של מדיניות IntegrationCallout:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

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

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

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

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

<DisplayName>

אפשר להשתמש במאפיין הזה בנוסף למאפיין name כדי לתת למדיניות שם אחר, שנשמע יותר טבעי, ב-UI של עורך ה-proxy לניהול.

הרכיב <DisplayName> משותף לכל סוגי המדיניות.

ערך ברירת המחדל	לא רלוונטי
חובה?	זה שינוי אופציונלי. אם לא מציינים את <DisplayName>, המערכת משתמשת בערך של מאפיין name של המדיניות.
סוג	String
רכיב אב	<PolicyElement>
רכיבי צאצא	ללא

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

תחביר

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

דוגמה

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

לרכיב <DisplayName> אין מאפיינים או רכיבי צאצא.

<AsyncExecution>

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

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

• מצב אסינכרוני: כשהבקשה להפעלת השילוב מגיעה לנקודת הקצה, נקודת הקצה מחזירה מיד את מזהי ההפעלה של השילוב, אבל מתחילה את ההפעלה של השילוב בזמן שצוין ברכיב <ScheduleTime>. אם לא הגדרתם את הרכיב <ScheduleTime>, השילוב מתוזמן לפעול באופן מיידי. למרות שהשילוב מתוזמן לפעול באופן מיידי, יכול להיות שהביצוע שלו יתחיל אחרי כמה שניות. כשהשילוב מתחיל לפעול, קורים שני הדברים הבאים:
  • השילוב מחזיר את קוד הסטטוס של HTTP 200 OK כדי שהפונקציה שקוראת לשילוב תוכל להמשיך את העיבוד.
  • המדיניות IntegrationCallout הושלמה.
  אחרי שמתחילים, יש לסיים את ההפעלה של השילוב תוך 50 דקות לכל היותר.
• מצב סינכרוני: כשהבקשה להפעלת השילוב מגיעה לנקודת הקצה, נקודת הקצה מתחילה מיד בהפעלת השילוב וממתינה לתגובה. הזמן המקסימלי להשלמת ההפעלה הוא 2 דקות. אחרי סיום ההפעלה, נקודת הקצה מחזירה תגובה עם מזהי ההפעלה ונתוני תגובה אחרים.

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

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

תחביר

<AsyncExecution>BOOLEAN</AsyncExecution>

דוגמה

בדוגמה הבאה, הביצוע האסינכרוני מוגדר ל-true:

<AsyncExecution>true</AsyncExecution>

<Request>

מציין את משתנה הזרימה שמכיל את אובייקט הבקשה שנוצר על ידי מדיניות SetIntegrationRequest. המדיניות IntegrationCallout שולחת את אובייקט הבקשה הזה אל Application Integration כדי להפעיל את השילוב.

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

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

תחביר

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

דוגמה

בדוגמה הבאה מצוין שאובייקט הבקשה זמין במשתנה הזרימה my_request_flow_var:

<Request clearPayload="true">my_request_flow_var</Request>

בטבלה הבאה מתוארים המאפיינים של <Request>:

מאפיין	חובה?	סוג	תיאור
clearPayload	אופציונלי	בוליאני	מציין אם אובייקט הבקשה צריך להימחק מהזיכרון אחרי שליחת הבקשה להרצת השילוב. אם המאפיין מוגדר ל-true, ‏ Apigee מנקה את אובייקט הבקשה. אם המאפיין מוגדר ל-false, המערכת לא מנקה את אובייקט הבקשה. אם לא מציינים את המאפיין הזה, ערך ברירת המחדל הוא true ואובייקט הבקשה נמחק מהזיכרון.

<Response>

מציינים את משתנה התהליך לשמירת התגובה של השילוב.

אם לא מציינים את הרכיב הזה, המדיניות שומרת את התגובה במשתנה הזרימה integration.response.

ערך ברירת המחדל	integration.response
חובה?	אופציונלי
סוג	String
רכיב אב	<IntegrationCallout>
רכיבי צאצא	ללא

אפשר לגשת לפלט של השילוב באמצעות integration.response.content או flow_variable.content. רכיב <Response> משתמש בתחביר הבא:

תחביר

<Response>FLOW_VARIABLE_NAME</Response>

דוגמה

בדוגמה הבאה, התגובה של הרצת השילוב נשמרת במשתנה הזרימה my_response_flow_var:

<Response>my_response_flow_var</Response>

קודי שגיאה

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

שגיאות זמן ריצה

השגיאות האלה יכולות להתרחש כשהמדיניות מופעלת.

קוד תקלה	סטטוס HTTP	מטרה
entities.UnresolvedVariable	500	השגיאה הזו מתרחשת אם Apigee לא מצליח לפענח את המשתנים integration.project.id או integration.name.
steps.integrationcallout.ExecutionFailed	500	השגיאה הזו יכולה להתרחש אם שירות היעד בקצה העורפי מחזיר סטטוס שגיאת HTTP כמו 4xx או 5xx. הסיבות האפשריות כוללות: לחשבון השירות שנפרס עם ה-proxy יש הרשאות שגויות להפעלת השילוב. השילוב או הטריגר של ה-API לא קיימים. השילוב של אפליקציות לא מופעל בפרויקט שלכם ב-Google Cloud. הגדרתם את הרכיב <ScheduleTime> במדיניות SetIntegrationRequest, והרכיב AsyncExecution במדיניות IntegrationCallout מוגדר לערך false.
steps.integrationcallout.NullRequestVariable	500	השגיאה הזו מתרחשת אם משתנה הזרימה שצוין ב-<Request> הוא null.
steps.integrationcallout.RequestVariableNotMessageType	500	השגיאה הזו מתרחשת כשמשתנה הזרימה שצוין ברכיב Request הוא לא מסוג message.
steps.integrationcallout.RequestVariableNotRequestMessageType	500	השגיאה הזו מתרחשת כשמשתנה הזרימה שצוין ברכיב Request הוא לא מסוג Request message.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure	500	השגיאה הזו יכולה להתרחש בגלל הגדרה שגויה של חשבון שירות. הסיבות האפשריות לכך: חשבון השירות שנפרס באמצעות ה-proxy לא קיים בפרויקט. חשבון השירות שנפרס עם ה-proxy מושבת.

משתני תקלות

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

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

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

משתנים	כאשר:	דוגמה
fault.name	הערך fault.name יכול להתאים לכל אחת מהתקלות שמופיעות בטבלה שגיאות בזמן ריצה. שם התקלה הוא החלק האחרון של קוד התקלה.	fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed	‫POLICY_NAME הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה.	IntegrationCallout.integration-callout-1.failed = true

מידע נוסף על שגיאות שקשורות למדיניות זמין במאמר מה צריך לדעת על שגיאות שקשורות למדיניות.

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

מידע נוסף על התכונה Application Integration זמין במאמר בנושא סקירה כללית של Application Integration