PublishMessage policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

policy icon

Overview

The PublishMessage policy lets you publish your API proxy flow information to a Google Cloud Pub/Sub topic. Google's Pub/Sub allows services to communicate asynchronously, with significantly less latency. For more information about Pub/Sub, see What is Pub/Sub?. The information you want to publish to a Pub/Sub topic can be a literal text or a flow variable. You can also specify a combination of literal text and flow variables by using a message template.

If the publish request is successful, Apigee sets the publishmessage.message.id flow variable to the value returned by the Pub/Sub server. For more information, see Flow variables.

This policy is a Standard policy and can be deployed to any environment type. Not all users need to know about policy and environment types. For information on policy types and availability with each environment type, see Policy types.

Authentication and proxy deployment

To run the PublishMessage policy, you need an authentication token. However, there is no explicit <Authentication> element in the policy definition. You must deploy your API proxy to use Google authentication, which adds the authentication token to the request under the hood. For information on how to deploy an API proxy that uses Google authentication, see Deployment steps. Apart from using Google authentication in your API proxy, you must deploy your API proxy with a service account that has a role with the pubsub.topics.publish permission. For more information about Identity and Access Management (IAM) roles for Pub/Sub, see Permissions and roles.

`<PublishMessage>`

Specifies the PublishMessage policy.

Default Value	N/A
Required?	Required
Type	Complex type
Parent Element	N/A
Child Elements	`<CloudPubSub>` `<DisplayName>` `<Source>`

The following table provides a high-level description of the child elements of <PublishMessage>:

Child Element	Required?	Description
`<CloudPubSub>`	Required	Parent element of `<Topic>`. The `<Topic>` element specifies the Pub/Sub topic in which you want to publish your message.
`<DisplayName>`	Optional	A custom name for the policy.
`<IgnoreUnresolvedVariables>`	Optional	Specifies whether processing stops if Apigee encounters an unresolved variable.
`<Source>`	Required	Specifies the message to publish.
Other child elements
`<Topic>`	Required	Specifies the Pub/Sub topic to which you want to publish the message.

The <PublishMessage> element uses the following syntax:

Syntax

<?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>

Example

The following example shows the <PublishMessage> policy definition:

<?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>

This element has the following attributes that are common to all policies:

Attribute	Default	Required?	Description
`name`	N/A	Required	The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name.
`continueOnError`	false	Optional	Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. See also: Fault rules are triggered ONLY in an error state (about continueOnError) Handling faults within the current flow
`enabled`	true	Optional	Set to `true` to enforce the policy. Set to `false` to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
`async`	false	Deprecated	This attribute is deprecated.

Child element reference

This section describes the child elements of <PublishMessage>.

`<DisplayName>`

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, more natural-sounding name.

The <DisplayName> element is common to all policies.

Default Value	N/A
Required?	Optional. If you omit `<DisplayName>`, the value of the policy's `name` attribute is used.
Type	String
Parent Element	<`PolicyElement`>
Child Elements	None

The <DisplayName> element uses the following syntax:

Syntax

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

Example

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

The <DisplayName> element has no attributes or child elements.

`<Source>`

Specifies the message to publish.

The message can be a literal text, a flow variable, or a combination of both in the form of a message template.

Default Value	N/A
Required?	Required
Type	String
Parent Element	`<PublishMessage>`
Child Elements	None

The <Source> element uses the following syntax:

Syntax

 <Source>SOURCE</Source>

Example-1

The following example sets the source message to the value of the flow-var-1 flow variable:

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

Example-2

The following example sets the source message to source-message-text-01:

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

`<CloudPubSub>`

Parent element of <Topic>.

You can publish to only one Pub/Sub topic. Hence, you can have only one <Topic> element in the <CloudPubSub> element.

Default Value	N/A
Required?	Required
Type	Complex type
Parent Element	`<PublishMessage>`
Child Elements	`<Topic>`

The <CloudPubSub> element uses the following syntax:

Syntax

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

Example

The following example shows the declaration of the <CloudPubSub> element:

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

`<Topic>`

Specifies the Pub/Sub topic to which you want to publish the <Source> message.

You must specify the topic name in the projects/project-id/topics/topic-name format.

Default Value	N/A
Required?	Required
Type	Complex type
Parent Element	`<CloudPubSub>`
Child Elements	None

The <Topic> element uses the following syntax:

Syntax

<Topic>TOPIC_NAME</Topic>

Example

The following example specifies the Pub/Sub topic to publish to:

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

In this example, project-id-marketing is your Google Cloud Project ID and topic-name-test1 is the topic in which the <Source> message should be published.

`<IgnoreUnresolvedVariables>`

Specifies whether processing stops if Apigee encounters an unresolved variable.

Default Value	False
Required?	Optional
Type	Boolean
Parent Element	`<PublishMessage>`
Child Elements	None

Set the value to true to ignore unresolved variables and continue processing; otherwise false. The default value is false.

Setting <IgnoreUnresolvedVariables> to true is different from setting the <PublishMessage>'s continueOnError to true. If you set continueOnError to true, Apigee ignores all errors, not only errors in variables.

The <IgnoreUnresolvedVariables> element uses the following syntax:

Syntax

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

Example

The following example sets <IgnoreUnresolvedVariables> to true:

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Flow variables

Flow variables are objects that hold specific data and are available to you in the context of an API proxy flow. These variables store information such as payload information, URL path, IP addresses, and data from policy execution. For more information about flow variables, see Using flow variables.

If the PublishMessage policy successfully publishes to the Pub/Sub topic, Apigee sets the publishmessage.message.id flow variable to the messageId returned by the Pub/Sub server. The flow variable is of type string, and the variable is available to you from the Proxy request flow onwards. Based on your requirement, you can use the flow variable in other downstream policies. However, if the publish fails, Apigee does not set the publishmessage.message.id variable, and accessing this variable will cause errors.

For more information about various types of flow variables, see Flow variables reference.

Error codes

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.

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