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

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

ההגדרה הזאת קובעת את המשתנה שמכיל את הודעת הבקשה שנשלחת משרת ה-API של ה-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> זהה לתחביר של המדיניות בנושא הקצאת הודעה.

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

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

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

מאפיינים

הרכיב <Request>/<IgnoreUnresolvedVariables>

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

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

הרכיב <Response>

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

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

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

 <Response>calloutResponse</Response> 

האלמנט <Timeout>

משך הזמן באלפיות השנייה שבו המדיניות של נכסי היתרונות המרכזיים של השירות תמתין לתגובה מהיעד. לא ניתן להגדיר את הערך הזה באופן דינמי בזמן ריצה. אם יתרון היתרונות המרכזיים של השירות פג תוקף, מוחזר 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 (לענן ולענן פרטי) ואת המאמר 'תצורת TLS/SSL TargetEndpoint' בחומר עזר בנושא הגדרה של שרת 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>/<Load Balancer>

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

<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 של שרת ה-API שצוין באמצעות הרכיב <APIProxy>.

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

רכיב <LocalTargetConnection>/<Path>

נתיב לנקודת הקצה שעליה טירגטת. נקודת הקצה צריכה להפנות לשרת 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 לקצה העורפי (ענן וענן פרטי)
  • 'TLS/SSL TargetEndpoint Configuration' בחומר עזר בנושא תצורה של שרת proxy ל-API
• מאפייני תעבורת HTTP: הפניות למאפייני נקודת קצה (endpoint)
• חלופה ליתרונות המרכזיים של השירות: HTTPClient כתוב ב-JavaScript, ראו מודל אובייקט של JavaScript