服務呼叫政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

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

  • 在外部使用案例中,您必須呼叫 Proxy 以外的第三方 API。剖析第三方 API 的回應,然後插入您的 API 回應訊息中,為應用程式使用者的資料充實並「混搭」起來。您也可以在要求流程中使用服務呼叫政策提出要求,然後將回應中的資訊傳送至 API Proxy 的 TargetEndpoint。
  • 在其他使用案例中,您呼叫的 Proxy 位於與呼叫來源相同的機構和環境中。舉例來說,當您的 Proxy 提供一些獨立的低階功能,而其他 Proxy 將會用到的特定低階功能時,這個功能就非常實用。舉例來說,與後端資料儲存庫公開建立/讀取/更新/刪除作業的 Proxy 可能會是多個向用戶端公開資料的其他 Proxy 的目標 Proxy。

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

範例

對內部 Proxy 的本機呼叫

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

這個範例會為名為 data-manager 的本機 API 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

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

這是另一個示例,就是要求在符合服務呼叫政策前就提出。

<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 的變數,您可以透過「擷取變數」政策或以 JavaScript 或 Java 編寫的自訂程式碼剖析訊息。這項政策會等候 Google Geocoding API 回應 30 秒,再逾時。

如需使用這個服務呼叫範例的完整 API Proxy 範例,以及指派訊息和擷取變數政策,請參閱使用政策組合

來電目標伺服器

<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 Proxy 呼叫外部服務,以便提供地理位置資料、客戶評論、合作夥伴零售目錄中的商品等等。

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

  • 要求:指派 Message 會填入傳送至遠端服務的要求訊息。
  • 回應:擷取變數會剖析回應並擷取特定內容。

典型的服務呼叫政策組合包含以下內容:

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

    為改善效能,您也可以依照下列 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>

<Service callout> 屬性

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

下表說明所有政策父項元素的通用屬性:

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

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

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

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

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 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 表示每次執行 Service callout 政策時,系統會建立新的要求物件。這表示要求和要求 URI 路徑均不會重複使用。其次,預設變數名稱 servicecallout.request 是在您未提供名稱的情況下指派給要求的保留名稱。

如果您使用資料遮蓋,請務必瞭解這個預設名稱。如果省略變數名稱,則必須在遮罩設定中加入 servicecallout.request。舉例來說,如果您想遮蓋 Authorization 標頭,使其不在 Trace 工作階段中,可以將下列內容加入遮蓋設定,以擷取預設名稱:

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 流程也無法偵測遠端呼叫中的失敗情形。使用 Service callout 時省略 Response 元素的常見用途:將訊息記錄到外部系統。

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

<Timeout> 元素

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

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

<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 設定的相關說明,請參閱「設定從邊緣到後端的 TLS (雲端和私有雲)」和 API Proxy 設定參考資料中的「TLS/SSL 目標端點設定」。

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

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

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

指定端點的路徑。端點必須參照與呼叫 Proxy 位於相同機構與環境中的 Proxy。

如果您不知道或無法使用 Proxy 名稱,請使用此組合取代 <APIProxy>/<ProxyEndpoint> 組合。路徑可能是可靠的目標。

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

結構定義

流程變數

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

服務呼叫具有專屬的要求和回應,您可以透過變數存取這些資料。由於主要訊息使用 request.*response.* 變數前置字串,因此請使用 myrequest.*calloutResponse.* 前置字串 (服務呼叫設定中的預設值),取得服務呼叫專屬的訊息資料。下表的第一個範例說明如何在服務呼叫中取得 HTTP 標頭。

變數 說明

以下範例是取得服務呼叫要求和回應標頭的範例,類似從主要要求和回應取得標頭的方式。

calloutResponse.header.HeaderName

myRequest.header.HeaderName

其中 calloutResponse 是服務呼叫中回應的變數名稱,myRequest 則是要求的變數名稱。例如:

calloutResponse.header.Content-Length

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

範圍:從服務摘要前推
類型:字串
Permission:讀取/寫入

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

servicecallout.requesturi

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

Service Call 政策的 TargetEndpoint URI。URI 是不含通訊協定和網域規格的 TargetEndpoint 網址。

servicecallout.{policy-name}.target.url

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

服務呼叫的目標網址。

calloutResponse.content

其中 calloutResponse 是服務呼叫設定中的 <Response> 變數名稱。

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

服務呼叫的回應主體。

servicecallout.{policy-name}.expectedcn

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

服務呼叫政策所參照的 TargetEndpoint 預期一般名稱。只有在 TargetEndpoint 參照傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 端點時,才會有意義。

servicecallout.{policy-name}.failed

範圍:從服務呼叫回應轉寄
類型:布林值
權限:讀取/寫入

布林值,表示政策成功、否或失敗。

錯誤

本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

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

造成這個錯誤的可能原因如下:

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

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

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

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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>

相關主題