服務呼叫政策

本頁適用於 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。

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

範例

對內部 Proxy 的本機呼叫

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

這個範例會建立對本地 API Proxy (即同一個組織和環境中的 Proxy) 的呼叫，該 Proxy 名為 data-manager，並指定其 Proxy 端點名稱為 default。

將網址設為變數

<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 編寫的自訂程式碼進行剖析。這項政策會等待 30 秒，等待 Google Geocoding API 回應，然後才會逾時。

呼叫目標伺服器

<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 中使用 ServiceCallout 政策。舉例來說，您可以設定 API 代理程式，以便呼叫外部服務，提供地理位置資料、顧客評論、合作夥伴零售目錄中的商品等等。

說明文字通常會與其他兩項政策一併使用：AssignMessage 和 ExtractVariables。

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

  • Response：ExtractVariables 會剖析回應並擷取特定內容。

一般 ServiceCallout 政策組合包含：

  1. AssignMessage 政策：建立要求訊息、填入 HTTP 標頭、查詢參數、設定 HTTP 動詞等。

  2. ServiceCallout 政策：參照由 AssignMessage 政策建立的訊息，定義外部呼叫的目標網址，並為目標服務傳回的回應物件定義名稱。

    為改善效能，您也可以快取 ServiceCallout 回應，如這篇文章所述。

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

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

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

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

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<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>
預設 如果您省略要求元素或任何屬性，Apigee 會指派下列預設值：

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

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

如果您使用資料遮罩功能，請務必瞭解這個預設名稱。如果省略變數名稱，您需要在遮罩設定中加入 servicecallout.request。舉例來說，如果您想遮蓋授權標頭，讓其不會顯示在偵錯工作階段中，請在遮罩設定中加入下列內容，擷取預設名稱：

servicecallout.request.header.Authorization。
在家狀態 選用。
類型 不適用

屬性

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

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

 servicecallout.request 選用
clearPayload

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

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

 是 選用

<Request>/<IgnoreUnresolvedVariables> 元素

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

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

<Response> 元素

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

當這個元素出現時，它會指定變數名稱，該變數會包含從外部服務收到的回應訊息。只有在政策成功讀取整個回應時，才會將目標的回應指派給變數。如果遠端呼叫因任何原因失敗，政策就會傳回錯誤。

如果省略這個元素，API Proxy 就不會等待回應；API Proxy 流程執行作業會繼續執行後續流程步驟。此外，如您所知，如果沒有 Response 元素，系統就無法處理目標的回應，代理程式流程也無法偵測遠端呼叫中的失敗。使用 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 Cloud 產品 (例如 Cloud Functions 和 Cloud Run) 執行的 Google 服務和自訂服務發出經過驗證的呼叫。如要使用這個元素，您必須按照「使用 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 政策擷取密鑰。

<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 的呼叫。

<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 的選項，以及 API 代理程式設定參考資料中的「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>/<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 名稱。代理程式必須與發出呼叫的代理程式位於相同的機構和環境。

<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 標頭、訊息內容或流程內容，在執行階段啟用政策和流程的動態行為。執行 ServiceCallout 政策後，您可以使用下列預先定義的 Flow 變數。如要進一步瞭解 Flow 變數，請參閱「Flow 變數參考資料」。

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

變數 說明

以下是取得 ServiceCallout 要求和回應標頭的範例，類似於從主要要求和回應取得標頭的方式。

calloutResponse.header.HeaderName

myRequest.header.HeaderName

其中 calloutResponse 是服務快訊中 Response 的變數名稱，而 myRequest 則是 Request 的變數名稱。例如：

calloutResponse.header.Content-Length

傳回 ServiceCallout 回應的 Content-Length 標頭。

範圍：從 ServiceCallout 開始
類型：字串
權限：讀取/寫入

ServiceCallout 要求或回應中的訊息標頭。舉例來說，如果 API 代理程式目標是 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 的目標網址。

calloutResponse.content

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

範圍：從 ServiceCallout 回應傳送
類型：字串
權限：讀取/寫入

ServiceCallout 的回應主體。
servicecallout.{policy-name}.expectedcn

範圍：從 ServiceCallout 要求傳遞
類型：字串
權限：讀取/寫入

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

範圍：從 ServiceCallout 回應傳送
類型：布林值
權限：讀取/寫入

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

錯誤

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

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

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

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

<GoogleIDToken> 已啟用，但 useTargetUrl 設為 false，且在發生錯誤時，沒有直接或透過參照的方式將值提供給 <Audience>。
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 如果 API Proxy 是使用 <Authentication> 元素進行設定，就可能發生此錯誤。可能的原因包括：
  • 透過 Proxy 部署的服務帳戶：
    • 不存在於專案中
    • 已停用
    • (僅限 Apigee hybrid) 未將 roles/iam.serviceAccountTokenCreator 角色授予 apigee-runtime 服務帳戶。
  • apigee-runtime 服務帳戶的來源專案已停用 IAMCredentials API。
  • 使用 <GoogleAccessToken> 元素，且提供一或多個無效範圍。例如，檢查是否有錯字或空白範圍。

    • 僅限 Apigee hybrid：請檢查執行階段容器的記錄，並搜尋 GoogleTokenGenerationFailure，找出可能有助於偵錯的問題的詳細錯誤訊息。

    部署錯誤

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

    錯誤名稱 原因 修正
    URLMissing <HTTPTargetConnection> 內部缺少或空白 <URL> 元素。
    ConnectionInfoMissing 如果政策沒有 <HTTPTargetConnection> 或 <LocalTargetConnection> 元素，就會發生這項錯誤。
    InvalidTimeoutValue 如果 <Timeout> 值為負數或零，就會發生這個錯誤。
    FAILED_PRECONDITION 如果使用 <Authentication> 標記設定 Proxy 時缺少服務帳戶，就會發生這個錯誤。

    例如：

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED 如果 Proxy 是使用 <Authentication> 標記設定，而服務帳戶有權限問題，就會發生這個錯誤。可能的原因：
    • 服務帳戶不存在。
    • 服務帳戶並未在 Apigee 機構所屬的 Google Cloud 專案中建立。
    • 部署者確實具備服務帳戶的 iam.serviceAccounts.actAs 權限。詳情請參閱「關於服務帳戶權限」。

    錯誤變數

    這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

    變數 地點 範例
    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="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    相關主題