額外資訊摘要政策

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

使用擴充功能摘要政策，將擴充功能整合至 API Proxy。

這項擴充功能提供 Apigee Edge 外部的特定資源存取權。資源可能是 Google Cloud Platform 服務，例如 Cloud Storage 或 Cloud Speech-to-Text。不過，資源可以是任何透過 HTTP 或 HTTPS 存取的外部資源。

如需擴充功能的簡介，請參閱「什麼是擴充功能？」一文。如需入門教學課程，請參閱教學課程：新增及使用擴充功能。

如要透過擴充功能摘要政策存取擴充功能，您必須先透過已安裝至 Apigee Edge 機構的擴充功能套件，新增、設定及部署擴充功能。

範例

以下是與 Cloud Logging 擴充功能搭配使用的政策範例：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

如需使用 Cloud Logging 擴充功能的完整教學課程，請參閱教學課程：使用擴充功能。

如需所有可用擴充功能的範例，請參閱擴充功能參考資料總覽。

關於額外資訊摘要政策

如要使用已設定的擴充功能從 API Proxy 中存取外部資源，請使用 Extension callout 政策。

使用這項政策前，您必須：

• 提供一些詳細資料，說明您要透過這項政策存取的外部資源。這些詳細資料專屬於資源。舉例來說，如果這項政策會存取您的 Cloud Firestore 資料庫，您必須先知道要建立或存取的集合和文件名稱，設定這項政策的要求和回應處理時，您通常會使用資源專屬資訊。
• 將擴充功能新增、設定及部署 API Proxy 到要部署 API Proxy 的環境中。換句話說，如果要使用此政策存取特定 Google Cloud 服務，您的環境中必須存在於該服務中已部署的擴充功能。設定詳細資料通常包含縮小資源存取範圍的必要資訊，例如專案 ID 或帳戶名稱。

在 PostClientFlow 中使用 Extension 調 政策

您可以從 API Proxy 的 PostClientFlow 叫用擴充功能摘要政策。PostClientFlow 會在回應傳送至要求用戶端後執行，確保所有指標都能記錄。如要進一步瞭解如何使用 PostClientFlow，請參閱 API Proxy 設定參考資料。

如要使用 Extension callout 政策，從 PostClientFlow 呼叫 Google Cloud Logging 擴充功能，請確認貴機構的 features.allowExtensionsInPostClientFlow 旗標已設為 true。

• 如果您是公開雲端的 Apigee Edge 客戶，features.allowExtensionsInPostClientFlow 標記會預設為 true。

• 如果您是 Private Cloud 適用的 Apigee Edge，請使用更新機構屬性 API，將 features.allowExtensionsInPostClientFlow 標記設為 true。

所有從 PostClientFlow 呼叫 MessageLogging 政策的限制，也適用於 Extension callout 政策。詳情請參閱「使用注意事項」。

元素參照

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<Connector callout> 屬性

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

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

屬性	說明	預設	存在必要性
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 屬性值。
存在必要性	選用
類型	字串

<Action> 元素

擴充功能公開後應叫用政策的動作。

<Action>action-exposed-by-extension</Action>

預設	無
存在必要性	需要
類型	字串

每個擴充功能都有專屬的一組動作，可用來存取擴充功能代表的資源功能。您可以將動作視為透過這項政策呼叫的函式，並使用 <Input> 元素的內容指定函式的引數。動作的回應會儲存在您使用 <Output> 元素指定的變數中。

如需擴充功能函式清單，請參閱您透過這項政策呼叫的擴充功能參考資料。

<Connector> 元素

已設定使用的擴充功能名稱。這是將擴充功能設為部署至環境時所提供的環境範圍名稱。

<Connector>name-of-configured-extension</Connector>

預設	無
存在必要性	需要
類型	字串

擴充功能的設定值可能與其他已部署的擴充功能不同 (根據同一擴充功能套件建立)。這些設定值可能代表透過相同套件設定的擴充功能，在執行階段功能之間存在重要差異，因此請務必指定要叫用的擴充功能。

<Input> 元素

JSON，包含要傳送至擴充功能的要求主體。

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

預設	無
存在必要性	此為選填或必填屬性，視副檔名而定。
類型	字串

基本上，這必須是您透過 <Action> 元素指定動作的引數。<Input> 元素的值會因您要叫用的擴充功能和動作而異。如要進一步瞭解每個動作的屬性，請參閱擴充功能套件說明文件。

請注意，雖然許多 <Input> 元素值可以正確運作，但不會將其納入 <![CDATA[]]> 區段，但 JSON 規則允許無法剖析為 XML 的值。最佳做法是將 JSON 納入 CDATA 區段，避免執行階段剖析錯誤。

<Input> 元素的值是格式正確的 JSON，其屬性會指定要傳送至擴充功能動作要叫用的值。例如，Google Cloud Logging 擴充功能擴充功能的 log 動作會採用下列值指定要寫入的記錄 (logName)、要納入項目的中繼資料 (metadata)，以及記錄訊息 (data)。範例如下：

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

在 <Input> JSON 中使用流程變數

系統會將 <Input> 的內容視為訊息範本。也就是說，系統會在執行階段將以大括號括住的變數名稱替換為參照變數的值。

舉例來說，您可以改寫上述 <Input> 區塊，使用 client.ip 流程變數取得呼叫 API Proxy 的用戶端 IP 位址：

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

如果您希望在執行階段期間用引號括住 JSON 中的屬性值，請務必在 JSON 程式碼中使用引號。即使您將流程變數指定為要在執行階段解析的 JSON 屬性值，情況也是如此。

以下 <Input> 範例包含兩個流程變數參照：

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

在執行階段，JSON 屬性值會以下列方式解析：

• logName 屬性值 -- 字串常值 example-log。
• metadata 屬性值 - my.log.entry.metadata 流量變數值「不含」括號。如果變數值本身是代表物件的 JSON，這個方法就能派上用場。
• message 屬性值 - client.ip 流量變數值「含」前後的引號。

<Output> 元素

儲存擴充功能動作回應的變數名稱。

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

或

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

預設	無
存在必要性	此為選填或必填屬性，視副檔名而定。
類型	剖析的物件或字串 (視 parsed 屬性設定而定)。

收到回應時，回應值會放置在您在這裡指定的變數中，您可以從其他 API Proxy 程式碼存取該變數。

擴充功能回應物件採用 JSON 格式。政策處理 JSON 的方式有兩種：

• 剖析 (預設)：政策會剖析 JSON 物件，並自動產生包含 JSON 資料的變數。舉例來說，如果 JSON 包含 "messageId" : 12345;，且您將輸出變數命名為 extensionOutput，就能使用變數 {extensionOutput.messageId} 在其他政策中存取該訊息 ID。
• 未剖析：輸出變數包含擴充功能的原始未剖析 JSON 回應。(如有需要，您還是可以使用 JavaScript 政策，在另一個步驟剖析回應值)。

<Output> 屬性

屬性	說明	預設	存在必要性
剖析	剖析擴充功能傳回的 JSON 物件，允許其他政策以變數的形式存取 JSON 物件中的資料。	true	選用

流程變數

無。

錯誤代碼

Apigee Edge 政策傳回的錯誤遵循一致的格式，詳情請參閱政策錯誤參考資料。

本節說明這項政策觸發錯誤的錯誤訊息和流程變數。這項資訊是瞭解 Proxy 是否針對錯誤建立規則的重要資訊。詳情請參閱「政策錯誤相關須知」和「處理錯誤」。

執行階段錯誤

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

錯誤名稱	HTTP 狀態	原因
執行作業失敗	500	擴充功能傳回錯誤。

部署錯誤

當您部署包含此政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	發生時機	修正
InvalidConnectorInstance	<Connector> 元素空白。	build
ConnectorInstanceDoesNotExists	環境中沒有 <Connector> 元素中指定的擴充功能。	build
InvalidAction	ExtensionSummary 政策中的 <Action> 元素遺失或設為空白值。	build
AllowExtensionsInPostClientFlow	禁止在 PostClient 流程中使用 ExtensionSummary 政策。	build