服務呼叫政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

服務呼叫政策可讓您從 API Proxy 流程呼叫其他服務。個人中心 可以呼叫外部服務 (例如符合 REST 樣式的外部服務端點) 內部服務 (例如相同機構和環境中的 API Proxy)。

• 如果是外部用途，則呼叫的是 Proxy 上。系統會剖析第三方 API 回應，並插入您的 API 回應中 訊息、豐富及「混搭」應用程式使用者的資料你也可以請求 在要求流程中使用服務呼叫政策，然後在回應中傳遞資訊 指向 API Proxy 的 TargetEndpoint。
• 在其他用途中，您呼叫的 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>

關於服務呼叫政策

在許多情況下，您可以在 API Proxy 中使用服務呼叫政策。適用對象 比方說，您可以設定 API Proxy 呼叫外部服務 地理位置資料、客戶評論、合作夥伴零售目錄中的商品等等。

摘要通常會搭配另外兩種政策使用：指派訊息和擷取變數。

• 要求：指派訊息會填入傳送至遠端的要求訊息 課程中也會快速介紹 Memorystore 這是 Google Cloud 的全代管 Redis 服務

• 回應：擷取變數會剖析回應並擷取 內容。

一般服務呼叫政策的組成包括：

1. 指派訊息 policy：建立要求訊息、填入 HTTP 標頭、查詢參數、設定 HTTP 動詞等
2. 服務摘要政策：參照指派訊息所建立的訊息 policy、定義外部呼叫的目標網址，以及定義回應物件的名稱 回應目標服務傳回的值
   
   如要改善效能，您也可以快取服務呼叫回應，如下文所述 Apigee 社群會話串：https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html。
3. 擷取變數 政策：通常定義 JSONPath 或 XPath 運算式，用來剖析產生的訊息 由服務呼叫所支援接著，政策會設定變數，其中包含從 服務呼叫回應。

請參閱使用政策 組合包含使用服務呼叫政策及服務呼叫政策的完整 API Proxy 範例 指派訊息和擷取變數政策

自訂錯誤處理

元素參照

以下為這項政策可設定的元素和屬性：

<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 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

<Request>元素

指定內含要求訊息的變數，該訊息會從 API Proxy 傳送至 其他服務。變數可由流程中的現有政策建立，也可以建立該變數 服務呼叫政策的內嵌項目。

<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> 標記的語法與 指定訊息 政策。

如果要求訊息無法解析或無效，政策會傳回錯誤 要求訊息類型。

在最簡單的範例中，您傳遞的變數包含已填入的要求訊息 執行以下作業：

<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;元素

當 API Proxy 邏輯需要遠端呼叫的回應時，請加入此元素 需要進一步處理

使用這個元素時，它會指定包含 從外部服務接收的回應訊息。目標的回應會指派給 政策能成功讀取整個回應時，才會儲存這個變數。如果遠端通話 失敗，這項政策會傳回錯誤。

如果省略這個元素，API Proxy 不會等待回應。API Proxy 流程 隨著任何後續流程步驟繼續執行。此外，為了說明這個情況， Response 元素，則無法透過 ，而 Proxy 流程無法偵測遠端呼叫中的失敗情形。 使用 Service callout 時省略 Response 元素的常見用途：記錄 傳送至外部系統

 <Response>calloutResponse</Response> 

<逾時>元素

服務呼叫政策等待回應 目標。您無法在執行階段動態設定這個值。如果服務呼叫達到逾時， 如果傳回 HTTP 500，政策就會失敗，且 API Proxy 進入錯誤狀態， 請參閱「處理錯誤」一節。

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt;元素

提供網址、TLS/SSL 和 HTTP 屬性等傳輸詳細資料。詳情請參閱 <TargetEndpoint> 設定參考資料。

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

&lt;HTTPTargetConnection&gt;/&lt;URL&gt;元素

要呼叫的服務的網址：

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

您可以使用變數動態提供部分網址。不過，通訊協定部分 下方的 http:// 網址，不可以是 變數指定的變數在下一個範例中，您將使用變數指定查詢的值 參數：

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

或者，您也可以使用變數來設定部分網址路徑：

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

如要使用變數指定網址的網域和通訊埠，請使用單一變數 以及第二個變數 (用於網址其他部分)：

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt;元素

後端服務的 TLS/SSL 設定。如需 TLS/SSL 設定的說明，請參閱 設定 TLS 從邊緣到後端 (Cloud 和私有雲) 以及「TLS/SSL 目標端點設定」 API Proxy 設定參考資料。

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

&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;元素

做為本機呼叫目標的 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 端點名稱。這是位於 使用 <APIProxy> 元素指定的 API Proxy。

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt;元素

指向目標端點的路徑。端點必須參照位於 和環境。

如果不需要，請使用這個組合，而不要使用 <APIProxy>/<ProxyEndpoint> 組合 或無法依賴 -- Proxy 名稱路徑可能是可靠的目標。

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

結構定義

流程變數

流程變數會根據 HTTP 在執行階段啟用政策和流程的動態行為 標頭、郵件內容或流程背景資訊可用的預先定義 Flow 變數如下 執行服務呼叫政策後。如要進一步瞭解流程變數，請參閱變數參考資料。

服務呼叫有自己的要求和回應，您可以透過 變數。因為主要訊息使用 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>

相關主題

• 產生或修改訊息：指派訊息政策
• 擷取變數：擷取變數 政策
• 變數：Variables 參考資料
• TLS/SSL 設定
  • 設定 從 Edge 到後端的傳輸層安全標準 (TLS) (雲端和私有雲)
  • 「TLS/SSL 目標端點設定」API Proxy 設定參考資料
• HTTP 傳輸屬性：端點屬性參考資料
• 服務呼叫的替代方法：以 JavaScript 編寫的 HTTPClient，請參閱 JavaScript 物件模型