Neste documento, descrevemos como criar uma assinatura do Cloud Storage. É possível usar o console do Google Cloud, a Google Cloud CLI, a biblioteca de cliente ou a API Pub/Sub para criar uma assinatura do Cloud Storage.
Antes de começar
Antes de ler este documento, você precisa conhecer bem:
- Como funciona uma assinatura do Cloud Storage.
- Como o Cloud Storage funciona e como criar e gerenciar buckets do Cloud Storage.
- Como configurar um tópico de mensagens inativas para lidar com falhas de mensagens.
Papéis e permissões necessárias
Confira a seguir uma lista de diretrizes relacionadas a papéis e permissões:
Para criar uma assinatura, configure o controle de acesso no nível do projeto.
Você também vai precisar de permissões no nível do recurso se suas assinaturas e tópicos estiverem em projetos diferentes, conforme discutido mais adiante nesta seção.
Para criar uma assinatura do Cloud Storage, a conta de serviço do Pub/Sub precisa ter permissão para gravar no bucket específico do Cloud Storage e ler os metadados dele. Para mais informações sobre como conceder essas permissões, consulte a próxima seção deste documento.
Para receber as permissões necessárias para criar assinaturas do Cloud Storage,
peça ao administrador para conceder a você o papel do IAM
Editor do Pub/Sub (roles/pubsub.editor
) no projeto.
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Esse papel predefinido contém as permissões necessárias para criar assinaturas do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
As seguintes permissões são necessárias para criar assinaturas do Cloud Storage:
-
Crie uma assinatura:
pubsub.subscriptions.create
-
Anexar uma assinatura a um tópico:
pubsub.topics.attachSubscription
-
Extrair de uma assinatura:
pubsub.subscriptions.consume
-
Conseguir uma assinatura:
pubsub.subscriptions.get
-
Listar uma assinatura:
pubsub.subscriptions.list
-
Atualizar uma assinatura:
pubsub.subscriptions.update
-
Excluir uma assinatura:
pubsub.subscriptions.delete
-
Consiga a política do IAM para uma assinatura:
pubsub.subscriptions.getIamPolicy
-
Configure a política do IAM para uma assinatura:
pubsub.subscriptions.setIamPolicy
Também é possível receber essas permissões com papéis personalizados ou outros papéis predefinidos.
Se você precisar criar assinaturas do Cloud Storage em um projeto que estejam associadas a um tópico em outro projeto, peça ao administrador do tópico para conceder a você o papel do IAM (roles/pubsub.editor)
de editor do Pub/Sub no tópico.
Atribuir papéis do Cloud Storage à conta de serviço do Pub/Sub
Alguns serviços do Google Cloud têm contas de serviço gerenciado pelo Google Cloud que
permitem que os serviços acessem seus recursos. Essas contas são conhecidas
como agentes de serviço. O Pub/Sub cria e mantém uma conta de
serviço para cada projeto no formato
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
.
Para criar uma assinatura do Cloud Storage, a conta de serviço do Pub/Sub precisa ter permissão para gravar no bucket específico do Cloud Storage e ler os metadados do bucket. Escolha um dos seguintes procedimentos:
Conceda permissões no nível do bucket. No bucket específico do Cloud Storage, conceda os papéis Criador de objetos do Storage (
roles/storage.objectCreator
) e Leitor de bucket legado do Storage (roles/storage.legacyBucketReader
) à conta de serviço do Pub/Sub.Se for necessário conceder papéis no nível do projeto, é possível conceder o papel Administrador do Storage (
roles/storage.admin
) no projeto que contém o bucket do Cloud Storage. Conceda esse papel à conta de serviço do Pub/Sub.
Permissões de bucket
Execute as etapas a seguir para conceder os papéis Criador de objetos do Storage (roles/storage.objectCreator
) e Leitor de bucket legado do Storage (roles/storage.legacyBucketReader
) no nível do bucket:
No Console do Google Cloud, acesse a página Cloud Storage.
Clique no bucket do Cloud Storage em que você quer gravar mensagens.
A página Detalhes do bucket é aberta.
Na página Detalhes do bucket, clique na guia Permissões.
Na guia Permissões > Visualizar por principais, clique em Conceder acesso.
A página Conceder acesso será aberta.
Na seção Adicionar principais, insira o nome da sua conta de serviço do Pub/Sub.
O formato da conta de serviço é
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Por exemplo, para um projeto com PROJECT_NUMBER=112233445566
, a conta de serviço tem o formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.No menu suspenso Atribuir papéis > Selecionar um papel, insira
Creator
e selecione o papel Criador de objetos do Storage.Clique em Adicionar outro papel.
No menu suspenso Selecionar um papel, insira
Bucket Reader
e selecione o papel Leitor de bucket legado do Storage.Clique em Salvar.
Permissões do projeto
Execute as etapas a seguir para conceder o papel Administrador do Storage (roles/storage.admin
) no nível do projeto:
No console do Google Cloud, abra a página IAM.
Na guia Permissões > Visualizar por principais, clique em Conceder acesso.
A página Conceder acesso será aberta.
Na seção Adicionar principais, insira o nome da sua conta de serviço do Pub/Sub.
O formato da conta de serviço é
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Por exemplo, para um projeto com PROJECT_NUMBER=112233445566
, a conta de serviço tem o formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.No menu suspenso Atribuir papéis > Selecionar um papel, insira
Storage Admin
e selecione o papel Administrador do Storage.Clique em Salvar.
Para mais informações sobre o IAM do Cloud Storage, consulte Identity and Access Management do Cloud Storage.
Propriedades da assinatura do Cloud Storage
Ao configurar uma assinatura do Cloud Storage, é necessário especificar as propriedades comuns a todos os tipos de assinatura e algumas outras propriedades específicas da assinatura.
Propriedades comuns de assinaturas
Saiba mais sobre as propriedades comuns de assinatura que podem ser definidas em todas as assinaturas.
Nome do bucket
Um bucket do Cloud Storage precisa existir antes da criação de uma assinatura do Cloud Storage.
As mensagens são enviadas como lotes e armazenadas no bucket do Cloud Storage. Um único lote ou arquivo é armazenado como um objeto no bucket.
O bucket do Cloud Storage precisa ter a opção Pagamentos do solicitante desativada.
Para criar um bucket do Cloud Storage, consulte Criar buckets.
Prefixo, sufixo e data/hora do nome de arquivo
Os arquivos de saída do Cloud Storage gerados pela assinatura do Cloud Storage são armazenados como objetos no bucket do Cloud Storage. O nome
do objeto armazenado no bucket do Cloud Storage tem o seguinte
formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>
.
A lista a seguir inclui detalhes do formato do arquivo e os campos que podem ser personalizados:
<file-prefix>
é o prefixo de nome de arquivo personalizado. Esse campo é opcional.<UTC-date-time>
é uma string personalizável gerada automaticamente com base no horário de criação do objeto.<uuid>
é uma string aleatória gerada automaticamente para o objeto.<file-suffix>
é o sufixo do nome de arquivo personalizado. Esse campo é opcional. O sufixo do nome do arquivo não pode terminar em "/".É possível alterar o prefixo e o sufixo do nome de arquivo:
Por exemplo, se o valor do prefixo do nome de arquivo for
prod_
e o sufixo do nome do arquivo for_archive
, um nome de objeto de amostra seráprod_2023-09-25T04:10:00+00:00_uN1QuE_archive
.Se você não especificar o prefixo e o sufixo do nome de arquivo, o nome do objeto armazenado no bucket do Cloud Storage terá o formato:
<UTC-date-time>_<uuid>
.Os requisitos de nomenclatura de objetos do Cloud Storage também se aplicam ao prefixo e ao sufixo do nome do arquivo. Para mais informações, consulte Sobre os objetos do Cloud Storage.
Você pode alterar como a data e a hora são exibidas no nome do arquivo:
Correspondências de data e hora obrigatórias que podem ser usadas apenas uma vez: ano (
YYYY
ouYY
), mês (MM
), dia (DD
), hora (hh
), minuto (mm
), segundo (ss
). Por exemplo,YY-YYYY
ouMMM
é inválido.Correspondências opcionais que podem ser usadas apenas uma vez: separador de data e hora (
T
) e compensação de fuso horário (Z
ou+00:00
).Elementos opcionais que podem ser usados várias vezes: hífen (
-
), sublinhado (_
), dois-pontos (:
) e barra (/
).Por exemplo, se o valor do formato de data e hora do nome do arquivo for
YYYY-MM-DD/hh_mm_ssZ
, um nome de objeto de amostra seráprod_2023-09-25/04_10_00Z_uNiQuE_archive
.Se o formato de data e hora do nome do arquivo terminar em um caractere que não é um correspondente, esse caractere substituirá o separador entre
<UTC-date-time>
e<uuid>
. Por exemplo, se o valor do formato de data e hora do nome do arquivo forYYYY-MM-DDThh_mm_ss-
, um nome de objeto de amostra seráprod_2023-09-25T04_10_00-uNiQuE_archive
.
Lote de arquivos
As assinaturas do Cloud Storage permitem decidir quando criar um novo arquivo de saída armazenado como um objeto no bucket do Cloud Storage. O Pub/Sub grava um arquivo de saída quando uma das condições de lote especificadas é atendida. Estas são as condições de lote do Cloud Storage:
Duração máxima do lote de armazenamento. Essa configuração é obrigatória. A assinatura do Cloud Storage gravará um novo arquivo de saída se o valor especificado da duração máxima for excedido. Se você não especificar o valor, o valor padrão de 5 minutos será aplicado. Veja a seguir os valores aplicáveis para a duração máxima:
- Valor mínimo = 1 minuto
- Valor padrão = 5 minutos
- Valor máximo = 10 minutos
Bytes máximos de lote de armazenamento. Essa configuração é opcional. A assinatura do Cloud Storage gravará um novo arquivo de saída se o valor especificado do máximo de bytes for excedido. Veja a seguir os valores aplicáveis para o máximo de bytes:
- Valor mínimo = 1 KB
- Valor máximo = 10 GiB
Por exemplo, é possível configurar a duração máxima como 6 minutos e o máximo de bytes como 2 GB. Se, no 4o minuto, o arquivo de saída atingir 2 GB, o Pub/Sub finalizará o arquivo anterior e começará a gravar em um novo.
Uma assinatura do Cloud Storage pode gravar em vários arquivos em um bucket do Cloud Storage simultaneamente. Se você configurou sua assinatura para criar um novo arquivo a cada 6 minutos, poderá observar vários arquivos do Cloud Storage sendo criados a cada seis minutos.
Em algumas situações, o Pub/Sub pode começar a gravar em um novo arquivo antes do tempo configurado pelas condições de loteamento de arquivos. Um arquivo também poderá exceder o valor máximo de bytes se a assinatura receber mensagens maiores que esse valor.
Formato do arquivo
Ao criar uma assinatura do Cloud Storage, especifique o formato dos arquivos de saída que serão armazenados em um bucket do Cloud Storage como Text ou Avro.
Texto: as mensagens são armazenadas como texto simples. Um caractere de nova linha separa uma mensagem da mensagem anterior no arquivo. Somente payloads de mensagens são armazenados, não atributos ou outros metadados.
Avro: as mensagens são armazenadas no formato binário Apache Avro. Ao selecionar Avro, você pode ativar as seguintes propriedades adicionais:
Gravar metadados: permite armazenar os metadados da mensagem com a mensagem. Metadados, como os campos
subscription_name
,message_id
,publish_time
eattributes
, são gravados em campos de nível superior no objeto Avro de saída, enquanto todas as outras propriedades da mensagem, exceto dados, (por exemplo, uma chave de ordenação, se presente) são adicionadas como entradas no mapaattributes
.Se a opção write metadata estiver desativada, apenas o payload da mensagem será gravado no objeto Avro de saída. Este é o esquema Avro para as mensagens de saída com metadados de gravação desativados:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessage", "fields": [ { "name": "data", "type": "bytes" } ] }
Este é o esquema Avro para as mensagens de saída com metadados de gravação ativados:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessageWithMetadata", "fields": [ { "name": "subscription_name", "type": "string" }, { "name": "message_id", "type": "string" }, { "name": "publish_time", "type": { "type": "long", "logicalType": "timestamp-micros" } }, { "name": "attributes", "type": { "type": "map", "values": "string" } }, { "name": "data", "type": "bytes" } ] }
Usar esquema de tópicos: essa opção permite que o Pub/Sub use o esquema do tópico do Pub/Sub a que a assinatura está anexada ao gravar arquivos Avro.
Ao usar essa opção, lembre-se de verificar os seguintes requisitos adicionais:
O esquema do tópico precisa estar no formato Apache Avro (link em inglês).
Se usar esquema de tópicos e gravar metadados estiverem ativados, o esquema de tópicos precisará ter um objeto Record na raiz. O Pub/Sub vai expandir a lista de campos do registro para incluir os campos de metadados. Como resultado, o registro não pode conter nenhum campo com o mesmo nome que os campos de metadados (
subscription_name
,message_id
,publish_time
ouattributes
).
Criar uma assinatura do Cloud Storage
Console
-
No console do Google Cloud, acesse a página Assinaturas.
-
Clique em Criar assinatura.
-
Insira um nome no campo ID da assinatura.
Para saber mais sobre como nomear uma assinatura, consulte Diretrizes para nomear um tópico ou uma assinatura.
-
Escolha ou crie um tópico no menu suspenso.
A assinatura recebe mensagens do tópico.
Para mais informações sobre como criar um tópico, consulte Criar e gerenciar tópicos.
-
Selecione o Tipo de entrega como Gravar no Cloud Storage.
-
Para o bucket do Cloud Storage, clique em Procurar.
-
É possível selecionar um bucket atual de qualquer projeto apropriado.
-
Também é possível clicar no ícone "Criar" e seguir as instruções na tela para criar um novo bucket.
Depois de criar o bucket, selecione-o para a assinatura do Cloud Storage.
Para mais informações sobre como criar um bucket, consulte Criar buckets.
Quando você especifica o bucket, o Pub/Sub verifica as permissões apropriadas no bucket para a conta de serviço do Pub/Sub. Se houver problemas de permissão, você verá uma mensagem parecida com esta:
Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions
. -
-
Se você tiver problemas de permissão, clique em Definir permissão e siga as instruções na tela.
Como alternativa, siga as instruções em Atribuir papéis do Cloud Storage à conta de serviço do Pub/Sub.
-
Em Formato de arquivo, selecione Texto ou Avro.
Se você selecionar Avro, também poderá especificar se quer armazenar os metadados da mensagem na saída.
Para mais informações sobre as duas opções, incluindo a opção de metadados de mensagens para o formato Avro, consulte Formato de arquivo.
-
Opcional: é possível especificar o prefixo, sufixo e data e hora do nome do arquivo para todos os arquivos que serão gravados no bucket do Cloud Storage. Um arquivo é armazenado como um objeto no bucket.
Para mais informações sobre como definir o prefixo, o sufixo e a data e hora do arquivo, consulte Prefixo, sufixo e data e hora do nome do arquivo.
-
Em Lote de arquivos, especifique um tempo máximo decorrido antes de criar um novo arquivo.
Também é possível definir o tamanho máximo dos arquivos.
Para saber mais sobre as duas opções de loteamento de arquivos, consulte Lote de arquivos.
-
É altamente recomendável ativar o recurso Mensagens inativas para lidar com falhas de mensagens.
Para mais informações, consulte Tópico de mensagens inativas.
-
Mantenha as outras configurações como padrão e clique em Criar.
gcloud
-
No Console do Google Cloud, ative o Cloud Shell.
Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
- Para criar uma
assinatura do Cloud Storage, execute o comando
gcloud pubsub subscriptions create
.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --cloud-storage-bucket=BUCKET_NAME \ --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \ --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \ --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata
No comando, apenas
SUBSCRIPTION_ID
e as sinalizações--topic
e--cloud-storage-bucket
são obrigatórias. As outras sinalizações são opcionais e podem ser omitidas.Substitua:
SUBSCRIPTION_ID
: o nome ou ID da sua nova assinatura do Cloud Storage.TOPIC_ID
: o nome ou o ID do tópico.BUCKET_NAME
: especifica o nome de um bucket atual. Por exemplo,prod_bucket
. O nome do bucket não pode incluir o ID do projeto. Para criar um bucket, consulte Criar buckets.CLOUD_STORAGE_FILE_PREFIX
: especifica o prefixo do nome de arquivo do Cloud Storage. Por exemplo,log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: especifica o sufixo do nome de arquivo do Cloud Storage. Por exemplo,.txt
.CLOUD_STORAGE_FILE_DATETIME_FORMAT
: especifica o formato de data e hora do nome de arquivo do Cloud Storage. Por exemplo,YYYY-MM-DD/hh_mm_ssZ
.CLOUD_STORAGE_MAX_BYTES
: o máximo de bytes que podem ser gravados em um arquivo do Cloud Storage antes da criação de um novo arquivo. O valor precisa estar entre 1 KB e 10 GB. Por exemplo,20MB
.CLOUD_STORAGE_MAX_DURATION
: a duração máxima que pode decorrer antes da criação de um novo arquivo do Cloud Storage. O valor precisa estar entre 1 m e 10 m. Por exemplo,5m
.CLOUD_STORAGE_OUTPUT_FORMAT
: o formato de saída dos dados gravados no Cloud Storage. Os valores são os seguintes:text
: as mensagens são escritas como texto bruto, separadas por uma nova linha.avro
: as mensagens são escritas como um binário Avro.--cloud-storage-write-metadata
tem efeito apenas para assinaturas com o formato de saídaavro
.
C++
Antes de testar esta amostra, siga as instruções de configuração do C++ no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Go
Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Java
Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do Pub/Sub: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Para autenticar no Pub/Sub, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Monitorar assinaturas
O Cloud Monitoring fornece várias métricas para monitorar assinaturas.
Também é possível monitorar as assinaturas no Pub/Sub.
A seguir
Resolver problemas de uma assinatura do Cloud Storage.
Leia sobre o Cloud Storage.
Revise os preços do Pub/Sub, incluindo a assinatura do Cloud Storage.