本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
您可以使用 ServiceCallout 政策,從 API Proxy 流程呼叫其他服務。您可以呼叫外部服務 (例如外部 RESTful 服務端點),也可以呼叫內部服務 (例如相同機構和環境中的 API Proxy)。
這項政策是可擴充政策,使用這項政策可能會產生費用或影響用量,具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響,請參閱「政策類型」。
- 在外部用途中,您會向 Proxy 外部的第三方 API 發出呼叫。系統會剖析第三方 API 的回應,並插入 API 的回應訊息,藉此充實及混搭應用程式使用者資料。您也可以在要求流程中使用 ServiceCallout 政策提出要求,然後將回應中的資訊傳遞至 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>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
您可以在 ServiceCallout 政策中直接定義要求物件,而不使用 AssignMessage 政策等政策建立要求物件。在本範例中,ServiceCallout 政策會設定傳遞至外部服務的三個查詢參數值。您可以在 ServiceCallout 政策中建立完整的要求訊息,指定酬載、編碼類型 (例如 application/xml)、標頭、表單參數等。
以下是另一個範例,要求是在抵達 ServiceCallout 政策之前形成。
<ServiceCallout name="ServiceCallout-GeocodingRequest2"> <Request clearPayload="false" variable="GeocodingRequest"/> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
要求訊息的內容是從名為 GeocodingRequest 的變數中擷取 (例如,可由 AssignMessage 政策填入)。回應訊息會指派給名為 GeocodingResponse 的變數,並可供 ExtractVariables 政策或以 JavaScript 或 Java 編寫的自訂程式碼剖析。這項政策會等待 Google Geocoding API 回應 30 秒,然後逾時。
呼叫目標伺服器
<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 設定目標伺服器及設定負載平衡,請參閱在後端伺服器之間進行負載平衡。
關於 ServiceCallout 政策
您可以在 API Proxy 中使用 ServiceCallout 政策,適用於許多情境。舉例來說,您可以設定 API Proxy,呼叫外部服務來提供地理位置資料、顧客評論、合作夥伴零售目錄中的項目等。
一般來說,呼叫會搭配另外兩項政策使用:AssignMessage 和 ExtractVariables。
- 要求:AssignMessage 會填入傳送至遠端服務的要求訊息。
-
回應:ExtractVariables 會剖析回應並擷取特定內容。
一般的 ServiceCallout 政策組成包括:
- AssignMessage 政策:建立要求訊息、填入 HTTP 標頭、查詢參數、設定 HTTP 動詞等。
-
ServiceCallout 政策:參照 AssignMessage 政策建立的訊息,定義外部呼叫的目標網址,並定義目標服務傳回的回應物件名稱。
如要提升效能,您也可以快取 ServiceCallout 回應,詳情請參閱「如何將 ServiceCallout 政策的結果儲存在快取中,並在稍後從快取中擷取?」一文。
- ExtractVariables 政策:通常會定義 JSONPath 或 XPath 運算式,用於剖析 ServiceCallout 產生的訊息。接著,政策會設定變數,其中包含從 ServiceCallout 回應剖析的值。
自訂錯誤處理
元素參考資料
您可以在這項政策中設定下列元素和屬性:
<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> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request> <Response>calloutResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> <Authentication> <HeaderName ref="{variable}">STRING</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds> </GoogleAccessToken> </Authentication> <Authentication> <HeaderName ref="{variable}">STRING</HeaderName> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience> <IncludeEmail ref="{variable}">true</IncludeEmail> </GoogleIDToken> </Authentication> </HTTPTargetConnection> <LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection> </ServiceCallout>
<ServiceCallout> 屬性
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
下表說明所有政策父項元素的共同屬性:
| 屬性 | 說明 | 預設 | 存在必要性 |
|---|---|---|---|
name |
政策的內部名稱。 您可以選擇使用 |
不適用 | 必填 |
continueOnError |
將其設為 將其設為 |
false | 選用 |
enabled |
設為 設為 |
是 | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name 屬性之外,您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。
<DisplayName>Policy Display Name</DisplayName>
| 預設 |
不適用 如果省略這個元素,系統會使用政策的 |
|---|---|
| 存在必要性 | 選用 |
| 類型 | 字串 |
<Request> 元素
指定包含從 API Proxy 傳送至其他服務的要求訊息的變數。變數可由流程中的先前政策建立,也可以在 ServiceCallout 政策中內嵌建立。
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request>
<Remove>、<Copy>、<Add> 和 <Set> 標記的語法與 AssignMessage 政策相同。
如果無法解析要求訊息,或要求訊息類型無效,政策就會傳回錯誤。
在最簡單的範例中,您會傳遞包含要求訊息的變數,該訊息先前已在 API Proxy 的流程中填入:
<Request clearPayload="true" variable="myRequest"/>
或者,您可以在 ServiceCallout 政策本身中,填入傳送至外部服務的要求訊息:
<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 元素或任何屬性,Apigee 會指派下列預設值:
<Request clearPayload="true" variable="servicecallout.request"/> 以下說明這些預設值的意義。首先,
如果您使用資料遮蓋,請務必瞭解這個預設名稱。如果省略變數名稱,您需要在遮蓋設定中加入 |
| 外觀狀態 | 選用。 |
| 類型 | 不適用 |
屬性
| 屬性 | 說明 | 預設 | 狀態 |
|---|---|---|---|
| variable |
將包含要求訊息的變數名稱。 |
servicecallout.request |
選用 |
| clearPayload |
如果 只有在執行 ServiceCallout 後仍需要要求訊息時,才將 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> 元素
ServiceCallout 政策等待目標回應的時間 (毫秒)。您無法在執行階段動態設定這個值。如果 ServiceCallout 達到逾時時間,系統會傳回 HTTP 500,政策會失敗,API Proxy 會進入錯誤狀態,如「處理錯誤」一文所述。
<Timeout>30000</Timeout>
| 預設 | 55000 毫秒 (55 秒),這是 Apigee 的預設 HTTP 逾時設定 |
| 外觀狀態 | 選用 |
| 類型 | 整數 |
<HTTPTargetConnection> 元素
提供傳輸詳細資料,例如網址、TLS/SSL 和 HTTP 屬性。請參閱 <TargetEndpoint> 設定參考資料。
<HTTPTargetConnection>
<URL>http://example.com</URL>
<LoadBalancer/>
<SSLInfo/>
<Properties/>
</HTTPTargetConnection>| 預設 | 不適用 |
| 外觀狀態 | 必填 |
| 類型 | 不適用 |
<HTTPTargetConnection>/<Authentication> 元素
產生 Google OAuth 2.0 或 Google 簽發的 OpenID Connect 權杖,對 Google 服務和在特定 Google Cloud 產品 (例如 Cloud Functions 和 Cloud Run) 上執行的自訂服務進行已驗證的呼叫。如要使用這個元素,請按照「使用 Google 驗證」一文所述的步驟進行設定及部署。設定完成後,這項政策會為您建立驗證權杖,並將其新增至服務要求。
子元素 GoogleAccessToken 和 GoogleIDToken 可讓您設定政策,產生 Google OAuth 或 OpenID Connect 權杖。您需要根據要呼叫的服務類型,挑選其中一個子元素。
ServiceCallout 政策僅支援呼叫以 HTTP 為基礎的服務。
| 預設 | 不適用 |
| 必填與否 | 選填。 |
| 類型 | 複雜型別 |
| 父項元素 | <HTTPTargetConnection> |
| 子元素 | <HeaderName><GoogleAccessToken><GoogleIDToken>
|
Authentication 元素使用下列語法:
語法
<ServiceCallout> ... <HTTPTargetConnection> <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleAccessToken> <Scopes> <Scope>SCOPE</Scope> ... </Scopes> <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only if you want to limit the risk of leaked access tokens or improve performance. --> <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds> </GoogleAccessToken> --OR-- <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience> <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </ServiceCallout>
使用 GoogleAccessToken
以下範例顯示 GoogleAccessToken 元素:
<Authentication>
<GoogleAccessToken>
<Scopes>
<Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
</Scopes>
</GoogleAccessToken>
</Authentication>使用 GoogleIDToken
以下範例顯示 GoogleIDToken 元素:
<Authentication>
<GoogleIDToken>
<Audience>https://httpserver0-bar.run.app</Audience>
<IncludeEmail>false</IncludeEmail>
</GoogleIDToken>
</Authentication>使用 HeaderName
以下範例顯示 HeaderName 元素:
<Authentication>
<HeaderName>X-Serverless-Authorization</HeaderName>
<GoogleAccessToken>
<Scopes>
<Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope>
</Scopes>
</GoogleAccessToken>
</Authentication>使用 LifetimeInSeconds
以下範例顯示 HeaderName 元素:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope> </Scopes> <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds> </GoogleAccessToken> </Authentication>
屬性
無。
HeaderName 子項元素
根據預設,如果存在驗證設定,Apigee 會產生不記名權杖,並將其插入傳送至目標系統的訊息中的 Authorization 標頭。HeaderName 元素可讓您指定其他標頭的名稱,以保留該不記名權杖。如果目標是使用 X-Serverless-Authorization 標頭的 Cloud Run 服務,這項功能就特別實用。如果存在 Authorization 標頭,則會保留不變,並一併傳送至要求。
| 預設 | 不適用 |
| 必填與否 | 否 |
| 類型 | 字串 |
| 父項元素 | <Authentication> |
| 子元素 | 無 |
HeaderName 元素使用下列語法:
語法
<ServiceCallout>
...
<Authentication>
<HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
<GoogleAccessToken>
...
</GoogleAccessToken>
</Authentication>
...
</ServiceCallout>使用靜態字串
在本範例中,系統預設會將產生的不記名權杖新增至名為 X-Serverless-Authorization 的標頭,並傳送至目標系統。如果存在 Authorization 標頭,則會保留不變,並一併傳送至要求。
<Authentication>
<HeaderName>X-Serverless-Authorization</HeaderName>
<GoogleAccessToken>
<Scopes>
<Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
</Scopes>
</GoogleAccessToken>
</Authentication>使用變數參照
在本範例中,系統預設會將產生的不記名權杖新增至名為 X-Serverless-Authorization 的標頭,並傳送至目標系統。如果 my-variable 有值,系統會使用該值,而非預設字串。如果存在 Authorization 標頭,則會保留不變,並一併傳送至要求。
<Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
GoogleAccessToken 子項元素
產生 Google OAuth 2.0 權杖,以便對 Google 服務進行已驗證的呼叫。Google OAuth 權杖可用於呼叫多種 Google 服務,例如 Cloud Logging 和 Secret Manager。
| 預設 | 不適用 |
| 必填與否 | 必須提供 GoogleAccessToken 或 GoogleIDToken 子項元素。 |
| 類型 | 字串 |
| 父項元素 | <Authentication> |
| 子元素 | <Scopes><LifetimeInSeconds> |
GoogleAccessToken 元素使用下列語法:
語法
<ServiceCallout>
...
<Authentication>
<GoogleAccessToken>
<Scopes>
<Scope>SCOPE_1</Scope>
...
</Scopes>
<!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing
the default unless you want to limit the risk of leaked access tokens or improve performance. -->
<LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds>
</GoogleAccessToken>
</Authentication>
...
</ServiceCallout>範例 1
以下範例顯示 GoogleAccessToken 元素:
<Authentication>
<GoogleAccessToken>
<Scopes>
<Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
</Scopes>
</GoogleAccessToken>
</Authentication>範例 2
以下範例說明如何使用 ServiceCallout 政策連線至 Secret Manager,以擷取密鑰。
<ServiceCallout name="ServiceCallout-sm">
<Response>SecretManagerResponse</Response>
<Timeout>30000</Timeout>
<HTTPTargetConnection>
<Authentication>
<GoogleAccessToken>
<Scopes>
<Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
</Scopes>
</GoogleAccessToken>
</Authentication>
<URL>
https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id
</URL>
</HTTPTargetConnection>
</ServiceCallout>範例 3
下列範例說明如何從 ServiceCallout 政策向 Cloud Run 發出呼叫。
<ServiceCallout name="ServiceCallout-CloudRun">
<Response>CloudRunResponse</Response>
<Timeout>30000</Timeout>
<HTTPTargetConnection>
<Authentication>
<GoogleIDToken>
<Audience>https://cloudrun-hostname.a.run.app/test</Audience>
</GoogleIDToken>
</Authentication>
<URL>https://cloudrun-hostname.a.run.app/test</URL>
</HTTPTargetConnection>
</ServiceCallout>範圍子元素
識別要納入 OAuth 2.0 存取權杖的範圍。詳情請參閱「
Google API 適用的 OAuth 2.0 範圍」。您可以在這個元素下新增一或多個 <Scope> 子項元素。
| 預設 | 不適用 |
| 必填與否 | 必填 |
| 類型 | 字串 |
| 父項元素 | <GoogleAccessToken> |
| 子元素 | <Scope> |
範圍子項元素
指定有效的 Google API 範圍。詳情請參閱「 Google API 適用的 OAuth 2.0 範圍」。
| 預設 | 不適用 |
| 必填與否 | 至少須輸入一個值。 |
| 類型 | 字串 |
| 父項元素 | <Scopes> |
| 子元素 | 無 |
LifetimeInSeconds 子項元素
以秒為單位指定存取權杖的生命週期長度。
| 預設 | 3600 |
| 必填與否 | 選用 |
| 類型 | 整數 |
| 父項元素 | <GoogleAccessToken> |
| 子元素 | 無 |
GoogleIDToken 子項元素
產生 Google 簽發的 OpenID Connect 權杖,向 Google 服務發出經過驗證的呼叫。
| 預設 | 不適用 |
| 必填與否 | 必須提供 GoogleAccessToken 或 GoogleIDToken 子項元素。 |
| 類型 | 字串 |
| 父項元素 | <Authentication> |
| 子元素 | <Audience><IncludeEmail> |
GoogleIDToken 元素使用下列語法:
語法
<ServiceCallout> ... <Authentication> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience> <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </ServiceCallout>
範例 1
以下範例顯示 GoogleIDToken 元素:
<Authentication>
<GoogleIDToken>
<Audience>https://httpserver0-bar.run.app</Audience>
<IncludeEmail>true</IncludeEmail>
</GoogleIDToken>
</Authentication>目標對象子元素
所產生驗證權杖的對象,例如權杖授予存取權的 API 或帳戶。
如果 Audience 的值為空白,或 ref 變數無法解析為有效值,且 useTargetUrl 為 true,則目標網址 (不含任何查詢參數) 會做為目標對象。根據預設,useTargetUrl 為 false。
<Audience>explicit-audience-value-here</Audience> or: <Audience ref='variable-name-here'/> or: <Audience ref='variable-name-here' useTargetUrl='true'/> or: <Audience useTargetUrl='true'/>
| 預設 | 不適用 |
| 必填與否 | 必填 |
| 類型 | 字串 |
| 父項元素 | <GoogleIDToken> |
| 子元素 | 無 |
IncludeEmail 子元素
如果設為 true,產生的驗證權杖會包含服務帳戶 email 和 email_verified 聲明。
| 預設 | false |
| 必填與否 | 選用 |
| 類型 | 布林值 |
| 父項元素 | <GoogleIDToken> |
| 子元素 | 無 |
<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 的選項」和「TLS/SSL TargetEndpoint 設定」,網址為 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>| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 不適用 |
<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> 元素
呼叫一或多個目標伺服器,並對這些伺服器執行負載平衡。請參閱「範例」一節中的「呼叫目標伺服器」範例。另請參閱跨後端伺服器負載平衡。另請參閱目標端點/伺服器呼叫,瞭解如何透過 ServiceCallout 政策和使用路由規則呼叫目標伺服器。
<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 端點名稱。這是 API Proxy 中的 Proxy 端點,以 <APIProxy> 元素指定。
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 不適用 |
<LocalTargetConnection> 或 <Path> 元素
要鎖定的端點路徑。端點必須參照與發出呼叫的 Proxy 位於相同機構和環境的 Proxy。
如果您不知道或無法依賴 Proxy 名稱,請使用這個標記,而非 <APIProxy>/<ProxyEndpoint> 標記組合。路徑可能是可靠的目標。
<LocalTargetConnection> <Path>/data-manager</Path> </LocalTargetConnection>
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 不適用 |
結構定義
流程變數
流程變數可讓政策和流程在執行階段根據 HTTP 標頭、訊息內容或流程情境,動態調整行為。服務呼叫政策執行後,即可使用下列預先定義的 Flow 變數。如要進一步瞭解流程變數,請參閱「流程變數參考資料」。
ServiceCallout 有自己的要求和回應,您可以透過變數存取該資料。由於主要訊息使用 request.* 和 response.* 變數前置字元,請使用 myrequest.* 和 calloutResponse.* 前置字元 (ServiceCallout 設定中的預設值),取得 ServiceCallout 專屬的訊息資料。下表的第一個範例說明如何在 ServiceCallout 中取得 HTTP 標頭。
| 變數 | 說明 |
|---|---|
|
以下範例說明如何取得 ServiceCallout 要求和回應標頭,與取得主要要求和回應標頭的方式類似。
其中 calloutResponse 是服務呼叫中「回應」的變數名稱,myRequest 則是「要求」的變數名稱。例如:
傳回 ServiceCallout 回應的 Content-Length 標頭。 |
範圍:從 ServiceCallout 開始 ServiceCallout 要求或回應中的訊息標頭。舉例來說,如果 API Proxy 目標是 http://example.com,而 ServiceCallout 目標是 http://mocktarget.apigee.net,這些變數就是呼叫 http://mocktarget.apigee.net 的標頭。 |
servicecallout.requesturi |
範圍:從 ServiceCallout 要求開始 ServiceCallout 政策的 TargetEndpoint URI。URI 是 TargetEndpoint 網址,不含通訊協定和網域規格。 |
servicecallout.{policy-name}.target.url |
範圍:從 ServiceCallout 要求開始 ServiceCallout 的目標網址。 |
|
其中 |
範圍:從 ServiceCallout 回應開始 ServiceCallout 的回應本文。 |
servicecallout.{policy-name}.expectedcn |
範圍:從 ServiceCallout 要求開始 TargetEndpoint 的預期通用名稱,如 ServiceCallout 政策中所述。只有在 TargetEndpoint 參照 TLS/SSL 端點時,這個屬性才有意義。 |
servicecallout.{policy-name}.failed |
範圍:從 ServiceCallout 回應開始 布林值,指出政策是否成功 (false) 或失敗 (true)。 |
錯誤
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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:
|
build |
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. |
build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 |
The Request variable specified in the policy is not of type RequestMessage. For
example, if it's a Response type, you'll see this error. |
build |
googletoken.EmptyIDTokenAudience |
500 |
|
|
messaging.adaptors.http.filter.GoogleTokenGenerationFailure |
500 |
This error can happen if the API proxy is configured with the <Authentication>
element. Possible causes include:
<GoogleAccessToken> element is used and one or more
invalid scopes are provided. For example, look for typos or empty scopes.
For Apigee hybrid only, check the runtime container's log and search for
|
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. |
build |
ConnectionInfoMissing |
This error happens if the policy does not have an
<HTTPTargetConnection> or <LocalTargetConnection>
element. |
build |
InvalidTimeoutValue |
This error happens if the <Timeout> value is negative or zero. |
build |
FAILED_PRECONDITION |
This error happens if the service account is missing when the proxy is
configured with the <Authentication> tag.
For example: Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
account identity, but one was not provided with the request. |
|
PERMISSION_DENIED |
This error happens if there is a permission problem with the service account if
the proxy is
configured with the <Authentication> tag. Possible causes:
|
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="RequestVariableNotMessageType">
<Step>
<Name>AM-RequestVariableNotMessageType</Name>
</Step>
<Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>相關主題
- 生成或修改訊息:AssignMessage 政策
- 擷取變數:ExtractVariables 政策
- 變數:流程變數參考資料
- 傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 設定
- 傳輸層安全標準 (TLS) 設定選項
- API Proxy 設定參考資料中的「TLS/SSL TargetEndpoint Configuration」(TLS/SSL TargetEndpoint 設定)
- HTTP 傳輸屬性:端點屬性參考資料
- ServiceCallout 的替代方案:以 JavaScript 編寫的 HTTPClient,請參閱 JavaScript 物件模型。