服務呼叫政策

您目前查看的是 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)。

錯誤

本節說明在這項政策觸發錯誤時，所傳回的錯誤代碼和錯誤訊息，以及 Edge 所設定的錯誤變數。 請務必瞭解這份資訊，以便瞭解您是否要擬定錯誤規則， 處理錯誤詳情請參閱這篇文章 瞭解政策錯誤和處理方式 發生錯誤

執行階段錯誤

執行政策時，可能會發生這些錯誤。

錯誤程式碼 HTTP 狀態 原因 修正
steps.servicecallout.ExecutionFailed 500

發生這個錯誤的可能原因如下：

  • 如果輸入格式錯誤或無效，系統就會要求政策處理。
  • 後端目標服務會傳回錯誤狀態 (預設為 4xx 或 5xx)。
steps.servicecallout.RequestVariableNotMessageType 500 政策中指定的 Request 變數不是 Message 類型。舉例來說 如果是字串或其他非訊息類型，系統就會顯示這則錯誤訊息。
steps.servicecallout.RequestVariableNotRequestMessageType 500 政策中指定的 Request 變數不是 Request Message。適用對象 例如，如果是回應類型，系統就會顯示此錯誤。

部署錯誤

當您部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱 原因 修正
URLMissing <HTTPTargetConnection> 中的 <URL> 元素 遺失或空白。
ConnectionInfoMissing 如果政策沒有 <HTTPTargetConnection> 或 <LocalTargetConnection> 元素。
InvalidTimeoutValue 如果 <Timeout> 值為負數或零，就會發生這個錯誤。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤程式碼的最後部分。 fault.name = "RequestVariableNotMessageType"
servicecallout.policy_name.failed policy_name 是使用者指定錯誤的政策名稱。 servicecallout.SC-GetUserData.failed = true

錯誤回應範例

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

相關主題