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

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

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

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

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

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

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

מידע על המדיניות ExtensionCallout

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

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

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

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

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

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

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

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

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

הפניה לרכיב

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

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

רכיב <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 Extension מקבלת ערכים שמציינים את היומן שייכתב (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 של הלקוח שקורא ל-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 עם מירכאות סוגרות.

רכיב <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 -->

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

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

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

מאפייני <Output>

משתני זרימה

ללא.

קודי שגיאה

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

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

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

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

שגיאות פריסה

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