Política PublishMessage

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

Veja a documentação do Apigee Edge.

Vista geral

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

Nota:

• Pode publicar uma mensagem apenas num tópico através da política PublishMessage. Se quiser publicar uma mensagem em vários tópicos, use várias políticas PublishMessage (uma política para cada tópico).
• Para executar a política PublishMessage, deve ativar as APIs Pub/Sub para o seu projeto do Google Cloud. Para mais informações sobre a ativação de APIs para um projeto do Google Cloud, consulte o artigo Ativar e desativar serviços.

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 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: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual
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 deve usar 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 pedidos 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 os vários tipos de variáveis de fluxo, consulte a Referência de variáveis de fluxo.

Códigos de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha	Estado de HTTP	Causa
steps.publishmessage.PermissionDeniedError	500	Este erro ocorre quando a conta de serviço de tempo de execução não consegue roubar a identidade da conta de serviço proxy ou a conta de serviço proxy não tem autorização para publicar no tópico.
steps.publishmessage.ExecutionError	500	Este erro ocorre se tiver ocorrido um erro inesperado durante a publicação da mensagem no Pub/Sub. Pode ver os detalhes do erro na mensagem de erro.
steps.publishmessage.MessageVariableNotMessageType	500	Este erro ocorre se o nome da variável especificado em UseMessageAsSource não puder ser resolvido ou não for um tipo de mensagem.

Variáveis de falha

Sempre que existem erros de execução numa política, o Apigee gera mensagens de erro. Pode ver estas mensagens de erro na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do seu produto. Pode personalizar as mensagens de erro com base no tipo de erro para as tornar mais significativas.

Para personalizar as mensagens de erro, pode usar regras de falhas ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falhas e a política RaiseFault, consulte Regras de falhas vs. a política RaiseFault. Tem de verificar as condições através do elemento Condition nas regras de falhas e na política RaiseFault. O Apigee fornece variáveis de falhas exclusivas para cada política, e os valores das variáveis de falhas são definidos quando uma política aciona erros de tempo de execução. Ao usar estas variáveis, pode verificar condições de erro específicas e tomar as medidas adequadas. Para mais informações sobre a verificação das condições de erro, consulte o artigo Criar condições.

Variáveis	Onde	Exemplo
fault.name	O fault.name pode corresponder a qualquer uma das falhas indicadas na tabela Erros de tempo de execução. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed	POLICY_NAME é o nome especificado pelo utilizador da política que gerou a falha.	publishmessage.publish-message-1.failed = true

Para mais informações acerca dos erros de políticas, consulte o artigo O que precisa de saber acerca dos erros de políticas