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

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

מה

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

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

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

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

בדרך כלל משתמשים בנכס יתרונות מרכזיים יחד עם שני כללי מדיניות אחרים: הקצאת משתני הודעה וחילוץ משתנים.

• בקשה: הקצאת הודעה מאכלסת את הודעת הבקשה שנשלחה לשלט הרחוק לאחר השיפור.

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

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

1. הקצאת הודעה policy: יוצר הודעת בקשה, מאכלסת כותרות HTTP, פרמטרים של שאילתה, מגדירה את ה-HTTP פועל וכו'
2. המדיניות בנושא יתרונות מרכזיים לשירות: הפניה להודעה שנוצרה על ידי הקצאת הודעה המדיניות, מגדיר כתובת URL יעד לקריאה החיצונית ומגדיר שם לאובייקט התגובה ששירות היעד מחזיר.
   
   כדי לשפר את הביצועים, ניתן גם לשמור במטמון את התשובות של יתרונות מרכזיים השירות, כפי שמתואר שרשור בקהילה ב-Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. חילוץ משתנים מדיניות: בדרך כלל מגדיר ביטוי JSONPath או XPath שמנתח את ההודעה שנוצרה להסבר על השירות. לאחר מכן המדיניות מגדירה משתנים שמכילים את הערכים שנותחו תגובה לבקשה להצעת מחיר בשירות.

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

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

הפניה לרכיב

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

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

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

<DisplayName> רכיב

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

<DisplayName>Policy Display Name</DisplayName>

<Request> רכיב

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

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

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

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

מאפיינים

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; רכיב

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

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

&lt;Response&gt; רכיב

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

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

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

 <Response>calloutResponse</Response> 

<זמן קצוב לתפוגה> רכיב

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

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; רכיב

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

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; רכיב

כתובת ה-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>

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; רכיב

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

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; רכיב

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

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

&lt;LocalTargetConnection&gt; רכיב

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

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

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; רכיב

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

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

יחד עם הרכיב <APIProxy>, יש לכלול את המילה <ProxyEndpoint> כדי לציין את השם של נקודת הקצה של שרת ה-proxy יהיה מטורגט לשיחה.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; רכיב

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

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; רכיב

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

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

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

סכימות

משתני זרימה

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

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

שגיאות

בקטע הזה מתוארים קודי השגיאה והודעות השגיאה שהוחזרו, ומשתני התקלה שמוגדרים על ידי 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>

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

• יצירה או שינוי של הודעות: הקצאת מדיניות בנושא הודעות
• חילוץ משתנים: חילוץ משתנים מדיניות
• משתנים: משתנים הפניה
• הגדרת TLS/SSL
  • הגדרה TLS מ-Edge לקצה העורפי (Cloud וענן פרטי)
  • 'הגדרת נקודת קצה (endpoint)' של TLS/SSL בחומר עזר בנושא תצורה של שרת proxy ל-API
• מאפייני תעבורה של HTTP: הפניה לנכסי נקודת קצה (endpoint)
• חלופה ל-Service Callout: HTTPClient כתוב ב-JavaScript. למידע נוסף: מודל אובייקט JavaScript