Este documento descreve 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, certifique-se de que você esteja familiarizado com o seguinte:
- 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, você precisa configurar o controle de acesso no projeto nível
Você também precisa de permissões no nível do recurso se as assinaturas e os 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 um 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
Editor do Pub/Sub (roles/pubsub.editor
) do IAM no projeto.
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
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
-
Anexe uma assinatura a um tópico:
pubsub.topics.attachSubscription
-
Extrair de uma assinatura:
pubsub.subscriptions.consume
-
Assinar uma assinatura:
pubsub.subscriptions.get
-
Listar uma assinatura:
pubsub.subscriptions.list
-
Atualizar uma assinatura:
pubsub.subscriptions.update
-
Excluir uma assinatura:
pubsub.subscriptions.delete
-
Acesse a política do IAM para uma assinatura:
pubsub.subscriptions.getIamPolicy
-
Configure a política do IAM para uma assinatura:
pubsub.subscriptions.setIamPolicy
Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.
Se você precisar criar assinaturas do Cloud Storage em um projeto associado 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)
do 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
permite que eles acessem seus recursos. Essas contas de serviço 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 dele. Escolha um dos seguintes procedimentos:
Conceda permissões no nível do bucket. No Cloud Storage específico conceda o papel Criador de objetos do Storage (
roles/storage.objectCreator
) e o papel Leitor de bucket legado do Storage (roles/storage.legacyBucketReader
) à conta de serviço do Pub/Sub.Se você precisar conceder papéis no nível do projeto, conceda o papel de administrador do Storage (
roles/storage.admin
) no projeto que contém o bucket do Cloud Storage. Conceda esse papel ao conta de serviço do Pub/Sub.
Permissões de bucket
Siga estas etapas para conceder ao 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 seção Permissões > Visualizar por principais, clique em Conceder acesso.
A página Conceder acesso será aberta.
Na seção Adicionar principais, insira o nome do seu Pub/Sub conta de serviço.
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
.Em Atribuir funções > menu suspenso Selecionar papel Insira
Creator
e selecione o papel Criador de objetos do Storage.Clique em Adicionar outro papel.
No menu suspenso Selecionar papel, insira
Bucket Reader
. e selecione o papel Leitor de bucket legado do Storage.Clique em Salvar.
Permissões do projeto
Siga estas etapas para conceder o papel de 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, digite
Storage Admin
e selecione o papel Administrador do Storage.Clique em Salvar.
Para mais informações sobre o IAM do Cloud Storage, consulte Gerenciamento de identidade e acesso do Cloud Storage.
Propriedades de assinatura do Cloud Storage
Ao configurar uma assinatura do Cloud Storage, você precisa especificar propriedades comuns a todos os tipos de assinatura e algumas Propriedades específicas da assinatura do Cloud Storage.
Propriedades comuns de assinaturas
Saiba mais sobre as propriedades comuns de assinaturas que você pode definir em todas as assinaturas.
Nome do bucket
Um bucket do Cloud Storage precisa existir antes de você criar uma assinatura do Cloud Storage.
As mensagens são enviadas em 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 Pagamentos do solicitante desativado.
Para criar um bucket do Cloud Storage, consulte Crie buckets.
Prefixo, sufixo e data/hora do nome de arquivo
Os arquivos de saída gerados pelo Cloud Storage
são armazenadas 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 você podem personalizar:
<file-prefix>
é o prefixo de nome de arquivo personalizado. Esse campo é opcional.<UTC-date-time>
é uma string gerada automaticamente e personalizável com base no momento em que o objeto é criado.<uuid>
é uma string aleatória gerada automaticamente para o objeto.<file-suffix>
é o sufixo do nome de arquivo personalizado. Esse campo é opcional. O O sufixo do nome do arquivo não pode terminar em "/".É possível mudar o prefixo e o sufixo do nome do arquivo:
Por exemplo, se o valor do prefixo do nome do arquivo for
prod_
e o valor do sufixo do nome do arquivo for_archive
, um exemplo de nome de objeto seráprod_2023-09-25T04:10:00+00:00_uN1QuE_archive
.Se você não especificar o prefixo e o sufixo do nome do arquivo, o nome do objeto armazenado no bucket do Cloud Storage tem o formato:
<UTC-date-time>_<uuid>
:Os requisitos de nomenclatura de objetos do Cloud Storage também se aplicam ao nome de arquivo e sufixo. 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:
Os comparadores de data/hora obrigatórios que podem ser usados apenas uma vez: ano (
YYYY
ouYY
), mês (MM
), dia (DD
), hora (hh
), minuto (mm
) e segundo (ss
). Por exemplo,YY-YYYY
ouMMM
são inválidos.Correspondências opcionais que podem ser usadas apenas uma vez: separador de data e hora (
T
) e e deslocamento 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 exemplo 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 seja correspondente, esse caractere substituirá o separador entre
<UTC-date-time>
e<uuid>
. Por exemplo, se o valor do formato datetime do nome do arquivo forYYYY-MM-DDThh_mm_ss-
, um nome de objeto de amostra éprod_2023-09-25T04_10_00-uNiQuE_archive
.
Lote de arquivos
As assinaturas do Cloud Storage permitem que você decida quando criar um novo arquivo de saída armazenado como um objeto no Cloud Storage do Google Cloud. O Pub/Sub grava um arquivo de saída quando que as condições de lote especificadas sejam atendidas. A seguir estão os Condições de lote do Cloud Storage:
Duração máxima do lote de armazenamento. Essa é uma configuração obrigatória. O 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, será aplicado um valor padrão de 5 minutos. Confira 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. O A assinatura do Cloud Storage grava um novo arquivo de saída se o o valor especificado do máximo de bytes for excedido. Os itens a seguir são os valores para o máximo de bytes:
- Valor mínimo = 1 KB
- Valor máximo = 10 GiB
Mensagens máximas de lote de armazenamento. Essa configuração é opcional. O A assinatura do Cloud Storage grava um novo arquivo de saída se o número especificado de mensagens é excedido. Os itens a seguir são os valores para o máximo de mensagens:
- Valor mínimo = 1.000
Por exemplo, é possível configurar a duração máxima como 6 minutos e os bytes máximos como 2 GB. Se, no 4o minuto, o arquivo de saída atingir uma tamanho de arquivo de 2 GB, o Pub/Sub finaliza o arquivo anterior e começa gravar em um novo arquivo.
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 seis minutos, talvez observe 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 do arquivo anterior ao horário configurado pelas condições de lote do arquivo. Um arquivo também poderá exceder o valor máximo de bytes se a assinatura recebe mensagens maiores que o valor máximo de bytes.
Formato do arquivo
Ao criar uma assinatura do Cloud Storage, é possível especificar o formato dos arquivos de saída que serão armazenados em um bucket do Cloud Storage como Texto ou Avro.
Texto: as mensagens são armazenadas como texto simples. Um caractere de nova linha separa uma mensagem da mensagem anterior no arquivo. Apenas mensagem payloads são armazenados, não atributos ou outros metadados.
Avro: as mensagens são armazenadas em Formato do binário Apache Avro (link em inglês). Ao selecionar Avro, você pode ativar as seguintes propriedades adicionais:
Gravar metadados: essa opção permite armazenar os metadados da mensagem junto com ela. 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 de 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" } ] }
Confira o esquema do 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 o esquema do tópico: essa opção permite que o Pub/Sub use o esquema do tópico do Pub/Sub ao qual 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.
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 campos com o mesmo nome dos 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.
-
No campo ID da assinatura, insira um nome.
Para obter informações 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 saber como criar um tópico, consulte Criar e gerenciar tópicos.
-
Selecione Tipo de entrega como Gravar no Cloud Storage.
-
No bucket do Cloud Storage, clique em Procurar.
-
É possível selecionar um bucket atual de qualquer projeto apropriado.
-
Você também pode clicar no ícone "Criar" e seguir as instruções 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 o Pub/Sub conta de serviço. Se houver problemas de permissões, vai aparecer uma mensagem semelhante ao seguinte:
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 (link em inglês).
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 mensagem para o formato Avro, consulte Formato de arquivo.
-
Opcional: é possível especificar o prefixo, sufixo e datetime para todos os arquivos que serão gravados no do bucket do Cloud Storage. Um arquivo é armazenado como um objeto no bucket.
Para mais informações sobre como definir os prefixos, sufixos e datetime, consulte Prefixo, sufixo e datetime.
-
Em Lote de arquivos, especifique o tempo máximo decorrido. antes de criar um novo arquivo.
Também é possível definir o tamanho máximo do arquivo ou o número máximo de mensagens para os arquivos.
Para mais informações sobre as duas opções de agrupamento de arquivos, consulte Agrupamento de arquivos.
-
É altamente recomendável ativar a Dead lettering para processar falhas de mensagens.
Para mais informações, consulte Mensagens mortas tópico.
-
Mantenha as outras configurações como padrão e clique em Criar.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
- 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-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata --cloud-storage-use-topic-schema
No comando, apenas
SUBSCRIPTION_ID
, o as sinalizações--topic
e--cloud-storage-bucket
são obrigatórios. As flags restantes 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 ID do tópico.BUCKET_NAME
: especifica o nome de um bucket existente. Por exemplo,prod_bucket
. O 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 do arquivo do Cloud Storage. Por exemplo,log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: especifica o sufixo para o 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_DURATION
: a duração máxima que pode decorrer antes que um novo arquivo do Cloud Storage seja criado. O valor precisa estar entre 1 m e 10 m. Por exemplo,5m
.CLOUD_STORAGE_MAX_BYTES
: o número máximo de bytes que podem ser gravados em um arquivo do Cloud Storage antes que um novo arquivo seja criado. O valor precisa estar entre 1 KB e 10 GB. Por exemplo,20MB
.CLOUD_STORAGE_MAX_MESSAGES
: o número máximo de mensagens que podem ser gravadas em um arquivo do Cloud Storage antes que um novo arquivo seja criado. O valor precisa ser maior ou igual a como 1.000. Por exemplo,100000
.CLOUD_STORAGE_OUTPUT_FORMAT
: a saída para dados gravados no Cloud Storage. Os valores são os seguintes:text
: as mensagens são escritas como texto bruto e são separadas por uma nova linha.avro
: as mensagens são gravadas como um binário Avro.--cloud-storage-write-metadata
e--cloud-storage-use-topic-schema
só afetam 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 API C++ do Pub/Sub documentação de referência.
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 API Go do Pub/Sub documentação de referência.
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 este exemplo, siga as instruções de configuração do Java na Guia de início rápido do Pub/Sub usando 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 uma assinatura do Cloud Storage
O Cloud Monitoring oferece várias métricas para monitorar assinaturas.
Para conferir uma lista de todas as métricas disponíveis relacionadas ao Pub/Sub e as descrições delas, consulte a documentação de monitoramento do Pub/Sub.
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.