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

מוצג המסמך של 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, תוסף שנפרס עבור השירות הזה חייב להיות קיים בסביבה. פרטי התצורה כוללים בדרך כלל את המידע הנדרש לצמצום גישה למשאב, כמו מזהה פרויקט או שם חשבון.

שימוש במדיניות 'יתרונות מרכזיים' ב-PostClientFlow

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

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

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

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

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

הפניה לרכיב

<?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> מאפיינים

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

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

<DisplayName> רכיב

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

<DisplayName>Policy Display Name</DisplayName>

<Action> רכיב

הפעולה שנחשפת לתוסף שהמדיניות צריכה להפעיל.

<Action>action-exposed-by-extension</Action>

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

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

<מחבר> רכיב

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

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

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

&lt;Input&gt; רכיב

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

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

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

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

ערך הרכיב <Input> הוא בפורמט JSON תקין, שהמאפיינים שלו מציינים ערכים כדי לשלוח לפעולת התוסף ולהפעיל. לדוגמה, תוסף Google Cloud Logging הפעולה log של התוסף מקבלת ערכים שמציינים את היומן שבו יש לכתוב (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 של הלקוח שקורא לשרת ה-proxy ל-API:

<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 עם מירכאות כפולות.

&lt;Output&gt; רכיב

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

<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 -->

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

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

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

&lt;Output&gt; מאפיינים

משתני זרימה

ללא.

קודי שגיאה

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

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

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

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

שגיאות פריסה

השגיאות האלה עשויות להתרחש במהלך פריסת שרת proxy שמכיל את המדיניות הזו.