PublishMessage 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

概览

通过 PublishMessage 政策，您可以将 API 代理流信息发布到 Google Cloud Pub/Sub 主题。Google 的 Pub/Sub 允许服务异步通信，从而显著缩短延迟时间。如需详细了解 Pub/Sub，请参阅什么是 Pub/Sub？您要发布到 Pub/Sub 主题的信息可以是字面量文本，也可以是流变量。您还可以使用消息模板指定字面量文本和流变量的组合。

如果发布请求成功，Apigee 会将 publishmessage.message.id 流变量设置为 Pub/Sub 服务器返回的值。如需了解详情，请参阅流变量。

此政策为标准政策，可部署到任何环境类型。如需了解政策类型以及在每种环境类型中的可用性，请参阅政策类型。

身份验证和代理部署

如需运行 PublishMessage 政策，您需要一个身份验证令牌。但是，政策定义中没有显式的 <Authentication> 元素。您必须部署 API 代理使用 Google 身份验证，该操作会在后台为请求添加身份验证令牌。如需了解如何部署使用 Google 身份验证的 API 代理，请参阅部署步骤。除了在 API 代理中使用 Google 身份验证之外，您还必须使用其角色具有 pubsub.topics.publish 权限的服务账号部署 API 代理。如需详细了解 Pub/Sub 的 Identity and Access Management (IAM) 角色，请参阅权限和角色。

`<PublishMessage>`

指定 PublishMessage 政策。

默认值	不适用
是否必需？	必需
类型	复杂类型
父元素	不适用
子元素	`<Attributes>` `<CloudPubSub>` `<DisplayName>` `<IgnoreUnresolvedVariables>` `<Source>` `<UseMessageAsSource>`

下表提供了 <PublishMessage> 的子元素的简要说明：

子元素	是否必需？	说明
`<Attributes>`	可选	要附加到 Pub/Sub 消息的一组属性。
`<CloudPubSub>`	必需	`<Topic>` 的父元素。`<Topic>` 元素指定要在其中发布消息的 Pub/Sub 主题。
`<DisplayName>`	可选	政策的自定义名称。
`<IgnoreUnresolvedVariables>`	可选	指定在 Apigee 遇到未解析变量时是否停止处理。
`<Source>`	可选	指定要发布到 Pub/Sub 主题的消息。此元素为可选元素，但您必须使用 `<Source>` 或 `<UseMessageAsSource>`。
`<UseMessageAsSource>`	可选	指定要发布到 Pub/Sub 主题的消息。此元素为可选元素，但您必须使用 `<Source>` 或 `<UseMessageAsSource>`。
其他子元素
`<Topic>`	必需	`<CloudPubSub>` 的子元素。指定要向其发布消息的 Pub/Sub 主题。

<PublishMessage> 元素使用以下语法：

语法

<PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1">
    <DisplayName>DISPLAY_NAME</DisplayName>
    <Source>SOURCE_VALUE</Source>
    <CloudPubSub>
        <Topic>TOPIC_NAME</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PublishMessage>

示例 - 来源

以下示例展示了 <PublishMessage> 政策的定义：

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>this is a message template {flow-variable1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

示例 - UseMessageAsSource

此 <PublishMessage> 政策指定了 UseMessageAsSource 元素：

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-2">
    <UseMessageAsSource>request</UseMessageAsSource>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

示例 - 属性

此 <PublishMessage> 政策指定了 Attributes 元素：

<PublishMessage name="Publish-Message-3">
  <Source>this is a message template {flow-variable1}</Source>
  <Attributes>
    <Attribute name='attr-name-0'>fixed-value</Attribute>
    <Attribute name='another-attribute-name'>{request.queryparam.attr1}</Attribute>
    <Attribute name='a-third-attribute-name'>{request.queryparam.attr2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
  </CloudPubSub>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

此元素具有所有政策中常见的以下属性：

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

子元素参考

本部分介绍 <PublishMessage> 的子元素。

`<Attributes>`

指定要附加到 Pub/Sub 消息的属性。

每个属性都是一个键值对。与属性关联的名称应该是唯一的。每个属性的值在运行时通过消息模板动态确定。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<PublishMessage>`
子元素	无

<Attributes> 元素使用以下语法：

语法

  <Attributes>
    <Attribute name='NAME-1'>fixed-value</Attribute>
    <Attribute name='NAME-2'>{flow-variable}</Attribute>
    ...
    <Attribute name='NAME-N'>message template here {flow-variable:default-value}</Attribute>
  </Attributes>

示例 1

以下示例在发布消息时为消息设置具有固定值的单个属性：

<PublishMessage name="PM-with-one-attribute">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{request.queryparam.message}</Source>
  <Attributes>
    <Attribute name='my-attribute-1'>fixed-value</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{request.queryparam.project}/topics/{request.queryparam.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

示例 2

以下示例在发布消息时为消息设置多个属性；其中一些属性的值在运行时动态确定：

<PublishMessage name="PM-with-multiple-attributes">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{my-assembled-message}</Source>
  <Attributes>
    <Attribute name='attr-0'>fixed-value</Attribute>
    <Attribute name='attr-1'>{flow-variable1}</Attribute>
    <Attribute name='attr-2'>fixed portion {flow-variable2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

`<DisplayName>`

除了用于 name 属性之外，还可用于在管理界面代理编辑器中使用其他更加自然的名称标记政策。

<DisplayName> 元素适用于所有政策。

默认值	不适用
是否必需？	可选。如果省略 `<DisplayName>`，则会使用政策的 `name` 属性的值
类型	字符串
父元素	<`PolicyElement`>
子元素	无

<DisplayName> 元素使用以下语法：

语法

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

示例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 元素没有属性或子元素。

`<Source>`

指定要发布的消息。

消息可以是消息模板形式的字面量文本、流变量或两者的组合。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<PublishMessage>`
子元素	无

<Source> 元素使用以下语法：

语法

 <Source>SOURCE</Source>

Example-1

以下示例将来源消息设置为 flow-var-1 流变量的值：

<Source>{flow-var-1}</Source>

Example-2

以下示例使用消息模板发布包含动态内容的 JSON 消息：

<PublishMessage name="PM-with-source-template">
  <Source>{
    "name": "value-1",
    "count": "{flow-variable1}",
    "action": "{flow-variable2}"
  }</Source>
  <Attributes>
    <Attribute name='content-type'>application/json</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

`<CloudPubSub>`

<Topic> 的父元素。

您只能发布到一个 Pub/Sub 主题。因此，<CloudPubSub> 元素中只能有一个 <Topic> 元素。

默认值	不适用
是否必需？	必需
类型	复杂类型
父元素	`<PublishMessage>`
子元素	`<Topic>`

<CloudPubSub> 元素使用以下语法：

语法

<CloudPubSub>
  <Topic>TOPIC_NAME</Topic>
</CloudPubSub>

示例

以下示例展示了 <CloudPubSub> 元素的声明：

<CloudPubSub>
  <Topic>projects/{my-project}/topics/{my-topic}</Topic>
</CloudPubSub>

`<Topic>`

指定要向其发布 <Source> 消息的 Pub/Sub 主题。

您必须以 projects/project-id/topics/topic-name 格式指定主题名称。

默认值	不适用
是否必需？	必需
类型	字符串
父元素	`<CloudPubSub>`
子元素	无

<Topic> 元素使用以下语法：

语法

<Topic>TOPIC_NAME</Topic>

示例

以下示例指定要发布到的 Pub/Sub 主题：

<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>

在此示例中，project-id-marketing 是您的 Google Cloud 项目 ID，topic-name-test1 是应在其中发布消息的主题。

`<UseMessageAsSource>`

指定要发布的消息。

使用此元素可替代 <Source> 元素。值应为引用消息的流变量的名称，例如 request、response 或 message。指定此元素后，政策会使用消息的内容作为要发布的消息。当消息内容是无法表示为字符串的八位字节流（例如来自二进制文件的内容）时，您应使用此元素，而不是 <Source>。

默认值	不适用
是否必需？	可选
类型	字符串
父元素	`<PublishMessage>`
子元素	无

<UseMessageAsSource> 元素使用以下语法：

语法

<PublishMessage name="PM-with-use-message-as-source">
  <UseMessageAsSource>MESSAGE_NAME</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flowvar1}/topics/{flowvar-topic}</Topic>
  </CloudPubSub>
</PublishMessage>

Example-1

以下示例指示政策使用请求消息的内容作为 Pub/Sub 消息的载荷：

<PublishMessage name="PM-with-use-message-as-source">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <UseMessageAsSource>request</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

`<IgnoreUnresolvedVariables>`

指定在 Apigee 遇到未解析变量时是否停止处理。

默认值	False
是否必需？	可选
类型	布尔值
父元素	`<PublishMessage>`
子元素	无

将值设置为 true 以忽略无法解析的变量并继续处理；否则为 false。默认值为 false。

将 <IgnoreUnresolvedVariables> 设置为 true 与将 <PublishMessage> 的 continueOnError 设置为 true 不同。如果将 continueOnError 设置为 true，Apigee 会忽略所有错误，而不仅仅是变量中的错误。

<IgnoreUnresolvedVariables> 元素使用以下语法：

语法

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

示例

以下示例将 <IgnoreUnresolvedVariables> 设置为 true：

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

流变量

流变量是保存特定数据的对象，您可以在 API 代理流的上下文中使用。这些变量存储载荷信息、网址路径、IP 地址以及政策执行中的数据。如需详细了解流变量，请参阅使用流变量。

如果 PublishMessage 政策成功发布到 Pub/Sub 主题，Apigee 会将 publishmessage.message.id 流变量设置为 Pub/Sub 服务器返回的 messageId。流变量为字符串类型，并且从代理请求流起您可以使用变量。根据您的要求，您可以在其他下游政策中使用流变量。但是，如果发布失败，Apigee 不会设置 publishmessage.message.id 变量，并且访问此变量将导致错误。

如需详细了解各种类型的流变量，请参阅流变量参考。

错误代码

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.publishmessage.PermissionDeniedError`	`500`	This error occurs when the runtime service account cannot impersonate the proxy service account or the proxy service account does not have the permission to publish to the topic.
`steps.publishmessage.ExecutionError`	`500`	This error occurs if there was an unexpected error while publishing the message to Pub/Sub. You can view the details of the error in the error message.
`steps.publishmessage.MessageVariableNotMessageType`	`500`	This error occurs if the variable name you specified in `UseMessageAsSource` cannot be resolved, or is not a message type.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
`fault.name`	The `fault.name` can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	`fault.name Matches "UnresolvedVariable"`
`publishmessage.POLICY_NAME.failed`	`POLICY_NAME` is the user-specified name of the policy that threw the fault.	`publishmessage.publish-message-1.failed = true`

For more information about policy errors, see What you need to know about policy errors

PublishMessage 政策 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

身份验证和代理部署

<PublishMessage>

语法

示例 - 来源

示例 - UseMessageAsSource

示例 - 属性

子元素参考

<Attributes>

语法

示例 1

示例 2

<DisplayName>

语法

示例

<Source>

语法

Example-1

Example-2

<CloudPubSub>

语法

示例

<Topic>

语法

示例

<UseMessageAsSource>

语法

Example-1

<IgnoreUnresolvedVariables>

语法

示例

流变量

错误代码

Runtime errors

Fault variables

PublishMessage 政策

`<PublishMessage>`

`<Attributes>`

`<DisplayName>`

`<Source>`

`<CloudPubSub>`

`<Topic>`

`<UseMessageAsSource>`

`<IgnoreUnresolvedVariables>`