Propriedades de assinatura

As propriedades de assinatura do Pub/Sub são as características de uma assinatura. Você pode definir as propriedades da assinatura ao criar ou atualizar uma assinatura.

Este documento descreve as diferentes propriedades de assinatura que podem ser definidas para uma assinatura.

Antes de começar

• Saiba mais sobre assinaturas.

• Entenda o fluxo de trabalho da assinatura que você vai criar: Pull, Push ou BigQuery.

Propriedades comuns de assinatura

Ao criar uma assinatura, você precisa especificar várias opções para configurá-la. Algumas dessas propriedades são comuns a todos os tipos de assinaturas e são discutidas nas próximas seções.

Duração da retenção da mensagem

A opção Duração da retenção de mensagens especifica por quanto tempo o Pub/Sub retém as mensagens após a publicação. Após a duração da retenção de mensagens, o Pub/Sub pode descartar a mensagem, independentemente do estado de confirmação. Para reter mensagens reconhecidas para a duração da retenção da mensagem, consulte Como reproduzir e descartar mensagens.

Confira a seguir os valores da opção Duração da retenção de mensagens:

• Valor padrão = 7 dias
• Valor mínimo = 10 minutos
• Valor máximo = 31 dias

As mensagens não confirmadas podem ser resultado de assinaturas inativas, necessidades de backup ou processamento lento. Se você conseguir processar as mensagens em até 24 horas, não haverá cobranças adicionais. Para evitar novas cobranças, gerencie esses cenários da seguinte forma:

• Assinaturas inativas. Exclua assinaturas inativas para evitar cobranças de retenção de mensagens de assinatura.

• Armazenamento de backup. Se você estiver usando a retenção de assinaturas como armazenamento de backup, mude para outra opção de armazenamento, como retenção de mensagens de tópico ou retenção de mensagens confirmadas. A retenção de mensagens de tópico armazena mensagens apenas uma vez no nível do tópico, e elas permanecem disponíveis para todas as assinaturas consumirem quando necessário.

• Atrasos no processamento. Adicione mais assinantes (se possível) para processar as mensagens em um dia.

Reter mensagens reconhecidas

Se você especificar a Duração da retenção de mensagens, também poderá especificar se quer reter mensagens confirmadas.

A opção Reter mensagens confirmadas permite reter mensagens confirmadas pelo período de retenção especificado. Isso aumenta as taxas de armazenamento de mensagens. Para mais informações, consulte custos de armazenamento.

Período de expiração

Com a opção Período de expiração, é possível estender o prazo de validade da sua assinatura.

As assinaturas sem atividade do assinante ou mudanças nas propriedades expiram. Se o Pub/Sub detectar atividade do assinante ou se você atualizar alguma das propriedades da assinatura, o relógio de exclusão da assinatura será reiniciado. Exemplos de atividades do assinante incluem conexões abertas, pulls ativos ou pushes bem-sucedidos.

Se você especificar o período de expiração, o valor precisará ser pelo menos tão longo quanto a duração da retenção da mensagem especificada na opção Duração da retenção de mensagens.

Confira a seguir os valores da opção Período de expiração:

• Valor padrão = 31 dias
• Valor mínimo = 1 dia

Para evitar que uma assinatura expire, defina o período de expiração como never expire.

Prazo de confirmação

A opção Prazo de confirmação especifica o prazo inicial após o qual uma mensagem não confirmada é enviada novamente. É possível estender o prazo de confirmação por mensagem enviando solicitações ModifyAckDeadline subsequentes.

Confira a seguir os valores da opção Prazo de confirmação:

• Valor padrão = 10 segundos
• Valor mínimo = 10 segundos
• Valor máximo = 600 segundos

Em alguns casos, as bibliotecas de cliente do Pub/Sub podem controlar a taxa de entrega e modificar dinamicamente o prazo de confirmação. Assim, a mensagem pode ser entregue novamente antes do prazo de confirmação definido por você. Para substituir esse comportamento, use minDurationPerAckExtension e maxDurationPerAckExtension. Para mais informações sobre como usar esses valores, consulte Suporte para entrega exatamente uma vez em bibliotecas de cliente.

Transformações de mensagem única (SMTs)

As SMTs permitem modificações leves nos atributos e dados das mensagens diretamente no Pub/Sub. Esse recurso permite a limpeza, filtragem ou conversão de formato de dados antes que as mensagens sejam entregues a um cliente assinante.

Para mais informações, consulte Visão geral das SMTs e Criar uma assinatura com SMTs.

Filtro de assinatura

Use a opção Filtro de assinatura para especificar uma string com uma expressão de filtragem. Se uma assinatura tiver um filtro, ela só entregará as mensagens correspondentes a ele. O serviço Pub/Sub reconhece automaticamente as mensagens que não correspondem ao filtro.

• É possível filtrar mensagens pelos atributos, mas não pelos dados nelas.

• Se não for especificada, a assinatura não filtrará as mensagens, e os inscritos vão receber todas as mensagens.

• Depois de aplicados, os filtros não podem ser alterados nem removidos.

Quando você recebe mensagens de uma assinatura com um filtro, não há taxas de saída para as mensagens que o Pub/Sub confirma automaticamente. Sujeito a taxas de entrega de mensagens e taxas de armazenamento relacionadas à busca para essas mensagens.

Para mais informações, consulte Filtrar mensagens de uma assinatura.

Ordenação das mensagens

Quando uma assinatura tem a ordem de mensagens ativada, os clientes assinantes recebem mensagens publicadas na mesma região com a mesma chave de ordenação na ordem em que as mensagens foram recebidas pelo serviço.

Ao usar a entrega ordenada, as confirmações de mensagens posteriores não são processadas até que as confirmações de mensagens anteriores sejam processadas.

Os editores precisam enviar mensagens com uma chave de ordenação para que o Pub/Sub possa entregar as mensagens em ordem.

Se não for definido, o Pub/Sub poderá não entregar mensagens em ordem, mesmo que elas tenham uma chave de ordenação.

Tópico de mensagens inativas

Quando uma mensagem não pode ser entregue após um número definido de tentativas de entrega ou um assinante não consegue confirmar a mensagem, é possível configurar um tópico de mensagens inativas para republicar essas mensagens.

Se você definir um tópico de mensagem inativa, também será possível especificar o número máximo de tentativas de entrega. Estes são os valores para o número máximo de tentativas de entrega do tópico de mensagens inativas:

• Valor padrão = 5 tentativas de entrega
• Valor mínimo = 5 tentativas de entrega
• Valor máximo = 100 tentativas de entrega

Se o tópico de mensagens inativas estiver em um projeto diferente da assinatura, também será necessário especificar o ID do projeto com o tópico de mensagens inativas.

Para mais informações, consulte Encaminhar para tópicos de mensagens inativas.

Política de repetição

Se o prazo de confirmação expirar ou um assinante responder com uma confirmação negativa, o Pub/Sub poderá enviar a mensagem novamente. Essa tentativa de nova entrega é conhecida como política de novas tentativas da assinatura.

Por padrão, a política de repetição de uma assinatura é definida para usar Tentar de novo imediatamente. Com essa opção, o Pub/Sub reenvia a mensagem quando o prazo de confirmação expira ou um assinante responde com uma confirmação negativa.

Você também pode definir o valor como Repetir após atraso de espera exponencial. Nesse caso, especifique os valores máximo e mínimo de espera.

Confira algumas diretrizes para definir os valores máximo e mínimo de espera:

• Se você definir o valor máximo para a duração da espera, o valor padrão para a duração mínima da espera será de 10 segundos.

• Se você definir o valor mínimo para a duração da espera, o valor padrão para a duração máxima da espera será de 600 segundos.

• A duração de espera mais longa que você pode especificar é de 600 segundos.

Política de repetição e mensagens em lote

Se as mensagens estiverem em lote, o Pub/Sub iniciará a espera exponencial quando uma das seguintes situações ocorrer:

• O assinante envia uma confirmação negativa para cada mensagem no lote.

• O prazo de confirmação expira.

Política de repetição e assinatura push

Se você receber mensagens de uma assinatura de push, o Pub/Sub pode reenviá-las após a espera em push em vez da duração da espera exponencial. Quando a espera em push é mais longa do que a duração da espera exponencial, o Pub/Sub reenvia mensagens não confirmadas após a espera em push.

Propriedades de assinatura de pull

Ao configurar uma assinatura de extração, é possível especificar as seguintes propriedades.

Entrega exatamente uma vez

Entrega exatamente uma vez. Se definido, o Pub/Sub atende às garantias de entrega exatamente uma vez. Se não for especificado, a assinatura vai oferecer suporte à entrega pelo menos uma vez para cada mensagem.

Propriedades de assinatura por push

Ao configurar uma assinatura de push, é possível especificar as seguintes propriedades.

Endpoints

URL do endpoint (obrigatório). Um endereço HTTPS acessível publicamente. O servidor do endpoint de push precisa ter um certificado SSL válido assinado por uma autoridade de certificação. O serviço do Pub/Sub entrega mensagens para enviar endpoints da mesma Google Cloud região em que o serviço do Pub/Sub armazena as mensagens. O serviço Pub/Sub entrega mensagens da mesma região Google Cloud com base no melhor esforço.

• Se os assinantes usam um firewall, eles não podem receber solicitações push. Para receber solicitações push, desative o firewall e verifique o JSON Web Token (JWT) usado na solicitação. Se um assinante tiver um firewall, talvez você receba um erro 403 permission denied.

• O Pub/Sub não exige mais prova de propriedade para domínios de URL de assinatura por push. Se seu domínio receber solicitações POST inesperadas do Pub/Sub, relate suspeita de abuso.

Autenticação

Ative a autenticação. Quando ativadas, as mensagens entregues pelo Pub/Sub ao endpoint de push incluem um cabeçalho de autorização para permitir que o endpoint autentique a solicitação. Os mecanismos de autenticação e autorização automáticos estão disponíveis para os endpoints do ambiente padrão do App Engine e do Cloud Run functions hospedados no mesmo projeto da assinatura.

A configuração de autenticação de uma assinatura push autenticada consiste em uma conta serviço gerenciado pelo usuário e nos parâmetros de público-alvo especificados em uma chamada create, patch ou ModifyPushConfig. Você também precisa conceder um papel específico a uma conta de serviço, conforme discutido na próxima seção.

• Público-alvo. Uma única string, indiferente a maiúsculas, que o webhook usa para validar o público-alvo desse token.

• Conta de serviço. O Pub/Sub cria automaticamente uma conta de serviço para você no formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Pré-requisitos para ativar a autenticação

A conta serviço gerenciado pelo usuário é a conta associada à assinatura de push. Essa conta é usada como a declaração email do JSON Web Token (JWT) gerado. Confira a seguir uma lista de requisitos para a conta de serviço:

• Essa conta serviço gerenciado pelo usuário precisa estar no mesmo projeto da assinatura por push.

• O principal que está criando ou modificando a assinatura de push precisa ter a permissão iam.serviceAccounts.actAs na conta de serviço gerenciada pelo usuário para anexar a conta de serviço à assinatura de push. Para mais informações, consulte Anexar contas de serviço a recursos.

• Permissões necessárias: essa conta de serviço precisa receber a permissão iam.serviceAccounts.getOpenIdToken (incluída no papel roles/iam.serviceAccountTokenCreator) para permitir que o Pub/Sub crie tokens JWT para a conta de serviço especificada autenticar solicitações push.

Desencapsulamento de payload

A opção Ativar desencapsulamento de payload remove todos os metadados das mensagens do Pub/Sub, exceto os dados da mensagem. Com o desencapsulamento de payload, os dados da mensagem são entregues diretamente como o corpo HTTP.

Você também pode ativar a opção Gravar metadados. A opção Gravar metadados adiciona ao cabeçalho da solicitação os metadados removidos das mensagens.

Propriedades do BigQuery

Ao selecionar um tipo de entrega de assinatura como Gravar no BigQuery, é possível especificar as seguintes propriedades adicionais.

Usar esquema de tópicos

Com essa opção, o Pub/Sub usa o esquema do tópico do Pub/Sub a que a assinatura está anexada. Além disso, o Pub/Sub grava os campos nas mensagens nas colunas correspondentes da tabela do BigQuery.

Ao usar essa opção, verifique os seguintes requisitos adicionais:

• Os campos no esquema de tópicos e no esquema do BigQuery precisam ter os mesmos nomes e tipos compatíveis entre si.

• Qualquer campo opcional no esquema de tópicos também precisa ser opcional no esquema do BigQuery.

• Os campos obrigatórios no esquema de tópicos não precisam ser obrigatórios no esquema do BigQuery.

• Se houver campos do BigQuery que não estão presentes no esquema de tópicos, eles precisam estar no modo NULLABLE.

• Se o esquema de tópico tiver campos extras que não estão presentes no esquema do BigQuery e puderem ser descartados, selecione a opção Descartar campos desconhecidos.

• Você pode selecionar apenas uma das propriedades de assinatura: Usar esquema de tópico ou Usar esquema de tabela.

Se você não selecionar a opção Usar esquema de tópicos ou Usar esquema de tabela, verifique se a tabela do BigQuery tem uma coluna chamada data do tipo BYTES, STRING ou JSON. O Pub/Sub grava a mensagem nessa coluna do BigQuery.

As mudanças no esquema de tópicos do Pub/Sub ou no esquema de tabela do BigQuery podem não entrar em vigor imediatamente com as mensagens gravadas na tabela do BigQuery. Por exemplo, se a opção Descartar campos desconhecidos estiver ativada e um campo estiver presente no esquema do Pub/Sub, mas não no do BigQuery, as mensagens gravadas na tabela do BigQuery ainda poderão não conter o campo depois de adicioná-lo ao esquema do BigQuery. Com o tempo, os esquemas vão se sincronizar, e as mensagens subsequentes vão incluir o campo.

Ao usar a opção Usar esquema de tópico na sua assinatura do BigQuery, você também pode aproveitar a captura de dados alterados (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery processando e aplicando mudanças às linhas atuais.

Para saber mais sobre esse recurso, consulte Fazer streaming de atualizações da tabela com captura de dados alterados.

Para saber como usar esse recurso com assinaturas do BigQuery, consulte Captura de dados de alterações do BigQuery.

Usar esquema de tabela

Com essa opção, o Pub/Sub usa o esquema da tabela do BigQuery para gravar os campos de uma mensagem JSON nas colunas correspondentes. Ao usar essa opção, verifique os seguintes requisitos adicionais:

• Os nomes de cada coluna na tabela do BigQuery só podem conter letras (a-z, A-Z), números (0-9) ou sublinhados (_).

• As mensagens publicadas precisam estar no formato JSON.

• As seguintes conversões JSON são compatíveis:

  Tipo de JSON	Tipo de dados do BigQuery
  string	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME ou TIMESTAMP
  number	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME ou TIMESTAMP

  • Ao usar number para DATE, DATETIME, TIME ou TIMESTAMP conversões, o número precisa obedecer às representações aceitas.
  • Ao usar number para conversão de NUMERIC ou BIGNUMERIC, a precisão e o intervalo de valores são limitados aos aceitos pelo padrão IEEE 754 para aritmética de ponto flutuante. Se você precisar de alta precisão ou um intervalo maior de valores, use conversões de string para NUMERIC ou BIGNUMERIC.
  • Ao usar string para conversões de NUMERIC ou BIGNUMERIC, o Pub/Sub pressupõe que a string é um número legível por humanos (por exemplo, "123.124"). Se o processamento da string como um número legível por humanos falhar, o Pub/Sub vai tratar a string como bytes codificados com o BigDecimalByteStringEncoder.

• Se o tópico da assinatura tiver um esquema associado a ele, a propriedade de codificação da mensagem precisará ser definida como JSON.

• Se houver campos do BigQuery que não estão presentes nas mensagens, eles precisam estar no modo NULLABLE.

• Se as mensagens tiverem campos extras que não estão no esquema do BigQuery e puderem ser descartados, selecione a opção Descartar campos desconhecidos.

• Você pode selecionar apenas uma das propriedades de assinatura: Usar esquema de tópico ou Usar esquema de tabela.

Se você não selecionar a opção Usar esquema de tópicos ou Usar esquema de tabela, verifique se a tabela do BigQuery tem uma coluna chamada data do tipo BYTES, STRING ou JSON. O Pub/Sub grava a mensagem nessa coluna do BigQuery.

As mudanças no esquema da tabela do BigQuery podem não entrar em vigor imediatamente com as mensagens gravadas na tabela. Por exemplo, se a opção Descartar campos desconhecidos estiver ativada e um campo estiver presente nas mensagens, mas não no esquema do BigQuery, as mensagens gravadas na tabela do BigQuery ainda poderão não conter o campo depois de adicioná-lo ao esquema do BigQuery. Com o tempo, o esquema é sincronizado e as mensagens subsequentes incluem o campo.

Ao usar a opção Usar esquema de tabela na sua assinatura do BigQuery, você também pode aproveitar a captura de dados alterados (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery processando e aplicando mudanças às linhas existentes.

Para saber mais sobre esse recurso, consulte Fazer streaming de atualizações da tabela com captura de dados alterados.

Para saber como usar esse recurso com assinaturas do BigQuery, consulte Captura de dados de alterações do BigQuery.

Remover campos desconhecidos

Essa opção é usada com as opções Usar esquema de tópicos ou Usar esquema de tabela. Quando ativada, essa opção permite que o Pub/Sub descarte qualquer campo presente no esquema ou na mensagem do tópico, mas não no esquema do BigQuery. Os campos que não fazem parte do esquema do BigQuery são descartados ao gravar a mensagem na tabela do BigQuery.

Sem a opção Descartar campos desconhecidos definida, as mensagens com campos extras não são gravadas no BigQuery e permanecem no backlog da assinatura, a menos que você configure um tópico de mensagens mortas.

A configuração Descartar campos desconhecidos não afeta campos que não estão definidos no esquema de tópico do Pub/Sub ou no esquema de tabela do BigQuery. Nesse caso, uma mensagem válida do Pub/Sub é entregue à assinatura. No entanto, como o BigQuery não tem colunas definidas para esses campos extras, eles são descartados durante o processo de gravação do BigQuery. Para evitar esse comportamento, verifique se todos os campos contidos na mensagem do Pub/Sub também estão no esquema da tabela do BigQuery.

O comportamento em relação a campos extras também pode depender do tipo de esquema específico (Avro, buffer de protocolo) e da codificação (JSON, binário) usados. Para informações sobre como esses fatores afetam o processamento de campos extras, consulte a documentação do tipo de esquema e da codificação específicos.

Gravar metadados

Essa opção permite que o Pub/Sub grave os metadados de cada mensagem em colunas adicionais na tabela do BigQuery. Caso contrário, os metadados não serão gravados na tabela do BigQuery.

Se você selecionar a opção Gravar metadados, verifique se a tabela do BigQuery tem os campos descritos na tabela a seguir.

Se você não selecionar a opção Gravar metadados, a tabela de destino do BigQuery só vai exigir o campo data, a menos que use_topic_schema seja verdadeiro. Se você selecionar as opções Gravar metadados e Usar esquema de tópico, o esquema do tópico não poderá conter campos com nomes que correspondam aos dos parâmetros de metadados. Essa limitação inclui versões camelcase desses parâmetros snake case.

Parâmetros
subscription_name	STRING Nome de uma assinatura.
message_id	STRING ID de uma mensagem
publish_time	TIMESTAMP O horário de publicação de uma mensagem.
data	BYTES, STRING ou JSON O corpo da mensagem. O campo data é obrigatório para todas as tabelas de destino do BigQuery que não selecionam Usar esquema de tópico ou Usar esquema de tabela. Se o campo for do tipo JSON, o corpo da mensagem precisa ser um JSON válido.
attributes	STRING ou JSON Um objeto JSON que contém todos os atributos da mensagem. Ele também contém outros campos que fazem parte da mensagem do Pub/Sub, incluindo a chave de ordenação, se presente.

Propriedades do Cloud Storage

Ao selecionar um tipo de entrega de assinatura como Gravar no Cloud Storage, é possível especificar as seguintes propriedades adicionais.

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 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 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 de arquivo e dos campos que você pode personalizar:

• <file-prefix> é o prefixo do nome de arquivo personalizado. Esse campo é opcional.

• <UTC-date-time> é uma string personalizável gerada automaticamente com base no momento em que o objeto é criado.

• <uuid> é uma string aleatória gerada automaticamente para o objeto.

• <file-suffix> é o sufixo personalizado do nome do arquivo. Esse campo é opcional. O sufixo do nome do arquivo não pode terminar com "/".

• É possível mudar o prefixo e o sufixo do nome do arquivo:

  • Por exemplo, se o valor do prefixo do nome de arquivo for prod_ e o valor do sufixo for _archive, um nome de objeto de exemplo 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 será do 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 objetos do Cloud Storage.

• Você pode mudar como a data e a hora são mostradas no nome do arquivo:

  • Correspondedores de data e hora obrigatórios que podem ser usados apenas uma vez: ano (YYYY ou YY), mês (MM), dia (DD), hora (hh), minuto (mm), segundo (ss). Por exemplo, YY-YYYY ou MMM é inválido.

  • Correspondedores opcionais que podem ser usados apenas uma vez: separador de data e hora (T) 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 amostra será prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Se o formato de data e hora do nome do arquivo terminar com um caractere que não seja um comparador, esse caractere vai substituir o separador entre <UTC-date-time> e <uuid>. Por exemplo, se o valor do formato de data e hora do nome do arquivo for YYYY-MM-DDThh_mm_ss-, um nome de objeto de amostra será prod_2023-09-25T04_10_00-uNiQuE_archive.

Lote de arquivos

Com as assinaturas do Cloud Storage, você decide quando quer 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 loteamento do Cloud Storage:

• Duração máxima do lote de armazenamento. Essa é uma configuração obrigatória. A assinatura do Cloud Storage grava um novo arquivo de saída se o valor especificado de duração máxima for excedido. Se você não especificar o valor, o padrão de 5 minutos será aplicado. Confira 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

• Máximo de bytes do lote de armazenamento. Essa configuração é opcional. A assinatura do Cloud Storage grava um novo arquivo de saída se o valor especificado de bytes máximos for excedido. Estes são os valores aplicáveis para bytes máximos:

  • Valor mínimo = 1 KB
  • Valor máximo = 10 GiB

• Número máximo de mensagens do lote de armazenamento. Essa configuração é opcional. A assinatura do Cloud Storage grava um novo arquivo de saída se o número máximo de mensagens especificado for excedido. Confira abaixo os valores aplicáveis para o número máximo de mensagens:

  • Valor mínimo = 1000

Por exemplo, é possível configurar a duração máxima como 6 minutos e o número máximo de bytes como 2 GB. Se, no quarto minuto, o arquivo de saída atingir um tamanho de 2 GB, o Pub/Sub vai 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, é possível observar vários arquivos do Cloud Storage sendo criados a cada 6 minutos.

Em algumas situações, o Pub/Sub pode começar a gravar em um novo arquivo antes do horário configurado pelas condições de agrupamento em lote. Um arquivo também pode exceder o valor de "Max bytes" se a assinatura receber mensagens maiores que esse valor.

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 anterior no arquivo. Somente os payloads de mensagens são armazenados, não atributos ou outros metadados.

• Avro: as mensagens são armazenadas no formato binário do Apache Avro. Ao selecionar Avro, você pode ativar estas propriedades adicionais:

  • Gravar metadados: com essa opção, é possível armazenar os metadados da mensagem junto com ela. Metadados como os campos subscription_name, message_id, publish_time e attributes são gravados em campos de nível superior no objeto Avro de saída, enquanto todas as outras propriedades da mensagem, além dos dados (por exemplo, uma ordering_key, se presente), são adicionadas como entradas no mapa attributes.

    Se a opção gravar metadados estiver desativada, apenas a carga útil da mensagem será gravada no objeto Avro de saída. Confira abaixo o esquema Avro para as mensagens de saída com os metadados de gravação desativados:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Confira o esquema Avro para as mensagens de saída com os 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ópico: 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, verifique os seguintes requisitos adicionais:

    • O esquema do tópico precisa estar no formato Apache Avro.

    • Se as opções usar esquema de tópico e gravar metadados estiverem ativadas, o esquema de tópico 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 ou attributes).

Conta de serviço

Você tem as seguintes opções para gravar mensagens em uma tabela do BigQuery ou em um bucket do Cloud Storage:

• Configure uma conta de serviço personalizada para que apenas usuários com a permissão iam.serviceAccounts.actAs na conta de serviço possam criar uma assinatura que grava na tabela ou no bucket. Um exemplo de papel que inclui a permissão iam.serviceAccounts.actAs é o papel de Usuário da conta de serviço (roles/iam.serviceAccountUser).

• Use o agente de serviço padrão do Pub/Sub, que permite que qualquer usuário com a capacidade de criar assinaturas no projeto crie uma assinatura que grave na tabela ou no bucket. O agente de serviço do Pub/Sub é a configuração padrão quando você não especifica uma conta de serviço personalizada.

A seguir

• Crie uma assinatura de pull.
• Crie uma assinatura por push.
• Crie uma assinatura do BigQuery.
• Crie uma assinatura do Cloud Storage.