ExtensionCallout 政策

您正在查看 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 扩展程序的完整教程，请参阅教程：使用扩展程序。

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

ExtensionCallout 政策简介

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

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

• 您想通过此政策访问的外部资源的一些详细信息。这些详细信息将特定于相应资源。例如，如果政策将访问您的 Cloud Firestore 数据库，您需要知道要创建或访问的集合和文档名称。您通常会在配置此政策的请求和响应处理时使用特定于资源的信息。
• 已添加、配置和部署到 API 代理将部署到的环境中的扩展程序。换句话说，如果您要使用此政策访问特定的 Google Cloud 服务，则您的环境中必须存在该服务的已部署扩展程序。配置详细信息通常包含用于缩小资源访问范围的必需信息，例如项目 ID 或账号名称。

在 PostClientFlow 中使用 ExtensionCallout 政策

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

如果您想使用 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">

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

<DisplayName> 元素

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

<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 代理的客户端的 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 代理代码访问该变量。

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

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

<Output> 属性

流变量

无。

错误代码

Apigee Edge 政策返回的错误遵循一致的格式，如政策错误参考文档中所述。

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

运行时错误

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

部署错误

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