‫ServiceCallout policy

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

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

לעיון במסמכי התיעוד של Apigee Edge

מדיניות ServiceCallout מאפשרת לכם לבצע קריאה לשירות אחר מתוך זרימת ה-proxy ל-API. אתם יכולים לבצע קריאות לשירות חיצוני (כמו נקודת קצה חיצונית של שירות RESTful) או לשירותים פנימיים (כמו proxy ל-API באותו ארגון ובאותה סביבה).

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

  • בתרחיש שימוש חיצוני, אתם מבצעים קריאה ל-API של צד שלישי שנמצא מחוץ ל-proxy ל-API. התגובה מ-API של הצד השלישי מנותחת ומוכנסת להודעת התגובה של ה-API, וכך מתבצע mashup של הנתונים עבור משתמשי הקצה של האפליקציה. אפשר גם לשלוח בקשה באמצעות מדיניות ServiceCallout בזרימת הבקשות, ואז להעביר את המידע בתגובה אל TargetEndpoint של proxy ל-API.
  • בתרחיש שימוש אחר, אתם קוראים לשרת proxy שנמצא באותו ארגון ובאותה סביבה שבה נמצא השרת שממנו אתם קוראים. לדוגמה, יכול להיות שהשימוש בזה יהיה שימושי אם יש לכם שרת proxy שמציע פונקציונליות נפרדת ברמה נמוכה, ששרת proxy אחד או יותר ישתמשו בה. לדוגמה, שרת proxy שחושף פעולות של יצירה, קריאה, עדכון ומחיקה עם מאגר נתונים בעורף יכול להיות שרת ה-proxy היעד של כמה שרתי proxy אחרים שחושפים את הנתונים ללקוחות.

המדיניות תומכת בבקשות באמצעות HTTP ו-HTTPS.

דוגמאות

שיחה מקומית לשרת proxy פנימי

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

בדוגמה הזו נוצרת קריאה לשרת proxy מקומי של API (כלומר, שרת proxy באותו ארגון ובאותה סביבה) שנקרא data-manager, ומצוינת נקודת הקצה של ה-proxy ששמה הוא default.

כתובת URL כמשתנה

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

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

בקשת מיקום גיאוגרפי של Google / בקשת הגדרה

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

במקום להשתמש במדיניות כמו AssignMessage policy כדי ליצור את אובייקט הבקשה, אפשר להגדיר אותו ישירות במדיניות ServiceCallout. בדוגמה הזו, מדיניות ServiceCallout מגדירה את הערכים של שלושה פרמטרים של שאילתה שמועברים לשירות החיצוני. אפשר ליצור הודעת בקשה שלמה במדיניות ServiceCallout שמציינת מטען ייעודי (payload), סוג קידוד כמו application/xml, כותרות, פרמטרים של טופס וכו'.

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

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>https://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

התוכן של הודעת הבקשה מחולץ ממשתנה שנקרא GeocodingRequest (יכול להיות שהוא יאוכלס, למשל, על ידי מדיניות AssignMessage). הודעת התגובה מוקצית למשתנה שנקרא GeocodingResponse, שבו היא זמינה לניתוח על ידי מדיניות ExtractVariables או על ידי קוד מותאם אישית שנכתב ב-JavaScript או ב-Java. המדיניות ממתינה 30 שניות לתשובה מ-Google Geocoding API לפני שהיא פוסקת.

התקשרות לשרתי יעד

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

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

מידע על מדיניות ServiceCallout

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

בדרך כלל משתמשים ב-callout בשילוב עם שתי מדיניות אחרות: AssignMessage ו-ExtractVariables.

  • ‫Request: רכיב AssignMessage מאכלס את הודעת הבקשה שנשלחת לשירות המרוחק.

  • תשובה: הרכיב ExtractVariables מנתח את התשובה ומחלץ ממנה תוכן ספציפי.

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

  1. מדיניות AssignMessage: יוצרת הודעת בקשה, מאכלסת כותרות HTTP, פרמטרים של שאילתה, מגדירה את פועל ה-HTTP וכו'.

  2. מדיניות ServiceCallout: מפנה להודעה שנוצרה על ידי מדיניות AssignMessage, מגדירה כתובת URL של יעד לקריאה החיצונית ומגדירה שם לאובייקט התגובה שהשירות של היעד מחזיר.

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

  3. ‫ExtractVariables policy: בדרך כלל מגדיר ביטוי JSONPath או XPath שמנתח את ההודעה שנוצרה על ידי ServiceCallout. לאחר מכן המדיניות מגדירה משתנים שמכילים את הערכים שנותחו מהתגובה של ServiceCallout.

טיפול מותאם אישית בשגיאות

הפניה לרכיב

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

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleAccessToken>
            <Scopes>
              <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
            </Scopes>
            <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds>
          </GoogleAccessToken>
        </Authentication>
        <Authentication>
          <HeaderName ref="{variable}">STRING</HeaderName>
          <GoogleIDToken>
            <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience>
            <IncludeEmail ref="{variable}">true</IncludeEmail>
          </GoogleIDToken>
        </Authentication>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

מאפיינים של <ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

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

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

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

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

 לא רלוונטי חובה
continueOnError

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

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

 FALSE אופציונלי
enabled

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

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

 TRUE אופציונלי
async

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

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

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

לא רלוונטי

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

אלמנט <Request>

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

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

התחביר של התגים <Remove>,‏ <Copy>,‏ <Add> ו-<Set> זהה לתחביר של מדיניות AssignMessage.

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

בדוגמה הפשוטה ביותר, מעבירים משתנה שמכיל את הודעת הבקשה שאוכלסה בשלב מוקדם יותר בתהליך של proxy ל-API:

<Request clearPayload="true" variable="myRequest"/>

אפשר גם לאכלס את הודעת הבקשה שנשלחת לשירות החיצוני במדיניות ServiceCallout עצמה:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
ברירת מחדל אם משמיטים את רכיב Request או את אחד המאפיינים שלו, מערכת Apigee מקצה את ערכי ברירת המחדל הבאים:

<Request clearPayload="true" variable="servicecallout.request"/>

נבחן את משמעות ערכי ברירת המחדל האלה. קודם כל, clearPayload=true אומר שכל פעם שמדיניות ServiceCallout מופעלת, נוצר אובייקט בקשה חדש. כלומר, הבקשה ונתיב ה-URI של הבקשה אף פעם לא מנוצלים מחדש. שנית, שם המשתנה שמוגדר כברירת מחדל, servicecallout.request, הוא שם שמור שמוקצה לבקשה אם לא מספקים שם.

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

servicecallout.request.header.Authorization.
נוכחות זה שינוי אופציונלי.
סוג לא רלוונטי

מאפיינים

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

שם המשתנה שיכיל את הודעת הבקשה.

 servicecallout.request אופציונלי
clearPayload

אם true, המשתנה שמכיל את הודעת הבקשה מנוקה אחרי שהבקשה נשלחת ליעד ה-HTTP, כדי לפנות את הזיכרון שבו נעשה שימוש בהודעת הבקשה.

מגדירים את האפשרות clearPayload כ-false רק אם נדרשת הודעת הבקשה אחרי ההפעלה של ServiceCallout.

 TRUE אופציונלי

אלמנט <Request>/<IgnoreUnresolvedVariables>

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

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
ברירת מחדל FALSE
נוכחות אופציונלי
סוג בוליאני

אלמנט <Response>

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

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

אם משמיטים את הרכיב הזה, שרת ה-API Proxy לא ממתין לתשובה, והביצוע של זרימת ה-API Proxy ממשיך עם כל השלבים הבאים בזרימה. בנוסף, ברור שאם לא מציינים את הרכיב Response, התשובה מהיעד לא זמינה לעיבוד בשלבים הבאים, ואין דרך שזרימת ה-Proxy תזהה כשל בקריאה מרחוק. שימוש נפוץ בהשמטת הרכיב Response כשמשתמשים ב-ServiceCallout: רישום הודעות במערכת חיצונית.

 <Response>calloutResponse</Response>
ברירת מחדל לא זמין
נוכחות אופציונלי
סוג String

אלמנט <Timeout>

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

<Timeout>30000</Timeout>
ברירת מחדל ‫55,000 אלפיות השנייה (55 שניות), הגדרת ברירת המחדל של הזמן הקצוב לתפוגה של HTTP ב-Apigee
נוכחות אופציונלי
סוג מספר שלם

אלמנט <HTTPTargetConnection>

מספק פרטים על ההעברה, כמו כתובת URL, ‏ TLS/SSL ומאפייני HTTP. אפשר לעיין בהפניה להגדרות של <TargetEndpoint>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג לא רלוונטי

אלמנט <HTTPTargetConnection>/<Authentication>

יצירת אסימונים של Google OAuth 2.0 או אסימונים של OpenID Connect שהונפקו על ידי Google, כדי לבצע קריאות מאומתות לשירותי Google ולשירותים בהתאמה אישית שפועלים במוצרי Google Cloud מסוימים, כמו Cloud Functions ו-Cloud Run. כדי להשתמש ברכיב הזה, צריך לבצע את שלבי ההגדרה והפריסה שמתוארים במאמר בנושא שימוש באימות של Google. אם המדיניות מוגדרת בצורה נכונה, היא יוצרת טוקן אימות ומוסיפה אותו לבקשת השירות.

רכיבי הצאצא, GoogleAccessToken ו-GoogleIDToken, מאפשרים להגדיר את המדיניות כך שתפיק טוקנים של Google OAuth או OpenID Connect. צריך לבחור אחד מרכיבי הצאצא האלה בהתאם לסוג השירות שרוצים להפעיל.

המדיניות ServiceCallout תומכת רק בקריאה לשירותים מבוססי HTTP.

ברירת מחדל לא רלוונטי
חובה? זה שינוי אופציונלי.
סוג סוג מורכב
רכיב אב <HTTPTargetConnection>
רכיבי צאצא <HeaderName>
<GoogleAccessToken>
<GoogleIDToken>

רכיב Authentication משתמש בתחביר הבא:

תחביר

<ServiceCallout>
...
  <HTTPTargetConnection>
    <Authentication>
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleAccessToken>
        <Scopes>
          <Scope>SCOPE</Scope>
          ...
        </Scopes>
        <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only
        if you want to limit the risk of leaked access tokens or improve performance. -->
        <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds>
      </GoogleAccessToken>

    --OR--
      <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
      <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
      </GoogleIDToken>
    </Authentication>
  </HTTPTargetConnection>
</ServiceCallout>

שימוש ב-GoogleAccessToken

בדוגמה הבאה מוצג הרכיב GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

שימוש ב-GoogleIDToken

בדוגמה הבאה מוצג הרכיב GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>false</IncludeEmail>
  </GoogleIDToken>
</Authentication>

שימוש ב-HeaderName

בדוגמה הבאה מוצג הרכיב HeaderName:

  <Authentication>
    <HeaderName>X-Serverless-Authorization</HeaderName>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
    </GoogleAccessToken>
  </Authentication>

שימוש ב-LifetimeInSeconds

בדוגמה הבאה מוצג הרכיב HeaderName:

  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
      </Scopes>
      <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>

מאפיינים

אין.

רכיב צאצא HeaderName

כברירת מחדל, כשקיימת הגדרת אימות, Apigee יוצר אסימון bearer ומזריק אותו לכותרת Authorization בהודעה שנשלחת למערכת היעד. רכיב HeaderName מאפשר לציין את השם של כותרת אחרת שתכיל את אסימון ה-Bearer. התכונה הזו שימושית במיוחד כשמטרת הבקשה היא שירות Cloud Run שמשתמש בכותרת X-Serverless-Authorization. הכותרת Authorization, אם היא קיימת, לא משתנה ונשלחת גם היא בבקשה.

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

רכיב HeaderName משתמש בתחביר הבא:

תחביר

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

עם מחרוזת סטטית

בדוגמה הזו, אסימון ה-bearer שנוצר מתווסף כברירת מחדל לכותרת בשם X-Serverless-Authorization שנשלחת למערכת היעד. הכותרת Authorization, אם היא קיימת, לא משתנה ונשלחת גם היא בבקשה.

<Authentication>
  <HeaderName>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

עם הפניה למשתנה

בדוגמה הזו, אסימון ה-Bearer שנוצר נוסף כברירת מחדל לכותרת בשם X-Serverless-Authorization שנשלחת למערכת היעד. אם ל-my-variable יש ערך, המערכת תשתמש בערך הזה במקום במחרוזת ברירת המחדל. הכותרת Authorization, אם היא קיימת, לא משתנה ונשלחת גם היא בבקשה.

<Authentication>
  <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

רכיב צאצא GoogleAccessToken

יצירת אסימונים של Google OAuth 2.0 כדי לבצע קריאות מאומתות לשירותי Google. אפשר להשתמש באסימוני Google OAuth כדי לקרוא לשירותים רבים של Google, כמו Cloud Logging ו-Secret Manager.

ברירת מחדל לא רלוונטי
חובה? צריך להוסיף את רכיב הבן GoogleAccessToken או GoogleIDToken.
סוג String
רכיב אב <Authentication>
רכיבי צאצא <Scopes>
<LifetimeInSeconds>

רכיב GoogleAccessToken משתמש בתחביר הבא:

תחביר

<ServiceCallout>
...
  <Authentication>
    <GoogleAccessToken>
      <Scopes>
        <Scope>SCOPE_1</Scope>
        ...
      </Scopes>
      <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
      the default unless you want to limit the risk of leaked access tokens or improve performance. -->
      <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

דוגמה 1

בדוגמה הבאה מוצג הרכיב GoogleAccessToken:

<Authentication>
  <GoogleAccessToken>
    <Scopes>
      <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
    </Scopes>
  </GoogleAccessToken>
</Authentication>

דוגמה 2

בדוגמה הבאה מוצג איך להתחבר ל-Secret Manager כדי לאחזר סוד באמצעות מדיניות ServiceCallout. 

<ServiceCallout name="ServiceCallout-sm">
  <Response>SecretManagerResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleAccessToken>
        <Scopes>
          <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
      </GoogleAccessToken>
    </Authentication>
    <URL>
      https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
    </URL>
  </HTTPTargetConnection>
</ServiceCallout>

דוגמה 3

בדוגמה הבאה מוצג איך לבצע קריאה ל-Cloud Run ממדיניות ServiceCallout. 

<ServiceCallout name="ServiceCallout-CloudRun">
  <Response>CloudRunResponse</Response>
  <Timeout>30000</Timeout>
  <HTTPTargetConnection>
    <Authentication>
      <GoogleIDToken>
        <Audience>https://cloudrun-hostname.a.run.app/test</Audience>
      </GoogleIDToken>
    </Authentication>
    <URL>https://cloudrun-hostname.a.run.app/test</URL>
  </HTTPTargetConnection>
</ServiceCallout>

אלמנט צאצא של Scopes

מזהה את ההיקפים שייכללו באסימון הגישה מסוג OAuth 2.0. מידע נוסף זמין במאמר היקפי OAuth 2.0 ל-Google APIs. אפשר להוסיף רכיב צאצא אחד או יותר <Scope> מתחת לרכיב הזה.

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

רכיב צאצא של היקף ההרשאות

מציין היקף הרשאות תקין ל-Google API. מידע נוסף זמין במאמר היקפי OAuth 2.0 ל-Google APIs.

ברירת מחדל לא רלוונטי
חובה? צריך להזין לפחות ערך אחד.
סוג String
רכיב אב <Scopes>
רכיבי צאצא אין.

רכיב הצאצא LifetimeInSeconds

מציין את משך החיים של אסימון הגישה בשניות.

ברירת מחדל 3600
חובה? אופציונלי
סוג מספר שלם
רכיב אב <GoogleAccessToken>
רכיבי צאצא אין.

רכיב צאצא של GoogleIDToken

יצירת אסימונים של OpenID Connect שהונפקו על ידי Google כדי לבצע קריאות מאומתות לשירותי Google.

ברירת מחדל לא רלוונטי
חובה? צריך להוסיף את רכיב הבן GoogleAccessToken או GoogleIDToken.
סוג String
רכיב אב <Authentication>
רכיבי צאצא <Audience>
<IncludeEmail>

רכיב GoogleIDToken משתמש בתחביר הבא:

תחביר

<ServiceCallout>
...
  <Authentication>
    <GoogleIDToken>
        <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience>
        <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail>
    </GoogleIDToken>
  </Authentication>
</ServiceCallout>

דוגמה 1

בדוגמה הבאה מוצג הרכיב GoogleIDToken:

<Authentication>
  <GoogleIDToken>
      <Audience>https://httpserver0-bar.run.app</Audience>
      <IncludeEmail>true</IncludeEmail>
  </GoogleIDToken>
</Authentication>

רכיב צאצא של קהל

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

אם הערך של Audience ריק או שהמשתנה ref לא מתפרש כערך תקין, וגם useTargetUrl הוא true, כתובת ה-URL של היעד (לא כולל פרמטרים של שאילתה) משמשת כקהל. ערך ברירת המחדל של useTargetUrl הוא false. 

<Audience>explicit-audience-value-here</Audience>

or:

<Audience ref='variable-name-here'/>

or:

<Audience ref='variable-name-here' useTargetUrl='true'/>

or:

<Audience useTargetUrl='true'/>
ברירת מחדל לא רלוונטי
חובה? חובה
סוג String
רכיב אב <GoogleIDToken>
רכיבי צאצא אין.

רכיב צאצא IncludeEmail

אם הערך הוא true, אסימון האימות שנוצר יכיל את הטענות email ו-email_verified של חשבון השירות.

ברירת מחדל FALSE
חובה? אופציונלי
סוג בוליאני
רכיב אב <GoogleIDToken>
רכיבי צאצא אין.

אלמנט <HTTPTargetConnection>/<URL>

כתובת ה-URL של השירות שאליו מתבצעת הקריאה:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

אפשר לספק חלק מכתובת ה-URL באופן דינמי באמצעות משתנה. עם זאת, אי אפשר לציין משתנה לחלק של הפרוטוקול בכתובת ה-URL, http://‎ שמופיע למטה. בדוגמה הבאה, משתמשים במשתנה כדי לציין את הערך של פרמטר בשאילתה:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

אפשר גם להגדיר חלק מנתיב כתובת ה-URL באמצעות משתנה:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

אם רוצים להשתמש במשתנה כדי לציין את הדומיין והיציאה של כתובת ה-URL, צריך להשתמש במשתנה אחד רק לדומיין וליציאה, ובמשתנה שני לכל חלק אחר של כתובת ה-URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג String

אלמנט <HTTPTargetConnection>/<SSLInfo>

הגדרת TLS/SSL לשירות לקצה העורפי. לקבלת עזרה בהגדרת TLS/SSL, אפשר לעיין באפשרויות להגדרת TLS ובקטע 'הגדרת TargetEndpoint של TLS/SSL' בהפניה להגדרת proxy ל-API.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

אלמנט <HTTPTargetConnection>/<Properties>

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

אלמנט <HTTPTargetConnection>/<LoadBalancer>

להתקשר לשרת יעד אחד או יותר ולבצע איזון עומסים בשרתים האלה. אפשר לעיין בדוגמה Call target servers בקטע הדוגמאות. מידע נוסף זמין במאמר בנושא איזון עומסים בין שרתים בעורף המערכת. אפשר גם לעיין במאמר Target Endpoint/Server callout שמתאר דרכים להפעלת שרתים של יעד גם ממדיניות ServiceCallout וגם באמצעות כללי ניתוב.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

אלמנט <LocalTargetConnection>

הגדרה של שרת proxy מקומי – כלומר, שרת proxy באותו ארגון ובאותה סביבה – כיעד של קריאות שירות.

כדי לציין עוד יותר את היעד, משתמשים ברכיבים <APIProxy> ו-<ProxyEndpoint> או ברכיב <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג לא רלוונטי

אלמנט <LocalTargetConnection>/<APIProxy>

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

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

בנוסף לרכיב <APIProxy>, צריך לכלול את הרכיב <ProxyEndpoint> כדי לציין את שם נקודת הקצה של ה-proxy שאליה צריך להפנות את הקריאה.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג String

אלמנט <LocalTargetConnection>/<ProxyEndpoint>

השם של נקודת הקצה של ה-proxy שאליה צריכות להיות מופנות הקריאות. זוהי נקודת קצה של proxy ב-API proxy שצוין באמצעות הרכיב <APIProxy>.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

אלמנט <LocalTargetConnection>/<Path>

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

אפשר להשתמש בזה במקום בצמד <APIProxy>/<ProxyEndpoint> כשלא יודעים את שם ה-proxy או כשאי אפשר להסתמך עליו. יכול להיות שהנתיב הוא יעד אמין.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג לא רלוונטי

סכימות

משתנים בתהליך

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

ל-ServiceCallouts יש בקשה ותגובה משלהן, ואפשר לגשת לנתונים האלה באמצעות משתנים. מכיוון שההודעה הראשית משתמשת בקידומות המשתנים request.* ו-response.*, צריך להשתמש בקידומות myrequest.* ו-calloutResponse.* (ברירות המחדל בהגדרות של ServiceCallout) כדי לקבל נתוני הודעה שספציפיים ל-ServiceCallout. בדוגמה הראשונה בטבלה הבאה מוצג איך מקבלים כותרות HTTP ב-ServiceCallout.

משתנה תיאור

הדוגמה הבאה מראה איך מקבלים את הכותרות של הבקשות והתשובות של ServiceCallout, בדומה לאופן שבו מקבלים את הכותרות מהבקשה והתשובה העיקריות.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

כאשר calloutResponse הוא שם המשתנה של התגובה ב-Service Callout, ו-myRequest הוא שם המשתנה של הבקשה. לדוגמה:

calloutResponse.header.Content-Length

מחזירה את כותרת Content-Length של תגובת ServiceCallout.

היקף: מ-ServiceCallout קדימה
סוג: מחרוזת
הרשאה: קריאה/כתיבה

כותרת של הודעה בבקשה או בתשובה של ServiceCallout. לדוגמה, אם יעד ה-API Proxy הוא http://example.com, ויעד ה-ServiceCallout הוא http://mocktarget.apigee.net, המשתנים האלה הם הכותרות של ה-callout אל http://mocktarget.apigee.net.
servicecallout.requesturi

היקף: מבקשת ServiceCallout ואילך
סוג: מחרוזת
הרשאה: קריאה/כתיבה

מזהה המשאבים האחיד (URI) של TargetEndpoint למדיניות ServiceCallout. ה-URI הוא כתובת ה-URL של TargetEndpoint בלי הפרוטוקול והגדרת הדומיין.
servicecallout.{policy-name}.target.url

היקף: מבקשת ServiceCallout ואילך
סוג: מחרוזת
הרשאה: קריאה/כתיבה

כתובת היעד של רכיב ServiceCallout.

calloutResponse.content

כאשר calloutResponse הוא <Response>שם המשתנה בהגדרות של ServiceCallout.

היקף: החל מהתגובה של ServiceCallout
סוג: מחרוזת
הרשאה: קריאה/כתיבה

גוף התגובה מ-ServiceCallout.
servicecallout.{policy-name}.expectedcn

היקף: מבקשת ServiceCallout ואילך
סוג: מחרוזת
הרשאה: קריאה/כתיבה

השם הנפוץ הצפוי של TargetEndpoint, כפי שמצוין במדיניות ServiceCallout. ההגדרה הזו רלוונטית רק כש-TargetEndpoint מתייחס לנקודת קצה של TLS/SSL.
servicecallout.{policy-name}.failed

היקף: מהתגובה של ServiceCallout ואילך
סוג: בוליאני
הרשאה: קריאה/כתיבה

ערך בוליאני שמציין אם המדיניות הצליחה (False) או נכשלה (True).

שגיאות

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

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

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

קוד תקלה סטטוס HTTP מטרה תיקון
steps.servicecallout.ExecutionFailed 500

השגיאה הזו יכולה להופיע אם:

  • המדיניות מתבקשת לטפל בקלט שהפורמט שלו שגוי או שהוא לא תקין מסיבה אחרת.
  • שירות היעד בעורף האתר מחזיר סטטוס שגיאה (כברירת מחדל, 4xx או 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 המשתנה Request שצוין במדיניות הוא לא מסוג Message. לדוגמה, אם מדובר במחרוזת או בסוג אחר שאינו הודעה, תוצג השגיאה הזו.
steps.servicecallout.RequestVariableNotRequestMessageType 500 המשתנה Request שצוין במדיניות הוא לא מסוג RequestMessage. לדוגמה, אם מדובר בסוג תגובה, תופיע השגיאה הזו.
googletoken.EmptyIDTokenAudience 500

המאפיין <GoogleIDToken> מופעל אבל המאפיין useTargetUrl מוגדר לערך false ולא צוין ערך למאפיין <Audience> ישירות או באמצעות הפניה בזמן השגיאה.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 השגיאה הזו יכולה לקרות אם proxy ל-API מוגדר עם הרכיב <Authentication>‎. הסיבות האפשריות כוללות:
  • חשבון השירות שנפרס עם ה-proxy:
    • לא קיים בפרויקט
    • הושבת
    • (רק ב-Apigee hybrid) לא הוקצה התפקיד roles/iam.serviceAccountTokenCreator בחשבון השירות apigee-runtime.
  • ממשק IAMCredentials API מושבת בפרויקט המקור של חשבון השירות apigee-runtime.
  • נעשה שימוש ברכיב <GoogleAccessToken> וצוין היקף לא תקין אחד או יותר. לדוגמה, צריך לחפש שגיאות הקלדה או היקפים ריקים.

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

    שגיאות בהטמעה

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

    שם השגיאה מטרה תיקון
    URLMissing הרכיב <URL> בתוך <HTTPTargetConnection> חסר או ריק.
    ConnectionInfoMissing השגיאה הזו מתרחשת אם במדיניות אין רכיב <HTTPTargetConnection> או <LocalTargetConnection>.
    InvalidTimeoutValue השגיאה הזו מתרחשת אם הערך של <Timeout> הוא שלילי או אפס.
    FAILED_PRECONDITION השגיאה הזו מתרחשת אם חשבון השירות חסר כשמגדירים את ה-proxy באמצעות התג <Authentication>.

    לדוגמה: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED השגיאה הזו מתרחשת אם יש בעיית הרשאה בחשבון השירות, אם ה-proxy מוגדר עם התג <Authentication>. סיבות אפשריות:
    • חשבון השירות לא קיים.
    • חשבון השירות לא נוצר באותו פרויקט בענן של Google כמו הארגון ב-Apigee.
    • לפורס יש הרשאה iam.serviceAccounts.actAs בחשבון השירות. פרטים נוספים זמינים במאמר מידע על הרשאות לחשבון שירות.

    משתני תקלות

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

    משתנים כאשר: דוגמה
    fault.name="fault_name" ‫fault_name הוא שם התקלה, כפי שמופיע בטבלה Runtime errors שלמעלה. שם התקלה הוא החלק האחרון של קוד התקלה. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed ‫policy_name הוא השם שהמשתמש הגדיר למדיניות שגרמה לשגיאה. servicecallout.SC-GetUserData.failed = true

    דוגמה לתגובת שגיאה

    {
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}

    דוגמה לכלל שגיאה

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

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