Este documento descreve como configurar a exportação automática de Mensagens do Pub/Sub Lite para o Pub/Sub.
Confira alguns cenários em que esse recurso pode ser usado:
- Interoperabilidade entre cargas de trabalho que usam uma combinação de Pub/Sub Lite e o Pub/Sub.
- Migre uma carga de trabalho do Pub/Sub Lite para o Pub/Sub.
- Use recursos avançados do Pub/Sub, como assinaturas de push e de um aplicativo atual baseado em Pub/Sub Lite
- Consolide vários pipelines de dados.
Visão geral
Para exportar mensagens do Pub/Sub Lite para o Pub/Sub, faça o seguinte: crie um tipo especial chamado assinatura de exportação. Um de exportação recebe mensagens de um tópico do Lite, as converte em de mensagens do Pub/Sub e envia as mensagens convertidas tópico do Pub/Sub de destino.
Um tópico do Lite pode ter uma combinação de assinaturas de exportação e assinaturas assinaturas. Os dois tipos de assinatura são idênticos em termos de uso da cota e capacidade de processamento de reserva. Uma assinatura de exportação consome a capacidade de processamento da assinatura Lite e é cobrado Capacidade de publicação do Pub/Sub.
Uma assinatura de exportação conecta um tópico do Lite a exatamente um tópico do Pub/Sub. No entanto, um tópico do Lite pode ter várias exportações assinaturas que se conectam a diferentes tópicos do Pub/Sub (arquitetura de fan-out). Você também pode exportar de vários tópicos do Lite para o mesmo tópico do Pub/Sub (arquitetura fan-in).
Autenticação
Uma assinatura de exportação acessa o Pub/Sub Lite e recursos do Pub/Sub. Para criar uma assinatura de exportação, você precisa do as seguintes permissões:
pubsublite.subscriptions.create
: Os papéis predefinidos a seguir contêm essa permissão:roles/pubsublite.admin
roles/pubsublite.editor
Consulte Controle de acesso para o Pub/Sub Lite.
pubsub.topics.get
: Os papéis predefinidos a seguir contêm essa permissão:roles/pubsub.admin
roles/pubsub.editor
roles/pubsub.viewer
Consulte Controle de acesso para Pub/Sub.
Agentes de serviço
Uma assinatura de exportação publica em um tópico do Pub/Sub no em nome da empresa. Para fazer isso, ele usa uma agente de serviço.
Depois de criar a primeira assinatura de exportação em um projeto, um
O agente de serviço do Pub/Sub Lite é criado automaticamente. Se você
criar assinaturas de exportação adicionais no mesmo projeto, elas usam a mesma
agente de serviço. O agente de serviço tem o seguinte esquema de nomenclatura:
service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com
:
O agente de serviço é criado com permissões para publicar para todos
tópicos do Pub/Sub e do Pub/Sub Lite no mesmo
como a assinatura de exportação. Se o Pub/Sub de destino
está em um projeto diferente da assinatura de exportação, será necessário conceder o
permissões adicionais do agente de serviço adicionando o papel Publicador do Pub/Sub.
(roles/pubsub.publisher
). É possível conceder permissões para um projeto inteiro ou
um tópico individual. Recomendamos conceder permissões no nível do tópico,
seguindo o princípio de privilégio mínimo.
Para mais informações, consulte
Como controlar o acesso usando o console do Google Cloud.
Você também pode usar o
gcloud projects add-iam-policy-binding
para adicionar papéis do IAM:
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com --role=roles/pubsub.publisher
Substitua:
- TOPIC_NAME: o nome do Pub/Sub de destino para adicionar a vinculação de política do IAM.
- PROJECT_NUMBER: o número do projeto do Projeto da assinatura de exportação do Pub/Sub Lite.
Criar uma assinatura de exportação
É possível criar uma assinatura de exportação do Lite com o console do Google Cloud, a Google Cloud CLI ou API Pub/Sub Lite.
Uma assinatura de exportação do Lite precisa estar no mesmo projeto e local que a do Lite ao qual estão anexados. Para criar o tópico do Lite, consulte Crie e gerencie tópicos do Lite.
Se você anexar uma assinatura de exportação a um tópico do Lite, verifique se todas as as mensagens publicadas no tópico do Lite são compatíveis com o Pub/Sub. Para mais informações, consulte Compatibilidade de mensagens.
Depois de criá-la, não é possível alterar uma assinatura de exportação para um assinatura padrão ou vice-versa.
Console
Acesse a página Assinaturas do Lite.
Clique em Criar assinatura do Lite.
Insira o ID da assinatura do Lite.
Selecione um tópico do Lite para receber mensagens.
Selecione Entregar mensagens imediatamente ou Entregar mensagens após armazenados.
Escolha um tipo de Deslocamento inicial.
Selecione Exportar para o tópico do Pub/Sub.
Na lista Tópico de destino, escolha um tópico do Pub/Sub para receber as mensagens exportadas do Lite.
Opcional. Especifique um tópico de mensagens inativas.
- Marque a caixa de seleção Ativar mensagens mortas.
- Selecione um tópico do Lite para usar como tópico de mensagens inativas ou clique em Criar Tópico do Lite para criar um novo tópico de mensagens inativas. Tópico de mensagens inativas precisa estar no mesmo local (zona ou região) e projeto que a exportação assinatura.
Clique em Criar.
gcloud
Para criar uma assinatura de exportação, use o
gcloud pubsub lite-subscriptions create
comando:
gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \ --location=LOCATION \ --topic=TOPIC_ID \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura do Lite que será criada.
- LOCATION: o local do Lite assinatura.
- TOPIC_ID: o ID do tópico do Lite a ser anexado ao Lite assinatura.
- PUBSUB_TOPIC_NAME: o nome do tópico do Pub/Sub a ser
exportar. Especifique o nome completo se o tópico estiver em um projeto diferente:
projects/my-project-id/topics/my-topic-id
. - DEAD_LETTER_TOPIC_ID: opcional. O ID de um tópico do Lite para usar como o tópico de mensagens inativas. O tópico de mensagens inativas precisa estar no mesmo local (zona ou região) e projeto da assinatura de exportação.
- DESIRED_STATE: opcional. O estado inicial da assinatura.
Os seguintes valores são aceitos:
active
: a assinatura exporta mensagens do Lite para Pub/Sub (padrão).paused
: a exportação de mensagens do Lite está suspensa.
Se a solicitação for bem-sucedida, a linha de comando exibirá uma confirmação:
Created [SUBSCRIPTION_ID].
Protocolo
Para criar uma assinatura de exportação do Lite, envie uma solicitação POST
como a
seguintes:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Substitua:
- REGION: a região em que a assinatura do Lite será armazenada.
- PROJECT_NUMBER: o número do projeto em que o Entrada do Lite.
- LOCATION: o nome de um local em que o Pub/Sub Lite suporta.
- SUBSCRIPTION_ID: o ID da assinatura do Lite.
Especifique os campos a seguir no corpo da solicitação:
{ "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
Substitua:
- DELIVERY_REQUIREMENT: o requisito de envio.
DELIVER_AFTER_STORED
ouDELIVER_IMMEDIATELY
. - DESIRED_STATE: o estado inicial da assinatura. O
valores a seguir são suportados:
ACTIVE
: a assinatura exporta mensagens do Lite para Pub/SubPAUSED
: a exportação de mensagens do Lite está suspensa.
- DEAD_LETTER_TOPIC_ID: o ID de um tópico existente do Lite a ser usado como um tópico de mensagens inativas. O tópico deve estar no mesmo local (zona ou região) e projeto como a própria assinatura de exportação.
- PUBSUB_TOPIC_NAME: o nome do tópico do Pub/Sub a ser
exportar. Exemplo de formato:
projects/my-project-id/topics/my-topic-id
.
Se a solicitação for bem-sucedida, a resposta será a assinatura do Lite no formato JSON:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Python
Antes de executar este exemplo, siga as instruções de configuração do Java nas bibliotecas de cliente do Pub/Sub Lite.
Atualizar uma assinatura de exportação
É possível atualizar as assinaturas do Lite com o console do Google Cloud, a Google Cloud CLI ou API Pub/Sub Lite. Pode levar até 30 em segundos para que as novas configurações sejam aplicadas.
Console
Acesse a página Assinaturas do Lite.
Clique no ID da assinatura do Lite.
Na página Detalhes da assinatura do Lite, clique em Editar.
gCloud
Para atualizar uma assinatura do Lite, use o
comando
gcloud pubsub lite-subscriptions update
:
gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \ --location=LOCATION \ --delivery-requirement=DELIVERY_REQUIREMENT \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
Substitua:
- SUBSCRIPTION_ID: o ID da assinatura do Lite
- LOCATION: o local do Lite assinatura.
- DELIVERY_REQUIREMENT: opcional. O requisito de entrega,
deliver-after-stored
oudeliver-immediately
. - PUBSUB_TOPIC_NAME: opcional. O nome
Tópico do Pub/Sub para onde exportar. Especifique o nome completo se o tópico estiver em um projeto diferente:
projects/my-project-id/topics/my-topic-id
: - DEAD_LETTER_TOPIC_ID: o ID de um tópico existente do Lite a ser usado como um tópico de mensagens inativas. O tópico deve estar no mesmo local (zona ou região) e projeto como a própria assinatura de exportação.
- DESIRED_STATE: opcional. O estado desejado da assinatura.
Os seguintes valores são aceitos:
active
: a assinatura exporta mensagens do Lite para Pub/Sub (padrão).paused
: a exportação de mensagens do Lite está suspensa.
Se a solicitação for bem-sucedida, a linha de comando exibirá a assinatura do Lite:
Updated subscription [SUBSCRIPTION_ID]. deliveryConfig: deliveryRequirement: DELIVERY_REQUIREMENT exportConfig: currentState: DESIRED_STATE deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID desiredState: DESIRED_STATE pubsubConfig: topic: PUBSUB_TOPIC_NAME name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID
Protocolo
Para atualizar uma assinatura Lite, envie uma solicitação PATCH
como esta:
PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig Authorization: Bearer $(gcloud auth print-access-token)
Substitua:
- REGION: a região em que a assinatura do Lite foi criada.
- PROJECT_NUMBER: o número do projeto em que o Lite assinatura criada.
- LOCATION: o local em que a assinatura do Lite foi criada.
- SUBSCRIPTION_ID: o ID da assinatura do Lite.
Especifique os campos a seguir no corpo da solicitação:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
Substitua:
- DELIVERY_REQUIREMENT: o requisito de envio.
DELIVER_AFTER_STORED
ouDELIVER_IMMEDIATELY
. - DESIRED_STATE: o estado desejado para a assinatura. O
valores a seguir são suportados:
ACTIVE
: a assinatura exporta mensagens do Lite para Pub/SubPAUSED
: a exportação de mensagens do Lite está suspensa.
- DEAD_LETTER_TOPIC_ID: o ID de um tópico existente do Lite a ser usado como um tópico de mensagens inativas. O tópico deve estar no mesmo local (zona ou região) e projeto como a própria assinatura de exportação.
- PUBSUB_TOPIC_NAME: o nome do destino.
tópico do Pub/Sub. Exemplo de formato:
projects/my-project-id/topics/my-topic-id
:
Se a solicitação for bem-sucedida, a resposta será a assinatura do Lite no formato JSON:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
Pausar ou iniciar uma assinatura de exportação
As inscrições na exportação têm uma configuração chamada estado desejado, que tem uma das dois valores:
- Ativa: a assinatura exporta mensagens do Lite para o Pub/Sub.
- Pausada: a exportação de mensagens do Lite está suspensa.
Para alterar o estado pretendido no console do Google Cloud:
Acesse a página Assinaturas do Lite.
Clique no ID da assinatura do Lite.
Na página Detalhes da assinatura do Lite, clique em Pausar ou Iniciar.
Também é possível atualizar o estado desejado usando a Google Cloud CLI ou a API Pub/Sub Lite. Consulte Atualizar uma assinatura de exportação.
Práticas recomendadas
Esta seção descreve algumas práticas recomendadas ao usar assinaturas de exportação.
Reservas
Recomendamos usar uma assinatura de exportação com um reservation, em vez de definir explicitamente a capacidade de processamento da assinatura.
Compatibilidade de mensagens
Se uma mensagem do Pub/Sub Lite não for compatível Pub/Sub, a assinatura de exportação não publica a mensagem para Pub/Sub Em vez disso, ele coloca a mensagem no tópico de mensagens inativas, caso um tenha sido atribuído. Se nenhum tópico de mensagens inativas foi atribuído, incompatível as mensagens são simplesmente descartadas.
Ao publicar mensagens no tópico do Lite, observe o seguinte problemas de compatibilidade:
Chaves. As chaves do Pub/Sub Lite têm tipo
bytes
, enquanto As chaves de ordem do Pub/Sub são do tipostring
. Para ser compatível, o A chave do Pub/Sub Lite só pode ter caracteres UTF-8.Atributos. Os atributos de mensagem têm os seguintes requisitos:
- Para ser compatível, todos os atributos de mensagem do Pub/Sub Lite precisa ter um único valor. O Pub/Sub Lite aceita mensagens atributos com vários valores, mas o Pub/Sub só aceita atributos de valor único.
- Os atributos de mensagem não podem exceder o Limites de mensagens do Pub/Sub incluindo o máximo de atributos por mensagem e o tamanho máximo de chaves e valores .
Tópico de mensagens inativas
Para reter e processar mensagens incompatíveis, recomendamos usar mensagens inativas tópico. Você pode atribuir um tópico de mensagens inativas ao criar a exportação ou atualize uma existente para usar uma tópico de mensagens inativas. Se a assinatura receber uma mensagem incompatível com o Pub/Sub, ele publica a mensagem no tópico de mensagens inativas.
Um tópico de mensagens inativas é um tópico normal do Pub/Sub Lite. Ele deve estar no está no mesmo local e projeto que a inscrição de exportação e deve ser um um tópico diferente do tópico de origem.
Normalmente, um tópico de mensagens inativas tem baixa utilização da capacidade de processamento. Portanto, atribuir uma reserva ao tópico de mensagens inativas, em vez de alocar a capacidade de processamento para o tópico.
Erros de entrega
Uma assinatura de exportação tenta entregar todas as mensagens compatíveis para o
tópico do Pub/Sub de destino. Se a entrega da mensagem falhar, a exportação
a assinatura foi suspensa. Para encontrar a categoria do erro, verifique
subscription/export_status
. Os valores a seguir indicam um erro:
PERMISSION_DENIED
: permissões insuficientes para exportar mensagens.NOT_FOUND
: um ou mais recursos não foram encontrados. por exemplo, o destino tópico não existe.
Para mais informações sobre solução de problemas, consulte Resolver problemas com a exportação de assinaturas
Depois que você resolver o erro, a assinatura de exportação será reiniciada automaticamente. devido a novas tentativas periódicas.
Preços
O Pub/Sub Lite e o Pub/Sub são cobrados que a assinatura de exportação consome. Especificamente, você vai receber cobranças para a capacidade e o armazenamento da assinatura alocada assinatura do Pub/Sub Lite, que é configurada para o Tópico do Pub/Sub Lite. Você também é cobrado pela publicação tópico do Pub/Sub de destino. Consulte Preços do Pub/Sub.
Não há custos adicionais pelo uso do recurso de exportação nem diferença de preço entre as assinaturas de exportação do Pub/Sub Lite e assinaturas padrão.
Resolver problemas de exportação de assinaturas
Esta seção descreve algumas dicas de solução de problemas para assinaturas de exportação.
A assinatura de exportação está pausada
Se a assinatura for pausada, nenhuma mensagem será exportada.
Para detectar esse problema:
Console do Google Cloud: confira detalhes da assinatura. Se a assinatura estiver pausado, o Estado desejado e o Estado atual serão
Paused
.Métricas: a métrica
subscription/export_status
éPAUSED
.
Para resolver esse problema, inicie a assinatura.
O tópico de destino ou tópico de mensagens inativas foi excluído
Se você excluir o tópico do Pub/Sub anexado a uma exportação ou excluir o tópico de mensagens inativas, ocorrerá um erro.
Para detectar esse problema:
Console do Google Cloud: confira detalhes da assinatura. Se o tema for excluído, o Estado atual será
Not found
.Métricas: a métrica
subscription/export_status
. Se o tema for excluído, o valor seráNOT_FOUND
.
Para resolver esse problema, verifique o tópico de destino do Pub/Sub e o tópico de mensagens inativas (se houver um configurado).
Se o Pub/Sub de destino tiver sido excluído, recrie o tópico com com o mesmo nome. A assinatura de exportação retoma a publicação, supondo que as permissões não mudaram.
Se o tópico de mensagens inativas foi excluído, crie um novo tópico de mensagens inativas e atualize a assinatura de exportação para referenciá-lo.
Mensagens incompatíveis
Se as mensagens forem incompatíveis com o Pub/Sub, elas não serão exportadas.
Para detectar esse problema:
- Métricas: a métrica
subscription/unexportable_message_count
mostra a contagem de mensagens incompatíveis que não foram exportadas.
Para resolver esse problema, use um tópico de mensagens inativas para reter as mensagens incompatíveis. Examine as mensagens para determinar a causa e, em seguida, e republicá-los, se necessário. Consulte Compatibilidade de mensagens.
A exportação está limitada
Para detectar esse problema:
- Métricas: a métrica
subscription/flow_control_status
mostra um controle de fluxoNO_CLIENT_TOKENS
, o que indica que o limite por partição do bytes ou mensagens pendentes tenham sido atingidos. Até que o problema seja resolvido, o backlog aumentará para assinaturas de exportação associadas.
Esse erro tem várias causas possíveis. A maioria das causas possíveis ocorre no back-end, mas verifique o seguinte:
- Publique as mensagens do Lite compartilhando a mesma chave a uma taxa menor que 1 MiB/s por chave. A assinatura de exportação grava as chaves de mensagem do Lite como Chaves de ordem do Pub/Sub, e o Pub/Sub tem 1 MiB/s limit em cada chave de ordem. Exceder essa pode causar limitação.
Usuário não autorizado a realizar esta ação
O agente de serviço do Pub/Sub Lite precisa ter permissões para publicar no tópico do Pub/Sub de destino.
Para detectar esse problema:
Console do Google Cloud: confira detalhes da assinatura. Se houver erros de permissão, o Estado atual será
Permission denied
.Métricas: a métrica
subscription/export_status
éPERMISSON_DENIED
.
Por exemplo, as situações a seguir podem causar esse erro:
- O agente de serviço do Pub/Sub Lite não tem a permissão correta para publicar mensagens no tópico do Pub/Sub de destino em um projeto diferente.
- O agente de serviço foi removido da política do IAM da exportação projeto pai da assinatura.
- O agente de serviço do Pub/Sub Lite ainda está sendo configurado. Um serviço o agente é criado automaticamente quando você cria a primeira assinatura de exportação em um projeto. O erro de permissão deve ser resolvido automaticamente em até 10 minutos.
Para resolver o problema, verifique se o agente de serviço recebeu a permissão correta uma permissão ou um papel. Consulte Agentes de serviço.
A seguir
Escolha entre o Pub/Sub ou o Pub/Sub Lite.