Política PublishMessage

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ícone da política

Visão geral

A política PublishMessage permite publicar suas informações de fluxo de proxy de API em um tópico do Google Cloud Pub/Sub. O Pub/Sub do Google permite que os serviços se comuniquem de forma assíncrona, com uma latência significativamente menor. Para saber mais, consulte O que é o Pub/Sub? As informações que você quer publicar em um tópico do Pub/Sub podem ser um texto literal ou uma variável de fluxo. Também é possível especificar uma combinação de variáveis literais de texto e fluxo usando um modelo de mensagem.

Se a solicitação de publicação for bem-sucedida, a Apigee definirá a variável de fluxo publishmessage.message.id para o valor retornado pelo servidor do Pub/Sub. Para mais informações, consulte Variáveis de fluxo.

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

Autenticação e implantação de proxy

Para executar a política PublishMessage, você precisa de um token de autenticação. No entanto, não há um elemento <Authentication> explícito na definição da política. Você precisa implantar seu proxy de API para usar a autenticação do Google, que adiciona o token de autenticação à solicitação internamente. Para informações sobre como implantar um proxy de API que usa a autenticação do Google, consulte Etapas de implantação. Além de usar a autenticação do Google no proxy de API, é preciso implantar o proxy de API com uma conta de serviço que tenha um papel com a permissão pubsub.topics.publish. Para mais informações sobre os papéis de gerenciamento de identidade e acesso (IAM) para o Pub/Sub, consulte Permissões e papéis.

<PublishMessage>

Especifica a política PublishMessage.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo Tipo complexo
Elemento pai N/A
Elemento filho <CloudPubSub>
<DisplayName>
<Source>

A tabela a seguir fornece uma descrição de alto nível dos elementos-filhos de <PublishMessage>:

Elemento filho Obrigatório? Descrição
<CloudPubSub> Obrigatório Elemento-pai de <Topic>. O elemento <Topic> especifica o tópico do Pub/Sub em que você quer publicar a mensagem.
<DisplayName> Opcional Um nome personalizado para a política.
<IgnoreUnresolvedVariables> Opcional Especifica se o processamento será interrompido se a Apigee encontrar uma variável não resolvida.
<Source> Obrigatório Especifica a mensagem a ser publicada.
Outros elementos filhos
<Topic> Obrigatório Especifica o tópico do Pub/Sub em que você quer publicar a mensagem.

O elemento <PublishMessage> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir mostra a definição da 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 tem os seguintes atributos comuns a todas as políticas:

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

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

continueOnError falso Opcional Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também:
enabled true Opcional Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async   falso Obsoleto Esse atributo está obsoleto.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <PublishMessage>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

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

Valor padrão N/A
Obrigatório? Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo String
Elemento pai <PolicyElement>
Elemento filho 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 ou elementos filhos.

<Source>

Especifica a mensagem a ser publicada.

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

Valor padrão N/A
Obrigatório? Obrigatório
Tipo String
Elemento pai <PublishMessage>
Elemento filho Nenhum

O elemento <Source> usa a seguinte sintaxe:

Sintaxe

 <Source>SOURCE</Source>

Example-1

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

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

Example-2

O exemplo a seguir define a mensagem de origem como source-message-text-01:

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

<CloudPubSub>

Elemento-pai de <Topic>.

Só é possível publicar em um tópico do Pub/Sub. Portanto, só é possível ter um elemento <Topic> no elemento <CloudPubSub>.

Valor padrão N/A
Obrigatório? Obrigatório
Tipo Tipo complexo
Elemento pai <PublishMessage>
Elemento filho <Topic>

O elemento <CloudPubSub> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir mostra os atributos do elemento <CloudPubSub>:

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

<Topic>

Especifica o tópico do Pub/Sub em que você quer publicar a mensagem <Source>.

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

Valor padrão N/A
Obrigatório? Obrigatório
Tipo Tipo complexo
Elemento pai <CloudPubSub>
Elemento filho Nenhum

O elemento <Topic> usa a seguinte sintaxe:

Sintaxe
<Topic>TOPIC_NAME</Topic>
Exemplo

O exemplo a seguir especifica o tópico do Pub/Sub a ser publicado:

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

Neste exemplo, project-id-marketing é o ID do projeto no Google Cloud, e topic-name-test1 é o tópico em que a mensagem <Source> será publicada.

<IgnoreUnresolvedVariables>

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

Valor padrão Falso
Obrigatório? Opcional
Tipo Booleano
Elemento pai <PublishMessage>
Elemento filho Nenhum

Defina o valor como true para ignorar variáveis não resolvidas e continuar o processamento. Caso contrário, false. O valor padrão é false.

Definir <IgnoreUnresolvedVariables> como true é diferente de definir o continueOnError do <PublishMessage> como true. Se você definir continueOnError como true, a Apigee vai ignorar todos os erros, e não apenas os erros nas variáveis.

O elemento <IgnoreUnresolvedVariables> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

O exemplo a seguir 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 para você no contexto de um fluxo de proxy de API. Essas variáveis armazenam informações, como informações de payload, caminho do URL, endereços IP e dados da execução da política. Para mais informações sobre variáveis de fluxo, consulte Como usar variáveis de fluxo.

Se a política PublishMessage for publicada com sucesso no tópico Pub/Sub, a Apigee definirá a variável de fluxo publishmessage.message.id para o messageId retornado pelo servidor Pub/Sub. A variável de fluxo é do tipo string, e a variável está disponível para você a partir do fluxo de solicitação do proxy. Com base no seu requisito, é possível usar a variável de fluxo em outras políticas downstream. No entanto, se a publicação falhar, a Apigee não definirá a variável publishmessage.message.id, e o acesso a essa variável causará erros.

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

Códigos de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Código de falha Status HTTP Causa
steps.publishmessage.PermissionDeniedError 500 Esse erro ocorre quando a conta de serviço do ambiente de execução não pode personificar a conta de serviço proxy ou a conta de serviço proxy não tem permissão para publicar no tópico.
steps.publishmessage.ExecutionError 500 Esse erro ocorrerá se ocorrer um erro inesperado ao publicar a mensagem no Pub/Sub. Veja os detalhes do erro na mensagem de erro.

Variáveis de falha

Sempre que houver erros de execução em uma política, a Apigee gerará mensagens de erro. Essas mensagens de erro podem ser visualizadas na resposta de erro. Muitas vezes, as mensagens de erro geradas pelo sistema podem não ser relevantes no contexto do produto. Personalize as mensagens de erro com base no tipo específico para torná-las mais úteis.

Para personalizar as mensagens de erro, use regras de falha ou a política RaiseFault. Para informações sobre as diferenças entre as regras de falha e a política RaiseFault, consulte FaultRules vs. a política RaiseFault. Verifique as condições usando o elemento Condition nas regras de falha e na política RaiseFault. A Apigee fornece variáveis de falha exclusivas para cada política, e os valores das variáveis de falha são definidos quando uma política aciona erros de ambiente de execução. Ao usar essas variáveis, é possível verificar se há condições de erro específicas e agir conforme adequado. Para mais informações sobre como verificar condições de erro, consulte Como criar condições.

Variáveis Onde Exemplo
fault.name O fault.name pode corresponder a qualquer uma das falhas listadas na tabela Erros de ambiente 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 da política especificada pelo usuário que gerou a falha. publishmessage.publish-message-1.failed = true
Para mais informações sobre erros de política, consulte O que você precisa saber sobre erros de política