本页面适用于 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 |
无 | 必需 |
政策的内部名称。 （可选）使用 |
continueOnError |
false | 可选 | 设置为 false 可在政策失败时返回错误。这是大多数政策的预期行为。设置为 true，即使在政策失败后，仍可以继续执行流。另请参阅：
|
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 |
| 是否必需？ | 可选 |
| 类型 | Boolean |
| 父元素 |
<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 变量，并且访问此变量将导致错误。
如需详细了解各种类型的流变量，请参阅流变量参考。
错误代码
本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 原因 |
|---|---|---|
steps.publishmessage.PermissionDeniedError |
500 |
如果运行时服务账号无法模拟代理服务账号，或者代理服务账号无权向主题发布消息，则会发生此错误。 |
steps.publishmessage.ExecutionError |
500 |
如果在向 Pub/Sub 时发布消息时出现意外错误，则会发生此错误。您可以在错误消息中查看错误的详细信息。 |
steps.publishmessage.MessageVariableNotMessageType |
500 |
如果您在 UseMessageAsSource 中指定的变量名称无法解析，或者不是消息类型，就会发生此错误。
|
故障变量
只要政策中存在执行错误，Apigee 就会生成错误消息。您可以在错误响应中查看这些错误消息。很多时候，系统生成的错误消息可能与您的产品上下文无关。您可能希望根据错误类型自定义错误消息，以使消息更有意义。
如需自定义错误消息，可以使用故障规则或 RaiseFault 政策。如需了解故障规则与 RaiseFault 政策之间的差异，请参阅 FaultRule 与 RaiseFault 政策。您必须使用故障规则和 RaiseFault 政策中的 Condition 元素来检查条件。
Apigee 提供每个政策独有的故障变量，并在政策触发运行时错误时设置故障变量的值。
通过使用这些变量，您可以检查特定的错误情况并采取适当的操作。如需详细了解如何检查错误条件，请参阅构建条件。
| 变量 | 其中 | 示例 |
|---|---|---|
fault.name |
fault.name 可以匹配运行时错误表中列出的任何故障。故障名称是故障代码的最后一部分。 |
fault.name Matches "UnresolvedVariable" |
publishmessage.POLICY_NAME.failed |
POLICY_NAME 是抛出故障的政策的用户指定名称。 | publishmessage.publish-message-1.failed = true |