額外資訊摘要政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

使用 ExtensionCallout 政策，將擴充功能併入 API Proxy。

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

如要瞭解擴充功能，請參閱「什麼是擴充功能？」如需入門教學課程，請參閱「教學課程：新增及使用擴充功能」。

如要透過 ExtensionCallout 政策存取擴充功能，您必須先新增、設定及部署擴充功能，該擴充功能來自已安裝至 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 擴充功能的完整教學課程，請參閱「教學課程：使用擴充功能」。

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

關於 ExtensionCallout 政策

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

使用這項政策前，請先準備好：

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

在 PostClientFlow 中使用 ExtensionCallout 政策

您可以從 API Proxy 的 PostClientFlow 叫用 ExtensionCallout 政策。 回應傳送至要求用戶端後，系統會執行 PostClientFlow，確保所有指標都可供記錄。如要瞭解如何使用 PostClientFlow，請參閱「API Proxy 設定參考資料」。

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

• 如果您是 Apigee Edge for Public Cloud 客戶，features.allowExtensionsInPostClientFlow 標記預設會設為 true。

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

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

元素參考資料

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

<ConnectorCallout> 屬性

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

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

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

<DisplayName>Policy Display Name</DisplayName>

<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 Extension 擴充功能的 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 -->

收到回應後，回應值會放入您在此指定的變數，您可從其他 API Proxy 程式碼存取該變數。

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

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

<Output> 屬性

流程變數

無。

錯誤代碼

如「政策錯誤參考資料」所述，Apigee Edge 政策傳回的錯誤會採用一致的格式。

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

執行階段錯誤

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

部署錯誤

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