Política PublishMessage

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política PublishMessage permite-lhe publicar as informações do fluxo do proxy de API num tópico do Google Cloud Pub/Sub. O Pub/Sub da Google permite que os serviços comuniquem de forma assíncrona, com uma latência significativamente menor. Para mais informações sobre o Pub/Sub, consulte o artigo O que é o Pub/Sub?. As informações que quer publicar num tópico do Pub/Sub podem ser um texto literal ou uma variável de fluxo. Também pode especificar uma combinação de texto literal e variáveis de fluxo através de um modelo de mensagem.

Se o pedido de publicação for bem-sucedido, o Apigee define a variável de fluxo publishmessage.message.id com o valor devolvido pelo servidor do Pub/Sub. Para mais informações, consulte o artigo Variáveis de fluxo.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

Autenticação e implementação de proxy

Para executar a política PublishMessage, precisa de um token de autenticação. No entanto, não existe um elemento <Authentication> explícito na definição da política. Tem de implementar o proxy de API para usar a autenticação Google, que adiciona o token de autenticação ao pedido de forma oculta. Para obter informações sobre como implementar um proxy de API que usa a autenticação Google, consulte os passos de implementação. Além de usar a autenticação Google no proxy de API, tem de implementar o proxy de API com uma conta de serviço que tenha uma função com a autorização pubsub.topics.publish. Para mais informações sobre as funções de gestão de identidade e de acesso (IAM) para o Pub/Sub, consulte o artigo Autorizações e funções.

<PublishMessage>

Especifica a política PublishMessage.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo Tipo complexo
Elemento principal N/A
Elementos subordinados <Attributes>
<CloudPubSub>
<DisplayName>
<IgnoreUnresolvedVariables>
<Source>
<UseMessageAsSource>

A tabela seguinte apresenta uma descrição geral dos elementos subordinados de <PublishMessage>:

Elemento secundário Obrigatório? Descrição
<Attributes> Opcional Um conjunto de atributos a anexar à mensagem do Pub/Sub.
<CloudPubSub> Obrigatória Elemento principal de <Topic>. O elemento <Topic> especifica o tópico do Pub/Sub no qual quer publicar a sua mensagem.
<DisplayName> Opcional Um nome personalizado para a política.
<IgnoreUnresolvedVariables> Opcional Especifica se o processamento é interrompido se o Apigee encontrar uma variável não resolvida.
<Source> Opcional Especifica a mensagem a publicar no tópico Pub/Sub. Este elemento é opcional, mas tem de usar <Source> ou <UseMessageAsSource>.
<UseMessageAsSource> Opcional Especifica a mensagem a publicar no tópico Pub/Sub. Este elemento é opcional, mas tem de usar <Source> ou <UseMessageAsSource>.
Outros elementos secundários
<Topic> Obrigatória Um elemento secundário de <CloudPubSub>. Especifica o tópico do Pub/Sub no qual quer publicar a mensagem.

O elemento <PublishMessage> usa a seguinte sintaxe:

Sintaxe

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

Exemplo: origem

O exemplo seguinte mostra a definição da política <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>

Exemplo: UseMessageAsSource

Esta política de <PublishMessage> especifica o elemento 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>

Exemplo: atributos

Esta política de <PublishMessage> especifica o elemento 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>

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo Predefinição Obrigatório? Descrição
name N/A Obrigatório

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres.

Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.
continueOnError falso Opcional Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também:
enabled verdadeiro Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça anexada a um fluxo.
async   falso Descontinuado Este atributo foi descontinuado.

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <PublishMessage>.

<Attributes>

Especifica os atributos a anexar à mensagem do Pub/Sub.

Cada atributo é um par de chave-valor. O nome associado ao atributo deve ser exclusivo. O valor de cada um é determinado dinamicamente no tempo de execução através de um modelo de mensagem.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <PublishMessage>
Elementos subordinados Nenhum

O elemento <Attributes> usa a seguinte sintaxe:

Sintaxe

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

Exemplo 1

O exemplo seguinte define um único atributo com um valor fixo na mensagem à medida que é publicada:

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

Exemplo 2

O exemplo seguinte define vários atributos na mensagem à medida que é publicada. Os valores de alguns deles são determinados dinamicamente no tempo de execução:

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

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor predefinido N/A
Obrigatório? Opcional. Se omitir <DisplayName>, é usado o valor do atributo name da política.
Tipo String
Elemento principal <PolicyElement>
Elementos subordinados Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos nem elementos subordinados.

<Source>

Especifica a mensagem a publicar.

A mensagem pode ser um texto literal, uma variável de fluxo ou uma combinação de ambos sob a forma de um modelo de mensagem.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <PublishMessage>
Elementos subordinados Nenhum

O elemento <Source> usa a seguinte sintaxe:

Sintaxe

 <Source>SOURCE</Source>

Example-1

O exemplo seguinte define a mensagem de origem para o valor da flow-var-1 variável de fluxo:

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

Example-2

O exemplo seguinte usa um modelo de mensagem para publicar uma mensagem JSON com conteúdo dinâmico:

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

Elemento principal de <Topic>.

Só pode publicar num tópico do Pub/Sub. Por conseguinte, só pode ter um elemento <Topic> no elemento <CloudPubSub>.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo Tipo complexo
Elemento principal <PublishMessage>
Elementos subordinados <Topic>

O elemento <CloudPubSub> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo seguinte mostra a declaração do elemento <CloudPubSub>:

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

<Topic>

Especifica o tópico do Pub/Sub no qual quer publicar a mensagem <Source>.

Tem de especificar o nome do tópico no formato projects/project-id/topics/topic-name.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <CloudPubSub>
Elementos subordinados Nenhum

O elemento <Topic> usa a seguinte sintaxe:

Sintaxe
<Topic>TOPIC_NAME</Topic>
Exemplo

O exemplo seguinte especifica o tópico do Pub/Sub para publicação:

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

Neste exemplo, project-id-marketing é o ID do projeto do Google Cloud e topic-name-test1 é o tópico no qual a mensagem deve ser publicada.

<UseMessageAsSource>

Especifica a mensagem a publicar.

Use isto como alternativa ao elemento <Source>. O valor deve ser o nome de uma variável de fluxo que se refere a uma mensagem, como request, response ou message. Quando especifica este elemento, a política usa o conteúdo da mensagem como a mensagem a publicar. Deve usar este elemento em vez de <Source> quando o conteúdo da mensagem for um fluxo de octetos que não pode ser representado como uma string, por exemplo, conteúdo de um ficheiro binário.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <PublishMessage>
Elementos subordinados Nenhum

O elemento <UseMessageAsSource> usa a seguinte sintaxe:

Sintaxe

<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

O exemplo seguinte indica à política que use o conteúdo da mensagem de pedido como a carga útil da mensagem do 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>

Especifica se o processamento é interrompido se o Apigee encontrar uma variável não resolvida.

Valor predefinido Falso
Obrigatório? Opcional
Tipo Booleano
Elemento principal <PublishMessage>
Elementos subordinados Nenhum

Defina o valor como true para ignorar as variáveis não resolvidas e continuar o processamento; caso contrário, false. O valor predefinido é false.

Definir <IgnoreUnresolvedVariables> como true é diferente de definir o <PublishMessage> de continueOnError como true. Se definir continueOnError como true, o Apigee ignora todos os erros, não apenas os erros nas variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo seguinte define <IgnoreUnresolvedVariables> como true:

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Variáveis de fluxo

As variáveis de fluxo são objetos que contêm dados específicos e estão disponíveis no contexto de um fluxo de proxy de API. Estas variáveis armazenam informações como informações de carga útil, caminho do URL, endereços IP e dados da execução de políticas. Para mais informações sobre as variáveis de fluxo, consulte o artigo Usar variáveis de fluxo.

Se a política PublishMessage for publicada com êxito no tópico Pub/Sub, o Apigee define a variável de fluxo publishmessage.message.id como o messageId devolvido pelo servidor Pub/Sub. A variável de fluxo é do tipo string e está disponível para si a partir do fluxo de pedido de proxy. Com base no seu requisito, pode usar a variável de fluxo noutras políticas a jusante. No entanto, se a publicação falhar, o Apigee não define a variável publishmessage.message.id, e o acesso a esta variável vai causar erros.

Para mais informações sobre vários tipos de variáveis de fluxo, consulte a referência de variáveis de fluxo.

Códigos de erro

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