額外資訊摘要政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

使用 Extension callout 政策，將擴充功能納入 API Proxy。

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

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

透過 Extension callout 政策存取擴充功能之前，您必須從已安裝至 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 要部署的環境也就是 如果您想使用這項政策存取特定 Google Cloud 服務 那麼服務部署的擴充功能必須存在於您的環境中。 設定詳細資料通常包含縮小範圍的必要資訊 資源的存取權，例如專案 ID 或帳戶名稱。

在 PostClientFlow 中使用 Extension callout 政策

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

如果您想使用額外資訊摘要政策來呼叫 Google Cloud Logging 擴充功能 從 PostClientFlow 中，確認 features.allowExtensionsInPostClientFlow 標記 已在貴機構中設為 true。

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

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

從 PostClientFlow 呼叫 MessageLogging 政策的所有限制 您必須同時遵守「額外資訊摘要」政策的規定詳情請參閱「使用注意事項」一文。

元素參照

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

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

<DisplayName>元素

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

<DisplayName>Policy Display Name</DisplayName>

<Action>元素

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

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

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

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

<連接器>元素

已設定的擴充功能名稱。這是設定要在環境部署的擴充功能時，以環境為範圍的名稱。

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

擴充功能的設定值可能與部署的其他擴充功能因相同擴充功能套件而異。從相同套件設定的擴充功能之間，這些設定值可呈現重要的執行階段功能差異，因此請務必指定叫用的正確擴充功能。

&lt;Input&gt;元素

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 流程變數值「已」加上引號。

&lt;Output&gt;元素

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

<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 政策，透過另一個步驟剖析回應值)。

&lt;Output&gt;屬性

流程變數

無。

錯誤代碼

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

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

執行階段錯誤

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

部署錯誤

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