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 客户，默认情况下，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>

<ConnectorCallout> 属性

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

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

属性	说明	默认	状态
name	政策的内部名称。name 属性的值可以包含字母、数字、空格、连字符、下划线和英文句点。此值不能超过 255 个字符。 （可选）使用 <DisplayName> 元素在管理界面代理编辑器中给政策添加不同的自然语言名称标签。	不适用	必需
continueOnError	设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。 设置为 true，即使在政策失败后，仍可以继续执行流。	false	可选
enabled	设置为 true 可强制执行政策。 设为 false 可关闭政策。即使政策仍附加到某个流，也不会强制执行该政策。	true	可选
async	此特性已弃用。	false	已弃用

<DisplayName> 元素

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

<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 代理的客户端的 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 流变量值。

<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 代理代码从该变量访问该值。

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

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

<Output> 属性

属性	说明	默认	在家/外出状态
parsed	解析该扩展程序返回的 JSON 对象，以便其他政策可将 JSON 对象中的数据作为变量访问。	true	可选

流变量

无。

错误代码

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

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

运行时错误

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

错误名称	HTTP 状态	原因
ExecutionFailed	500	扩展程序响应了错误。

部署错误

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

错误名称	发生的条件	修复
InvalidConnectorInstance	<Connector> 元素为空。	build
ConnectorInstanceDoesNotExists	环境中不存在 <Connector> 元素中指定的扩展程序。	build
InvalidAction	ExtensionIDFA 政策中的 <Action> 元素缺失或设为空值。	build
AllowExtensionsInPostClientFlow	禁止在 PostClient 流中使用 Extension callout 政策。	build