‫ServiceCallout policy

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

מה

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

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

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

דוגמאות

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

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

<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>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

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

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

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

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

בדרך כלל משתמשים ב-Callout עם שני כללי מדיניות נוספים: Assign Message ו-Extract Variables.

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

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

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

1. הקצאת מדיניות להודעה: יוצרת הודעת בקשה, מאכלסת כותרות HTTP, פרמטרים של שאילתה, מגדירה את הפועל של HTTP וכו'.
2. מדיניות Service Callout: מפנה להודעה שנוצרה על ידי מדיניות Assign Message, מגדירה כתובת URL של יעד לקריאה החיצונית ומגדירה שם לאובייקט התגובה ששירות היעד מחזיר.
   
   כדי לשפר את הביצועים, אפשר גם לשמור במטמון את התגובות של Service Callout, כמו שמתואר בשרשור הזה בקהילת Apigee: ‏ How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache?.
3. מדיניות Extract Variables (חילוץ משתנים): בדרך כלל מגדירה ביטוי JSONPath או XPath שמנתח את ההודעה שנוצרה על ידי Service Callout. לאחר מכן המדיניות מגדירה משתנים שמכילים את הערכים שנותחו מהתגובה של רכיב Service Callout.

במאמר שימוש בהרכבת מדיניות מופיע קוד מלא של proxy ל-API שמשתמש במדיניות Service Callout יחד עם המדיניות Assign Message ו-Extract Variables.

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

הפניה לרכיב

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

<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>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

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

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

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

אלמנט <Request>

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

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

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

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

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

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

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

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

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

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

אלמנט <Response>

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

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

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

 <Response>calloutResponse</Response>

אלמנט <Timeout>

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

<Timeout>30000</Timeout>

אלמנט <HTTPTargetConnection>

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

אלמנט <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>

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

הגדרת TLS/SSL לשירות הקצה העורפי. לקבלת עזרה בהגדרת TLS/SSL, אפשר לעיין במאמר הגדרת TLS מ-Edge אל ה-Backend (Cloud ו-Private Cloud) ובמאמר בנושא 'הגדרת 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>

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

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

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

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

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

שגיאות

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

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

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

שגיאות פריסה

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

משתני כשל

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

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

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

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

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

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

• יצירה או שינוי של הודעות: הקצאת מדיניות הודעות
• חילוץ משתנים: Extract Variables policy
• משתנים: הפניה למשתנים
• הגדרת TLS/SSL
  • הגדרה של TLS מ-Edge לקצה העורפי (Cloud ו-Private Cloud)
  • 'TLS/SSL TargetEndpoint Configuration' (הגדרת נקודת קצה של יעד TLS/SSL) בהפניה להגדרת proxy ל-API
• מאפייני העברה ב-HTTP: הפניה למאפייני נקודת קצה (endpoint)
• חלופה ל-Service Callout: ‏ HTTPClient שנכתב ב-JavaScript, ראו מודל אובייקטים של JavaScript