服務呼叫政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

您可以使用服務呼叫政策，從 API Proxy 流程呼叫其他服務。您可以對外部服務 (例如外部 RESTful 服務端點) 或內部服務 (例如相同機構和環境中的 API Proxy) 發出呼叫。

  • 在外部用途中，您會向 Proxy 外部的第三方 API 發出呼叫。系統會剖析第三方 API 的回應，並插入 API 的回應訊息，為應用程式使用者提供更豐富的資料。您也可以在要求流程中使用服務呼叫政策發出要求，然後將回應中的資訊傳遞至 API Proxy 的 TargetEndpoint。
  • 在另一個用途中，您會呼叫與您呼叫的物件位於相同機構和環境的 Proxy。舉例來說，如果您有一個提供某些離散低階功能的 Proxy，而一或多個其他 Proxy 會耗用這些功能，您可能會覺得這項功能很有用。舉例來說，如果某個 Proxy 透過後端資料存放區公開建立/讀取/更新/刪除作業，則該 Proxy 可能會成為其他多個 Proxy 的目標 Proxy，這些 Proxy 會向用戶端公開資料。

這項政策支援透過 HTTP 和 HTTPS 提出的要求。

範例

對內部 Proxy 的本機呼叫

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

這個範例會建立對名為 data-manager 的本機 API Proxy (也就是位於相同機構和環境中的 Proxy) 的呼叫，並指定名稱為 default 的 Proxy 端點。

網址 (變數)

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

這個範例使用網址中的變數，動態填入目標的網址。網址的通訊協定部分 (http://) 無法由變數指定。此外，網址的網域部分和網址的其餘部分必須使用不同的變數。

Google 地理編碼 / 定義要求

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

您可以在 Service Callout 政策中直接定義要求物件，而不必使用 Assign Message 等政策建立要求物件。在本例中，服務註解政策會設定傳遞至外部服務的三個查詢參數值。您可以在服務呼叫政策中建立整個要求訊息，指定酬載、編碼類型 (例如 application/xml)、標頭、表單參數等。

以下是另一個範例，說明如何在到達 Service Callout 政策前形成要求。

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

要求訊息的內容是從名為 GeocodingRequest 的變數中擷取 (例如，可由 AssignMessage 政策填入)。回應訊息會指派給名為 GeocodingResponse 的變數，供 Extract Variables 政策或以 JavaScript 或 Java 編寫的自訂程式碼剖析。這項政策會等待 Google Geocoding API 回應 30 秒，然後逾時。

如需使用這個範例服務呼叫的完整 API Proxy，以及 Assign Message 和 Extract Variables 政策，請參閱「使用政策組合」。

呼叫目標伺服器

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

這項政策會使用 LoadBalancer 屬性呼叫目標伺服器，並在這些伺服器之間進行負載平衡。在本範例中，負載會分配給名為「httpbin」和「yahoo」的兩個目標伺服器。如要瞭解如何為 Proxy 設定目標伺服器及設定負載平衡，請參閱在後端伺服器之間進行負載平衡。

關於服務呼叫政策

在 API Proxy 中，您可以在許多情境下使用服務呼叫政策。舉例來說，您可以設定 API 代理，呼叫外部服務來提供地理位置資料、顧客評論、合作夥伴零售目錄中的項目等。

一般來說，標註會搭配另外兩項政策使用：指派訊息和擷取變數。

  • 要求：指派訊息會填入傳送至遠端服務的要求訊息。

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

典型的服務呼叫政策組成包括：

  1. 指派訊息政策：建立要求訊息、填入 HTTP 標頭、查詢參數、設定 HTTP 動詞等。
  2. 服務呼叫政策：參照由「指派訊息」政策建立的訊息，定義外部呼叫的目標網址，並定義目標服務傳回的回應物件名稱。

    如要提升效能，您也可以快取服務呼叫回應，詳情請參閱這篇 Apigee 社群討論串：How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache? (如何將 ServiceCallout 政策的結果儲存在快取中，然後從快取中擷取？)。
  3. 擷取變數 政策：通常會定義 JSONPath 或 XPath 運算式，用於剖析服務呼叫產生的訊息。然後，政策會設定包含從服務呼叫回應剖析的值的變數。

如需使用 Service Callout 政策，以及 Assign Message 和 Extract Variables 政策的完整 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">

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以 包含英文字母、數字、空格、連字號、底線和半形句號。此值不能 超過 255 個半形字元

視需要使用 <DisplayName> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

如要強制執行政策，請設為 true。

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

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

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

在最簡單的範例中，您會傳遞包含要求訊息的變數，該訊息已在 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」元素或任何屬性，Edge 會指派下列預設值：

<Request clearPayload="true" variable="servicecallout.request"/>

以下說明這些預設值的意義。首先，clearPayload=true 表示每次執行 ServiceCallout 政策時，都會建立新的要求物件。也就是說，要求和要求 URI 路徑絕不會重複使用。其次，預設變數名稱 servicecallout.request 是保留名稱，如果您未提供名稱，系統會將這個名稱指派給要求。

如果您使用資料遮蓋，瞭解這個預設名稱非常重要。如果省略變數名稱，您需要在遮蓋設定中加入 servicecallout.request。舉例來說，如要遮蓋授權標頭，使其不會顯示在追蹤工作階段中，請在遮蓋設定中加入下列項目，以擷取預設名稱：

servicecallout.request.header.Authorization。
外觀狀態 選用。
類型 不適用

屬性

屬性 說明 預設 存在必要性
變數

將包含要求訊息的變數名稱。

 servicecallout.request 選用
clearPayload

如果是 true，系統會在要求傳送至 HTTP 目標後，清除包含要求訊息的變數，藉此釋放要求訊息使用的記憶體。

只有在執行服務呼叫後需要要求訊息時，才將 clearPayload 選項設為 false。

 true 選用

<Request>/<IgnoreUnresolvedVariables> 元素

如果設為 true，這項政策會忽略要求中任何未解決的變數錯誤。

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
預設 false
外觀狀態 選用
類型 布林值

<Response> 元素

如果 API Proxy 邏輯需要遠端呼叫的回應，才能進一步處理，請加入這個元素。

如果存在這個元素，則會指定變數名稱，其中包含從外部服務收到的回覆訊息。只有在政策成功讀取整個回應時，目標的回應才會指派給變數。如果遠端呼叫因故失敗，政策會傳回錯誤。

如果省略這個元素，API Proxy 不會等待回應；API Proxy 流程會繼續執行後續的任何流程步驟。此外，顯而易見的是，如果沒有 Response 元素，後續步驟就無法處理目標的回應，且 Proxy 流程也無法偵測遠端呼叫是否失敗。使用 ServiceCallout 時，省略 Response 元素的一般用途是將訊息記錄到外部系統。

 <Response>calloutResponse</Response>
預設 不適用
外觀狀態 選用
類型 字串

<Timeout> 元素

服務呼叫政策等待目標回應的時間 (以毫秒為單位)。您無法在執行階段動態設定這個值。如果服務呼叫達到逾時時間，系統會傳回 HTTP 500，政策會失敗，API Proxy 會進入錯誤狀態，如「處理錯誤」一文所述。

<Timeout>30000</Timeout>
預設 55000 毫秒 (55 秒)，Apigee Edge 的預設 HTTP 逾時設定
外觀狀態 選用
類型 整數

<HTTPTargetConnection> 元素

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

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>
預設 不適用
外觀狀態 必填
類型 不適用

<HTTPTargetConnection> 元素/<URL>

要呼叫的服務網址：

<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>
預設 不適用
外觀狀態 必填
類型 字串

<HTTPTargetConnection> 元素/<SSLInfo>

後端服務的 TLS/SSL 設定。如需傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 設定的說明，請參閱「從 Edge 到後端 (Cloud 和 Private Cloud) 設定傳輸層安全標準 (TLS)」一文，以及「API Proxy 設定參考資料」中的「傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) TargetEndpoint 設定」。

。 
<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>
預設 不適用
外觀狀態 選用
類型 不適用

<HTTPTargetConnection> 或 <Properties> 元素

傳送至後端服務的 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> 元素

呼叫一或多個目標伺服器，並對這些伺服器進行負載平衡。請參閱「範例」一節中的「呼叫目標伺服器」範例。另請參閱跨後端伺服器負載平衡。另請參閱這篇社群貼文，瞭解如何透過服務呼叫政策和使用路徑規則呼叫目標伺服器。

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

做為本機呼叫目標的 API Proxy 名稱。Proxy 必須與發出呼叫的 Proxy 位於相同機構和環境。

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

除了 <APIProxy> 元素，請一併加入 <ProxyEndpoint> 元素，指定應做為呼叫目標的 Proxy 端點名稱。

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection>
預設 不適用
外觀狀態 必填
類型 字串

<LocalTargetConnection> 或 <ProxyEndpoint> 元素

應做為呼叫目標的 Proxy 端點名稱。這是以 <APIProxy> 元素指定的 API Proxy 中的 Proxy 端點。

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>
預設 不適用
外觀狀態 選用
類型 不適用

<LocalTargetConnection> 元素

目標端點的路徑。端點必須參照與發出呼叫的 Proxy 位於相同機構和環境的 Proxy。

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

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>
預設 不適用
外觀狀態 選用
類型 不適用

結構定義

流程變數

流程變數可讓政策和流程在執行階段根據 HTTP 標頭、訊息內容或流程環境，動態調整行為。服務呼叫政策執行後，即可使用下列預先定義的 Flow 變數。如要進一步瞭解流程變數，請參閱「變數參考資料」。

服務 Callout 有自己的要求和回應，您可以透過變數存取該資料。由於主要訊息使用 request.* 和 response.* 變數前置字元，請使用 myrequest.* 和 calloutResponse.* 前置字元 (服務宣傳資訊設定中的預設值)，取得服務宣傳資訊專屬的訊息資料。下表的第一個範例顯示如何在服務呼叫中取得 HTTP 標頭。

變數 說明

以下範例說明如何取得服務呼叫要求和回應標頭，與取得主要要求和回應標頭的方式類似。

calloutResponse.header.HeaderName

myRequest.header.HeaderName

其中 calloutResponse 是服務呼叫中「回應」的變數名稱，而 myRequest 則是「要求」的變數名稱。例如：

calloutResponse.header.Content-Length

傳回服務呼叫回應的 Content-Length 標頭。

範圍：從服務呼叫轉送
類型：字串
權限：讀取/寫入

服務呼叫要求或回應中的訊息標頭。舉例來說，如果 API Proxy 目標是 http://example.com，而服務呼叫目標是 http://mocktarget.apigee.net，這些變數就是呼叫 http://mocktarget.apigee.net 的標頭。
servicecallout.requesturi

範圍：從服務呼叫要求轉送
類型：字串
權限：讀取/寫入

ServiceCallout 政策的 TargetEndpoint URI。URI 是 TargetEndpoint 網址，但不含通訊協定和網域規格。
servicecallout.{policy-name}.target.url

範圍：從服務呼叫要求轉送
類型：字串
權限：讀取/寫入

服務附註的目標網址。

calloutResponse.content

其中 calloutResponse 是 Service Callout 設定中的<Response>變數名稱。

範圍：從服務呼叫回應轉送
類型：字串
權限：讀取/寫入

服務呼叫的回應本文。
servicecallout.{policy-name}.expectedcn

範圍：從服務呼叫要求轉送
類型：字串
權限：讀取/寫入

TargetEndpoint 的預期通用名稱，如 ServiceCallout 政策中所述。只有在 TargetEndpoint 參照 TLS/SSL 端點時，這才有意義。
servicecallout.{policy-name}.failed

範圍：從 Service Callout 回應開始
類型：布林值
權限：讀取/寫入

布林值，指出政策是否成功 (false) 或失敗 (true)。

錯誤

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • the policy is asked to handle input that is malformed or otherwise invalid.
  • the backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type Request Message. For example, if it's a Response type, you'll see this error.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

Example error response

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

Example fault rule

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

相關主題