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

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

מה

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

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

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

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

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

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

1. Assign Message policy: יוצר בקשת הודעה, מאכלס כותרות 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 policy: בדרך כלל מגדיר ביטוי 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> זהה לתחביר של מדיניות הקצאת הודעות.

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

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

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

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

 <Response>calloutResponse</Response>

אלמנט <Timeout>

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

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

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

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