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

כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של Apigee X. מידע

משתמשים במדיניות של 'יתרונות מרכזיים של תוסף' כדי לשלב תוסף בשרת proxy ל-API.

תוסף מספק גישה למשאב ספציפי מחוץ ל-Apigee Edge. מקור המידע יכול להיות שירותי Google Cloud Platform כמו Cloud Storage או Cloud Speech-to-Text. עם זאת, המשאב יכול להיות כל משאב חיצוני שאפשר לגשת אליו באמצעות HTTP או HTTPS.

סקירה כללית של תוספים זמינה במאמר מהם תוספים? לקבלת מדריך מבוא, אפשר לעיין במאמר מדריך: הוספת תוסף ושימוש בו.

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

טעימות

זוהי דוגמה למדיניות לשימוש עם התוסף Cloud Logging:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

למדריך המלא על השימוש בתוסף Cloud Logging, קראו את המדריך: שימוש בתוספים.

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

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

יש להשתמש במדיניות 'יתרונות מרכזיים של תוסף' כשרוצים להשתמש בתוסף מוגדר כדי לגשת למשאב חיצוני מתוך שרת proxy של API.

כדי להשתמש במדיניות הזו, צריך:

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

שימוש במדיניות ExtensionExtension ב-PostClientFlow

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

אם רוצים להשתמש במדיניות ExtensionExtension כדי לקרוא לתוסף Google Cloud Logging מ-PostClientFlow, חשוב לוודא שהדגל features.allowExtensionsInPostClientFlow מוגדר לערך true בארגון שלכם.

  • ללקוחות Apigee Edge ב-Public Cloud, הדגל features.allowExtensionsInPostClientFlow מוגדר כברירת מחדל ל-true.

  • אם אתם לקוחות של Apigee Edge לענן פרטי, תוכלו להשתמש ב-API של עדכון מאפייני הארגון כדי להגדיר את הדגל features.allowExtensionsInPostClientFlow ל-true.

כל ההגבלות על קריאה למדיניות MessageLogging מ-PostClientFlow חלות גם על המדיניות ExtensionExtension. מידע נוסף זמין בקטע הערות שימוש.

הפניה לרכיב

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

מאפיינים של <הסבר על המחבר>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

מאפיין התיאור ברירת המחדל נוכחות
name

השם הפנימי של המדיניות. הערך של המאפיין name יכול להכיל אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך יכול להיות באורך של עד 255 תווים.

אפשר להשתמש באלמנט <DisplayName> כדי להוסיף למדיניות בכלי לעריכת שרת ה-proxy לניהול ממשק משתמש עם שם בשפה טבעית אחרת.

 לא רלוונטי נדרש
continueOnError

צריך להגדיר את הערך false כדי להחזיר שגיאה במקרה של כישלון במדיניות. זו התנהגות צפויה ברוב כללי המדיניות.

צריך להגדיר את הערך true כדי להפעיל את התהליך גם אחרי כישלון במדיניות.

 false אופציונלי
enabled

צריך להגדיר את הערך true כדי לאכוף את המדיניות.

צריך להגדיר את הערך false כדי להשבית את המדיניות. המדיניות לא תיאכף גם אם היא תישאר מצורפת לזרימה.

 true אופציונלי
async

המאפיין הזה הוצא משימוש.

 false הוצא משימוש

רכיב <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>
ברירת המחדל

לא רלוונטי

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

רכיב <Action>

הפעולה שתחול בעקבות החשיפה של התוסף, שעל המדיניות להפעיל.

<Action>action-exposed-by-extension</Action>
ברירת המחדל ללא
נוכחות נדרש
תיאור מחרוזת

כל תוסף חושף קבוצת פעולות משלו שמאפשרות גישה לפונקציונליות של המשאב שהתוסף מייצג. אפשר לחשוב על פעולה כפונקציה שאתם מפעילים באמצעות המדיניות הזו, ולהשתמש בתוכן של הרכיב <Input> כדי לציין את הארגומנטים של הפונקציה. התגובה של הפעולה נשמרת במשתנה שציינתם באמצעות הרכיב <Output>.

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

רכיב <Connector>

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

<Connector>name-of-configured-extension</Connector>

ברירת המחדל ללא
נוכחות נדרש
תיאור מחרוזת

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

רכיב <input>

קובץ JSON שמכיל את גוף הבקשה לשליחה לתוסף.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

ברירת המחדל ללא
נוכחות אופציונלי או חובה, בהתאם לתוסף.
תיאור מחרוזת

זהו למעשה ארגומנט לפעולה שאתם מציינים באמצעות הרכיב <Action>. הערך של הרכיב <Input> ישתנה בהתאם לתוסף ולפעולה שרוצים להפעיל. בתיעוד של חבילת התוספים אפשר לקרוא פרטים על המאפיינים של כל פעולה.

חשוב לשים לב: למרות שערכים רבים של רכיבי <Input> יפעלו כראוי מבלי להיות מוקפים כקטע <![CDATA[]]>, כללי JSON מאפשרים להציג ערכים שלא ינותחו כ-XML. מומלץ להקיף את קובץ ה-JSON כקטע CDATA כדי למנוע שגיאות בניתוח בזמן הריצה.

ערך הרכיב <Input> הוא בפורמט JSON, ובמאפיינים שלו מצוינים ערכים לשליחה לפעולת התוסף להפעלה. לדוגמה, הפעולה log של התוסף Google Cloud Logging מקבלת ערכים שמציינים את היומן שאליו צריך לכתוב (logName), את המטא-נתונים שייכללו ברשומה (metadata) ואת הודעת היומן (data). לדוגמה:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

שימוש במשתני זרימה בקובץ JSON של <Input>

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

לדוגמה, אפשר לשכתב את הבלוק הקודם של <Input> כך שישתמש במשתנה התהליך client.ip כדי לקבל את כתובת ה-IP של הלקוח שקורא לשרת ה-API של שרת ה-proxy:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

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

הדוגמה הבאה של <Input> כוללת שתי הפניות של משתני זרימה:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

בזמן הריצה, ערכי המאפיין JSON ייקבעו באופן הבא:

  • ערך המאפיין logName – ליטרל המחרוזת example-log.
  • ערך המאפיין metadata – הערך של משתנה הזרימה my.log.entry.metadata בלי לתחום במירכאות. זו יכולה להיות אפשרות שימושית אם ערך המשתנה הוא עצמו JSON שמייצג אובייקט.
  • ערך המאפיין message -- הערך של משתנה הזרימה client.ip עם מירכאות בסוגריים.

רכיב <Output>

שם המשתנה שמאחסן את התשובה של פעולת התוסף.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

או

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

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

כשהתגובה מתקבלת, ערך התגובה ימוקם במשתנה שציינתם כאן, ותוכלו לגשת אליו מקוד אחר של שרת proxy של API.

אובייקטים של תגובות של תוספים הם בפורמט JSON. יש שתי אפשרויות לטיפול במדיניות ב-JSON:

  • ניתוח (ברירת המחדל): המדיניות מנתחת את אובייקט ה-JSON ויוצרת באופן אוטומטי משתנים עם נתוני ה-JSON. לדוגמה, אם ה-JSON מכיל "messageId" : 12345; ואת השם של משתנה הפלט שלכם: extensionOutput, תוכלו לגשת למזהה ההודעה הזה בכללי מדיניות אחרים באמצעות המשתנה {extensionOutput.messageId}.
  • לא נותחו: משתנה הפלט מכיל את תגובת JSON הגולמית שלא נותחה מהתוסף. (אם תרצו, עדיין תוכלו לנתח את ערך התשובה בשלב נפרד באמצעות מדיניות JavaScript).

מאפיינים <Output>

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

משתני זרימה

ללא.

קודי שגיאה

השגיאות שהוחזרו ממדיניות Apigee Edge הן בפורמט עקבי, כפי שמתואר בחומר העזר בנושא שגיאות מדיניות.

This section describes the error messages and flow variables that are set when this policy triggers an error. This information is important to know if you are developing fault rules for a proxy. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Error name HTTP status Cause
ExecutionFailed 500 The extension responds with an error.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Occurs when Fix
InvalidConnectorInstance The <Connector> element is empty.
ConnectorInstanceDoesNotExists The Extension specified in the <Connector> element does not exist in the environment.
InvalidAction The <Action> element in the ExtensionCallout policy is missing or set to an empty value.
AllowExtensionsInPostClientFlow It is prohibited to have ExtensionCallout policy in a PostClient Flow.