您正在查看 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 會填入傳送至遠端服務的要求訊息。
-
回應:擷取變數會剖析回應並擷取特定內容。
典型的服務呼叫政策組合包含以下內容:
- 指派訊息政策:建立要求訊息、填入 HTTP 標頭、查詢參數,以及設定 HTTP 動詞等。
- 服務呼叫政策:參照由指派訊息政策建立的訊息、定義外部呼叫的目標網址,並定義目標服務傳回的回應物件名稱。
為改善效能,您也可以依照下列 Apigee 社群會話串的說明,快取服務呼叫回應:https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html。 - 擷取變數政策:一般會定義 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<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> 標記的語法與指派訊息政策相同。
如果要求訊息無法解析,或要求訊息類型無效,這項政策會傳回錯誤。
在最簡單的範例中,您傳遞的變數包含之前在 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"/> 一起來看看這些預設值的意義。首先,
如果您使用資料遮蓋,請務必瞭解這個預設名稱。如果省略變數名稱,則必須在遮罩設定中加入 |
外觀狀態 | 選用。 |
類型 | 不適用 |
屬性
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
變數 |
包含要求訊息的變數名稱。 |
servicecallout.request |
選用 |
clearPayload |
如為 只有在執行服務呼叫之後需要要求訊息時,才將 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 是服務呼叫中回應的變數名稱,myRequest 則是要求的變數名稱。例如:
會傳回服務呼叫回應的 Content-Length 標頭。 |
範圍:從服務摘要前推 服務呼叫要求或回應中的訊息標頭。舉例來說,如果 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 |
範圍:從服務呼叫要求轉寄 服務呼叫的目標網址。 |
其中 |
範圍:從服務呼叫回應轉寄 服務呼叫的回應主體。 |
servicecallout.{policy-name}.expectedcn |
範圍:從服務呼叫要求轉寄 服務呼叫政策所參照的 TargetEndpoint 預期一般名稱。只有在 TargetEndpoint 參照傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 端點時,才會有意義。 |
servicecallout.{policy-name}.failed |
範圍:從服務呼叫回應轉寄 布林值,表示政策成功、否或失敗。 |
錯誤
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.servicecallout.ExecutionFailed |
500 |
造成這個錯誤的可能原因如下:
|
build |
steps.servicecallout.RequestVariableNotMessageType |
500 | 政策中指定的 Request 變數不是「Message」類型。例如,如果是字串或其他非訊息類型,系統就會顯示這個錯誤。 | build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 | 政策中指定的 Request 變數不是要求訊息類型。舉例來說,如果是「回應」類型,系統就會顯示這個錯誤。 | build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
URLMissing |
<HTTPTargetConnection> 中的 <URL> 元素缺少或空白。 |
build |
ConnectionInfoMissing |
如果政策沒有 <HTTPTargetConnection> 或 <LocalTargetConnection> 元素,就會發生這個錯誤。 |
build |
InvalidTimeoutValue |
如果 <Timeout> 值為負或零,就會發生這個錯誤。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
錯誤回應範例
{ "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 設定
- 設定從 Edge 到後端的 TLS (雲端和私有雲)
- API Proxy 設定參考資料中的「TLS/SSL TargetEndpoint Configuration」一節
- HTTP 傳輸屬性:端點屬性參考資料
- 服務呼叫的替代方案:以 JavaScript 編寫的 HTTPClient,請參閱 JavaScript 物件模型