服務呼叫政策

本頁內容適用於 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 設定目標伺服器及設定負載平衡，請參閱在後端伺服器之間進行負載平衡。

---

注意：如果您使用 Apigee Hybrid 1.14 以上版本，且貴機構有權使用 Enhanced per-environment proxy limits 功能，則必須在 overrides.yaml 檔案中將 enhanceProxyLimits 屬性設為 true，才能使用 ServiceCallout 政策。

關於 ServiceCallout 政策

在 API Proxy 中，您可以在許多情境中使用 ServiceCallout 政策。舉例來說，您可以設定 API 代理，呼叫外部服務來提供地理位置資料、顧客評論、合作夥伴零售目錄中的項目等。

一般來說，呼叫會搭配另外兩項政策使用：AssignMessage 和 ExtractVariables。

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

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

  注意：ServiceCallout 中的要求和回應訊息標頭已是變數，如「流程變數」一節所述。您不需要使用 ExtractVariables 政策擷取這些變數。

典型的 ServiceCallout 政策組合包括：

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

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

   如要提升效能，您也可以快取 ServiceCallout 回應，詳情請參閱「如何將 ServiceCallout 政策的結果儲存在快取中，並在之後從快取中擷取？」一文。

3. ExtractVariables 政策：通常會定義 JSONPath 或 XPath 運算式，用於剖析 ServiceCallout 產生的訊息。接著，政策會設定變數，其中包含從 ServiceCallout 回應剖析的值。

注意：ServiceCallout 的替代方法是使用 JavaScript 物件模型，以 JavaScript 編寫 HTTPClient。

自訂錯誤處理

範例： 邊做邊學！
這個「瞭解 Apigee」範例說明如何檢查 ServiceCallout 回應中的 HTTP 程式碼，並根據程式碼的值擲回自訂例外狀況。如果目標服務傳回 404 狀態，這個範例會傳回自訂錯誤訊息。只要複製存放區，然後按照該主題中的指示操作即可。這個範例說明處理 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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	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 政策相同。

<Set> 和 <Add> 的子元素支援名為「訊息範本」的變數字串替代功能。

如果無法解析要求訊息，或要求訊息類型無效，政策就會傳回錯誤。

在最簡單的範例中，您會傳遞包含要求訊息的變數，該訊息已在 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"/> 以下說明這些預設值的意義。首先，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 元素，後續步驟就無法處理目標的回應，且 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> 元素中，使用流程變數建構網址。

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

預設	不適用
外觀狀態	必填
類型	不適用

<HTTPTargetConnection>/<Authentication> 元素

Apigee Hybrid 使用者：如果您使用 Apigee Hybrid，請注意這項功能僅支援 Apigee Hybrid 1.6.x 以上版本。

產生 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 政策擷取密鑰。

<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 子項元素

指定存取權杖的效期 (以秒為單位)。

注意： LifetimeInSeconds 的預設值為 3600。除非您想降低存取權杖外洩的風險或提升效能，否則不建議變更預設值。

預設	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。

Apigee Hybrid 使用者： 如果您使用 Apigee Hybrid，請注意 useTargetUrl 屬性適用於 Apigee Hybrid 1.8 以上版本。

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

要呼叫的服務網址：

<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 設定參考資料。

注意：在 SSLInfo 元素中指定 KeyStore 名稱，做為 ref://mykeystoreref 格式的參照。建議使用參照，而非直接名稱或流程變數。請參閱關於設定 <KeyStore> 和 <TrustStore> 元素的說明。

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

呼叫一或多個目標伺服器，並對這些伺服器進行負載平衡。請參閱「範例」一節中的「呼叫目標伺服器」範例。另請參閱跨後端伺服器負載平衡。另請參閱目標端點/伺服器呼叫，瞭解如何透過 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 端點名稱。這是以 <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>

預設	不適用
外觀狀態	選用
類型	不適用

結構定義

範例：如要查看最新結構定義，請參閱 GitHub 存放區範例。

流程變數

流程變數可讓政策和流程在執行階段根據 HTTP 標頭、訊息內容或流程環境，動態調整行為。服務呼叫政策執行後，可以使用下列預先定義的 Flow 變數。如要進一步瞭解流程變數，請參閱「流程變數參考資料」。

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

變數	說明
以下範例說明如何取得 ServiceCallout 要求和回應標頭，與取得主要要求和回應標頭的方式類似。 calloutResponse.header.HeaderName myRequest.header.HeaderName 其中 calloutResponse 是服務呼叫中「回應」的變數名稱，myRequest 則是「要求」的變數名稱。例如： 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 要求開始 類型：字串 權限：讀取/寫入 TargetEndpoint 的預期通用名稱，如 ServiceCallout 政策中所述。只有在 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

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

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

相關主題

• 生成或修改訊息：AssignMessage 政策
• 擷取變數：ExtractVariables 政策
• 變數：流程變數參考資料
• 傳輸層安全標準 (TLS)/安全資料傳輸層 (SSL) 設定
  • 傳輸層安全標準 (TLS) 設定選項
  • API Proxy 設定參考資料中的「TLS/SSL TargetEndpoint Configuration」
• HTTP 傳輸屬性：端點屬性參考資料
• ServiceCallout 的替代方案：以 JavaScript 編寫的 HTTPClient，請參閱 JavaScript 物件模型。