ExtensionCallout 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档。 信息

使用 ExtensionCallout 政策将扩展程序合并到 API 代理中。

扩展程序可访问 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 扩展程序的完整教程。

如需查看所有可用扩展程序的示例，请参阅扩展程序参考概览。

关于“附加信息宣传信息”政策

如果您想使用已配置的扩展程序通过 API 代理访问外部资源，请使用 ExtensionCallout 政策。

在使用此政策之前，您需要：

• 关于您希望通过此政策访问的外部资源的一些详细信息。这些详细信息因资源而异。例如，如果政策将访问您的 Cloud Firestore 数据库，您需要知道要创建或访问的集合和文档名称。在配置此政策的请求和响应处理方式时，您通常需要使用特定于资源的信息。
• 添加、配置和部署扩展程序 部署到将在其中部署 API 代理的环境。也就是说， 如果您要使用此政策访问特定 Google Cloud 服务， 那么您的环境中必须存在为该服务部署的扩展程序。 配置详细信息通常包括缩小范围所需的信息 对资源的访问权限，例如项目 ID 或账号名称。

在 PostClientFlow 中使用 ExtensionCallout 政策

您可以从 API 代理的 PostClientFlow 调用 ExtensionCallout 政策。 PostClientFlow 在响应发送到请求的客户端后执行， 这可确保所有指标都可用于日志记录。 如需详细了解如何使用 PostClientFlow，请参阅 API 代理配置参考文档。

如果您想使用 ExtensionCallout 政策来调用 Google Cloud Logging 扩展程序 来自 PostClientFlow 时，请确保 features.allowExtensionsInPostClientFlow 标志 设为 true。

• 如果您是面向公有云的 Apigee Edge 的客户， features.allowExtensionsInPostClientFlow 标志默认设置为 true。

• 如果您是适用于私有云的 Apigee Edge 客户，请使用 更新组织属性 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>

&lt;ConnectorCallout&gt;属性

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

下表介绍了所有政策父元素通用的特性：

<DisplayName> 元素

除了用于 name 属性之外，还可以用于在管理界面代理编辑器中给政策添加不同的自然语言名称标签。

<DisplayName>Policy Display Name</DisplayName>

&lt;Action&gt;元素

政策应调用的公开操作。

<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 代理的客户端的 IP 地址：

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

如果您希望 JSON 中的属性值在运行时用引号引起来，请务必在 JSON 代码中使用引号。即使您将 Flow 变量指定为要在运行时解析的 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 代理代码访问该值。

扩展程序响应对象采用 JSON 格式。政策处理 JSON 的方式有两种：

• 已解析（默认）：此政策会解析 JSON 对象，并使用 JSON 数据自动生成变量。例如，如果 JSON 包含 "messageId" : 12345; 且您将输出变量命名为 extensionOutput，则可以使用变量 {extensionOutput.messageId} 在其他政策中访问该消息 ID。
• 未解析：输出变量包含来自扩展程序的未解析原始 JSON 响应。（如果需要，您仍然可以使用 JavaScript 政策在单独的步骤中解析响应值。）

&lt;Output&gt;属性

流变量

无。

错误代码

从 Apigee Edge 政策返回的错误会采用一致的格式，如政策错误参考中所述。

本部分介绍了此政策触发错误时设置的错误消息和流程变量。在为代理开发故障规则时，请务必了解这些信息。如需了解详情，请参阅关于政策错误的须知事项和处理错误。

运行时错误

政策执行时可能会发生这些错误。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。