Política PublishMessage

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

La política PublishMessage está disponible en Apigee y en la versión 1.7 y posteriores de Apigee Hybrid.

Descripción general

La política PublishMessage te permite publicar la información de flujo del proxy de API en un tema de Google Cloud Pub/Sub. Pub/Sub de Google permite que los servicios se comuniquen de forma asíncrona con una latencia considerablemente menor. Para obtener más información sobre Pub/Sub, consulta ¿Qué es Pub/Sub?. La información que deseas publicar en un tema de Pub/Sub puede ser un texto literal o una variable de flujo. También puedes especificar una combinación de texto literal y variables de flujo mediante una plantilla de mensajes.

Si la solicitud de publicación se realiza correctamente, Apigee configura la variable de flujo publishmessage.message.id en el valor que muestra el servidor de Pub/Sub. Para obtener más información, consulta Variables de flujo.

Esta es una política estándar y se puede implementar en cualquier tipo de entorno. No todos los usuarios necesitan conocer los tipos de políticas y el entorno. Para obtener información sobre los tipos de políticas y la disponibilidad con cada tipo de entorno, consulta Tipos de políticas.

Nota:

• Puedes publicar un mensaje en un solo tema con la política PublishMessage. Si deseas publicar un mensaje en varios temas, usa varias políticas PublishMessage (una política para cada tema).
• Para ejecutar la política PublishMessage, debes habilitar las APIs de Pub/Sub en el proyecto de Google Cloud. A fin de obtener más información sobre cómo habilitar las APIs para un proyecto de Google Cloud, consulta Habilita o inhabilita servicios.

Implementación del proxy y autenticación

Para ejecutar la política PublishMessage, necesitas un token de autenticación. Sin embargo, no hay un elemento <Authentication> explícito en la definición de la política. Debes implementar el proxy de API para usar la autenticación de Google, que agrega el token de autenticación a la solicitud de forma interna. Para obtener información sobre cómo implementar un proxy de API que use la autenticación de Google, consulta Pasos para la implementación. Además de usar la autenticación de Google en tu proxy de API, debes implementar tu proxy de API con una cuenta de servicio que tenga una función con el permiso pubsub.topics.publish. Para obtener más información sobre las funciones de Identity and Access Management (IAM) para Pub/Sub, consulta Permisos y funciones.

<PublishMessage>

Especifica la política PublishMessage.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	N/A
Elementos secundarios	<CloudPubSub> <DisplayName> <Source>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <PublishMessage>.

Elemento secundario	¿Es obligatorio?	Descripción
<CloudPubSub>	Obligatorio	Elemento principal de <Topic>. El elemento <Topic> especifica el tema de Pub/Sub en el que deseas publicar tu mensaje.
<DisplayName>	Opcional	Un nombre personalizado para la política
<IgnoreUnresolvedVariables>	Opcional	Especifica si el procesamiento se detiene en caso de que Apigee encuentre una variable sin resolver.
<Source>	Obligatorio	Especifica el mensaje que se publicará.
Otros elementos secundarios
<Topic>	Obligatorio	Especifica el tema de Pub/Sub en el que deseas publicar el mensaje.

El elemento <PublishMessage> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo, se muestra la definición de la política <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>

Este elemento tiene los siguientes atributos que son comunes a todas las políticas:

Atributo	Predeterminada	(obligatorio)	Descripción
name	N/A	Obligatorio	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.
continueOnError	falso	Opcional	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual
enabled	true	Opcional	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará, incluso si permanece conectada a un flujo.
async	falso	Obsoleta	Este atributo dejó de estar disponible.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <PublishMessage>.

<DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omites <DisplayName>, se usa el valor del atributo name de la política.
Tipo	String
Elemento principal	<PolicyElement>
Elementos secundarios	Ninguna

El elemento <DisplayName> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

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

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<Source>

Especifica el mensaje que se publicará.

El mensaje puede ser un texto literal, una variable de flujo o una combinación de ambos en forma de una plantilla de mensajes.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	<PublishMessage>
Elementos secundarios	Ninguna

El elemento <Source> usa la siguiente sintaxis:

Sintaxis

 <Source>SOURCE</Source>

Ejemplo-1

En el siguiente ejemplo, se configura el mensaje fuente en el valor de la variable de flujo flow-var-1:

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

Ejemplo-2

En el siguiente ejemplo, se establece el mensaje fuente en source-message-text-01:

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

<CloudPubSub>

Elemento principal de <Topic>.

Puedes publicar en un solo tema de Pub/Sub. Por lo tanto, solo puedes tener un elemento <Topic> en el elemento <CloudPubSub>.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	<PublishMessage>
Elementos secundarios	<Topic>

El elemento <CloudPubSub> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo, se muestran la declaración del elemento <CloudPubSub>:

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

<Topic>

Especifica el tema de Pub/Sub en el que deseas publicar el mensaje <Source>.

Debes especificar el nombre del tema en el formato projects/project-id/topics/topic-name.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	Tipo complejo
Elemento principal	<CloudPubSub>
Elementos secundarios	Ninguna

El elemento <Topic> usa la siguiente sintaxis:

Sintaxis

<Topic>TOPIC_NAME</Topic>

Ejemplo

En el siguiente ejemplo, se especifica el tema de Pub/Sub en el que se publicará lo siguiente:

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

En este ejemplo, project-id-marketing es tu ID del proyecto de Google Cloud y topic-name-test1 es el tema en el que se debe publicar el mensaje <Source>.

<IgnoreUnresolvedVariables>

Especifica si el procesamiento se detiene en caso de que Apigee encuentre una variable sin resolver.

Valor predeterminado	Falso
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	<PublishMessage>
Elementos secundarios	Ninguna

Configura el valor en true para ignorar las variables sin resolver y continuar con el procesamiento; de lo contrario, false. El valor predeterminado es false.

Configurar <IgnoreUnresolvedVariables> como true es diferente a configurar continueOnError como <PublishMessage> en true. Si configuras continueOnError como true, Apigee ignora todos los errores, no solo los errores de las variables.

El elemento <IgnoreUnresolvedVariables> usa la siguiente sintaxis:

Sintaxis

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

Ejemplo

En el siguiente ejemplo, se configura <IgnoreUnresolvedVariables> como true:

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Variables de flujo

Las variables de flujo son objetos que contienen datos específicos y están disponibles en el contexto de un flujo del proxy de API. Estas variables almacenan información como la información de la carga útil, la ruta de URL, las direcciones IP y los datos de la ejecución de la política. Para obtener más información sobre las variables de flujo, consulta Usa variables de flujo.

Si la política PublishMessage publica con éxito en el tema Pub/Sub, Apigee establece la variable de flujo publishmessage.message.id en el campo messageId que muestra el servidor de Pub/Sub. La variable de flujo es de tipo de string y está disponible para ti a partir del flujo de solicitud de proxy en adelante. Según tus requisitos, puedes usar la variable de flujo en otras políticas descendentes. Sin embargo, si la publicación falla, Apigee no establece la variable publishmessage.message.id y el acceso a esta variable causará errores.

Para obtener más información sobre varios tipos de variables de flujo, consulta Referencia de las variables de flujo.

Códigos de error

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