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 政策。

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

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

<?xml version="1.0" encoding="UTF-8"?><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>

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>{flow-variable-1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

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

子元素参考

<DisplayName>

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

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

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

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

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

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

<Source>

指定要发布的消息。

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

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

 <Source>SOURCE</Source>

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

<Source>source-message-text-01</Source>

<CloudPubSub>

<Topic> 的父元素。

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

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

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

<CloudPubSub>
  <Topic>projects/{request.header.project}/topics/{request.header.topic}</Topic>
</CloudPubSub>

<Topic>

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

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

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

<Topic>TOPIC_NAME</Topic>

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

<IgnoreUnresolvedVariables>

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

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

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

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

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

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

流变量

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

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

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

错误代码

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

运行时错误

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

故障变量

只要政策中存在执行错误，Apigee 就会生成错误消息。您可以在错误响应中查看这些错误消息。很多时候，系统生成的错误消息可能与您的产品上下文无关。您可能希望根据错误类型自定义错误消息，以使消息更有意义。

如需自定义错误消息，可以使用故障规则或 RaiseFault 政策。如需了解故障规则与 RaiseFault 政策之间的差异，请参阅 FaultRule 与 RaiseFault 政策。您必须使用故障规则和 RaiseFault 政策中的 Condition 元素来检查条件。Apigee 提供每个政策独有的故障变量，并在政策触发运行时错误时设置故障变量的值。通过使用这些变量，您可以检查特定的错误情况并采取适当的操作。如需详细了解如何检查错误条件，请参阅构建条件。