Esta página foi traduzida pela API Cloud Translation.

Propriedades da subscrição

As propriedades de subscrição do Pub/Sub são as caraterísticas de uma subscrição. Pode definir propriedades de subscrição quando cria ou atualiza uma subscrição.

Este documento descreve as diferentes propriedades de subscrição que pode definir para uma subscrição.

Antes de começar

Saiba mais acerca das subscrições.
Compreenda o fluxo de trabalho da subscrição que vai criar: extrair, enviar ou BigQuery.

Propriedades comuns da subscrição

Quando cria uma subscrição, tem de especificar várias opções para configurar a subscrição. Algumas destas propriedades são comuns a todos os tipos de subscrições e são abordadas nas secções seguintes.

Duração da retenção de mensagens

A opção Duração da retenção de mensagens especifica durante 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 rejeitar a mensagem independentemente do estado de confirmação da mensagem. Para reter mensagens reconhecidas durante a duração da retenção de mensagens, consulte o artigo Repetição e rejeição de mensagens.

Seguem-se os valores da opção Duração da retenção de mensagens:

Valor predefinido = 7 dias
Valor mínimo = 10 minutos
Valor máximo = 31 dias

As mensagens não reconhecidas podem resultar de subscrições inativas, necessidades de cópias de segurança ou processamento lento. Se conseguir processar as mensagens no prazo de 24 horas, não incorre em custos adicionais. Pode evitar novas cobranças gerindo estes cenários da seguinte forma:

Subscrições inativas. Elimine subscrições inativas para evitar incorrer em cobranças de retenção de mensagens de subscrição.
Armazenamento de cópias de segurança. Se estiver a usar a retenção de subscrições como armazenamento de cópias de segurança, pode mudar para outra opção de armazenamento, como retenção de mensagens de tópicos ou retenção de mensagens reconhecidas. A retenção de mensagens de tópicos armazena mensagens apenas uma vez ao nível do tópico e permanecem disponíveis para todas as subscrições para consumo quando necessário.
Atrasos no processamento. Adicione mais subscritores (se possível) para processar as mensagens num dia.

Retenha mensagens confirmadas

Se especificar a Duração da retenção de mensagens, também pode especificar se quer reter mensagens reconhecidas.

A opção Manter mensagens confirmadas permite-lhe manter as mensagens confirmadas durante o período de retenção de mensagens especificado. Esta opção aumenta as taxas de armazenamento de mensagens. Para mais informações, consulte os custos de armazenamento.

Período de validade

A opção Período de expiração permite-lhe prolongar o período de expiração da sua subscrição.

As subscrições sem atividade de subscritores nem alterações feitas às propriedades da subscrição expiram. Se o Pub/Sub detetar atividade do subscritor ou se atualizar alguma das propriedades da subscrição, o temporizador de eliminação da subscrição é reiniciado. Exemplos de atividades de subscritores: incluem ligações abertas, obtenções ativas ou envios bem-sucedidos.

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

Seguem-se os valores da opção Período de validade:

Valor predefinido = 31 dias
Valor mínimo = 1 dia

Para evitar que uma subscrição expire, defina o período de validade 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. Pode prolongar o prazo de confirmação mensagem a mensagem enviando pedidos ModifyAckDeadline subsequentes.

Seguem-se os valores da opção Prazo de confirmação:

Valor predefinido = 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. Ao fazê-lo, a mensagem pode ser reenviada antes do prazo de confirmação que definiu. Para substituir este comportamento, use minDurationPerAckExtension e maxDurationPerAckExtension. Para mais informações sobre a utilização destes valores, consulte o artigo Suporte de fornecimento único nas bibliotecas de cliente.

Transformações de mensagens únicas (SMTs)

As SMTs permitem modificações simples aos atributos e dados das mensagens diretamente no Pub/Sub. Esta funcionalidade permite a limpeza, a filtragem ou a conversão de formato de dados antes de as mensagens serem entregues a um cliente subscritor.

Para mais informações, consulte os artigos Vista geral dos SMTs e Crie uma subscrição com SMTs.

Filtro de subscrições

Use a opção Filtro de subscrição para especificar uma string com uma expressão de filtragem. Se uma subscrição tiver um filtro, esta só envia as mensagens que correspondem ao filtro. O serviço Pub/Sub confirma automaticamente as mensagens que não correspondem ao filtro.

Pode filtrar as mensagens pelos respetivos atributos, mas não pelos dados na mensagem.
Se não for especificado, a subscrição não filtra mensagens e os subscritores recebem todas as mensagens.
Não é possível alterar nem remover os filtros depois de os aplicar.

Quando recebe mensagens de uma subscrição com um filtro, não incorre em taxas de saída para as mensagens que o Pub/Sub reconhece automaticamente. Incorre em taxas de entrega de mensagens e taxas de armazenamento relacionadas com a procura para estas mensagens.

Para mais informações, consulte o artigo Filtre mensagens de uma subscrição.

Ordenação de mensagens

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

Quando usa a entrega ordenada, as confirmações das mensagens posteriores não são processadas até que as confirmações das mensagens anteriores sejam processadas.

Os publicadores têm de enviar mensagens com uma chave de ordenação para que o Pub/Sub possa entregar as mensagens por ordem.

Se não estiver definida, o Pub/Sub pode não entregar mensagens por ordem, mesmo que tenham uma chave de ordenação.

Tópico de mensagens não entregues

Quando não é possível entregar uma mensagem após um número definido de tentativas de entrega ou um subscritor não consegue acusar a receção da mensagem, pode configurar um tópico de mensagens não entregues para o qual estas mensagens podem ser republicadas.

Se definir um tópico de mensagens não entregues, também pode especificar o número máximo de tentativas de entrega. Seguem-se os valores para o número máximo de tentativas de entrega do tópico de mensagens não entregues:

Valor predefinido = 5 tentativas de entrega
Valor mínimo = 5 tentativas de entrega
Valor máximo = 100 tentativas de entrega

Se o tópico de mensagens não entregues estiver num projeto diferente da subscrição, também tem de especificar o ID do projeto com o tópico de mensagens não entregues.

Para mais informações, consulte o artigo Encaminhamento para tópicos de mensagens não entregues.

Política de novas tentativas

Se o prazo de confirmação expirar ou um subscritor responder com uma confirmação negativa, o Pub/Sub pode enviar a mensagem novamente. Esta tentativa de reenvio é conhecida como a política de repetição da subscrição.

Por predefinição, a política de repetição de uma subscrição está definida para usar a opção Repetir imediatamente. Com esta opção, o Pub/Sub reenvia a mensagem quando o prazo de confirmação expira ou um subscritor responde com uma confirmação negativa.

Também pode definir o valor como Tentar novamente após o atraso de retirada exponencial. Neste caso, tem de especificar os valores de recuo máximo e mínimo.

Seguem-se algumas diretrizes para definir os valores de recuo máximo e mínimo:

Se definir o valor máximo para a duração da repetição, o valor predefinido para a duração mínima da repetição é de 10 segundos.
Se definir o valor mínimo para a duração da repetição, o valor predefinido para a duração máxima da repetição é de 600 segundos.
A duração máxima de recuo que pode especificar é de 600 segundos.

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

Se as mensagens estiverem num lote, o Pub/Sub inicia o recuo exponencial quando ocorre uma das seguintes situações:

O subscritor envia uma confirmação negativa para cada mensagem no lote.
O prazo de confirmação expira.

Política de repetição e subscrição push

Se receber mensagens de uma subscrição push, o Pub/Sub pode reenviar mensagens após o recuo push em vez da duração do recuo exponencial. Quando a retirada de envio é mais longa do que a duração da retirada exponencial, o Pub/Sub volta a enviar mensagens não reconhecidas após a retirada de envio.

Extraia propriedades de subscrição

Quando configura uma subscrição de obtenção, pode especificar as seguintes propriedades.

Entrega exatamente uma vez

Entrega exatamente uma vez. Se estiver definida, a Pub/Sub cumpre as garantias de entrega exatamente uma vez. Se não for especificado, a subscrição suporta a entrega pelo menos uma vez para cada mensagem.

Envie propriedades de subscrição de emissão

Quando configura uma subscrição push, pode especificar as seguintes propriedades.

Pontos finais

URL do ponto final (obrigatório). Um endereço HTTPS acessível publicamente. O servidor do ponto final de envio por push tem de ter um certificado SSL válido assinado por uma autoridade de certificação. O serviço Pub/Sub envia mensagens para pontos finais push a partir da mesma região em que o serviço Pub/Sub armazena as mensagens. Google Cloud O serviço Pub/Sub envia mensagens da mesma Google Cloud região com base no melhor esforço.

Se os subscritores usarem uma firewall, não podem receber pedidos push. Para receber pedidos push, tem de desativar a firewall e validar o símbolo da Web JSON (JWT) usado no pedido. Se um subscritor tiver uma firewall, pode receber um erro 403 permission denied.
O Pub/Sub já não requer prova de propriedade para domínios de URL de subscrição push. Se o seu domínio receber pedidos POST inesperados do Pub/Sub, pode denunciar suspeitas de abuso.

Autenticação

Ative a autenticação. Quando ativada, as mensagens enviadas pelo Pub/Sub para o ponto final de envio push incluem um cabeçalho de autorização para permitir que o ponto final autentique o pedido. Os mecanismos de autenticação e autorização automáticos estão disponíveis para os pontos finais das funções do App Engine Standard e do Cloud Run alojados no mesmo projeto que a subscrição.

A configuração de autenticação para uma subscrição push autenticada consiste numa conta de serviço gerida pelo utilizador e nos parâmetros de público-alvo que são especificados numa chamada create, patch ou ModifyPushConfig. Também tem de conceder uma função específica a uma conta de serviço, conforme abordado na secção seguinte.

Público-alvo. Uma única string não sensível a maiúsculas e minúsculas que o webhook usa para validar o público-alvo pretendido deste token específico.
Conta de serviço. O Pub/Sub cria automaticamente uma conta de serviço para si no formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Pré-requisitos para ativar a autenticação

A conta de serviço gerida pelo utilizador é a conta de serviço associada à subscrição push. Esta conta é usada como a reivindicação email do símbolo da Web JSON (JWT) gerado. Segue-se uma lista de requisitos para a conta de serviço:

Esta conta de serviço gerida pelo utilizador tem de estar no mesmo projeto que a subscrição push.
O principal que está a criar ou modificar a subscrição push tem de ter a autorização iam.serviceAccounts.actAs na conta de serviço gerida pelo utilizador para anexar a conta de serviço à subscrição push. Para mais informações, consulte o artigo Anexar contas de serviço a recursos.
Autorizações necessárias: esta conta de serviço tem de ter a autorização iam.serviceAccounts.getOpenIdToken (incluída na função roles/iam.serviceAccountTokenCreator) para permitir que o Pub/Sub crie tokens JWT para a conta de serviço especificada autenticar pedidos push.

Unwrapping do payload

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

Também pode ativar a opção Escrever metadados. A opção Escrever metadados adiciona novamente os metadados de mensagens removidos anteriormente ao cabeçalho do pedido.

Propriedades do BigQuery

Quando seleciona um tipo de fornecimento de subscrição como Escrever no BigQuery, pode especificar as seguintes propriedades adicionais.

Use o esquema de tópicos

Esta opção permite que o Pub/Sub use o esquema do tópico Pub/Sub ao qual a subscrição está anexada. Além disso, o Pub/Sub escreve os campos nas mensagens nas colunas correspondentes na tabela do BigQuery.

Quando usar esta opção, lembre-se de verificar os seguintes requisitos adicionais:

Os campos no esquema do tópico e no esquema do BigQuery têm de ter os mesmos nomes e os respetivos tipos têm de ser compatíveis entre si.
Qualquer campo opcional no esquema do tópico também tem de ser opcional no esquema do BigQuery.
Os campos obrigatórios no esquema do tópico não têm de ser obrigatórios no esquema do BigQuery.
Se existirem campos do BigQuery que não estejam presentes no esquema do tópico, estes campos do BigQuery têm de estar no modo NULLABLE.
Se o esquema do tópico tiver campos adicionais que não estão presentes no esquema do BigQuery e estes campos puderem ser ignorados, selecione a opção Ignorar campos desconhecidos.
Só pode selecionar uma das propriedades de subscrição, Usar esquema de tópicos ou Usar esquema de tabelas.

Se não selecionar a opção Usar esquema do tópico ou Usar esquema da tabela, certifique-se de que a tabela do BigQuery tem uma coluna denominada data do tipo BYTES, STRING ou JSON. O Pub/Sub escreve a mensagem nesta coluna do BigQuery.

Pode não ver as alterações ao esquema dos tópicos do Pub/Sub ou ao esquema da tabela do BigQuery entrarem em vigor imediatamente com as mensagens escritas na tabela do BigQuery. Por exemplo, se a opção Ignorar campos desconhecidos estiver ativada e um campo estiver presente no esquema do Pub/Sub, mas não no esquema do BigQuery, as mensagens escritas na tabela do BigQuery podem continuar a não conter o campo depois de o adicionar ao esquema do BigQuery. Eventualmente, os esquemas são sincronizados e as mensagens subsequentes incluem o campo.

Quando usa a opção Usar esquema de tópicos para a sua subscrição do BigQuery, também pode tirar partido da captura de dados de alterações (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery ao processar e aplicar alterações às linhas existentes.

Para saber mais acerca desta funcionalidade, consulte o artigo Atualize a tabela de streams com a captura de dados de alterações.

Para saber como usar esta funcionalidade com subscrições do BigQuery, consulte o artigo Captura de dados de alterações do BigQuery.

Use o esquema da tabela

Esta opção permite que o Pub/Sub use o esquema da tabela do BigQuery para escrever os campos de uma mensagem JSON nas colunas correspondentes. Quando usar esta opção, lembre-se de verificar 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 têm de estar no formato JSON.

As seguintes conversões JSON são suportadas:

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

Quando usar conversões de number para DATE, DATETIME, TIME ou TIMESTAMP, o número tem de cumprir as representações suportadas.
Quando usar number para NUMERIC ou BIGNUMERIC conversão, a precisão e o intervalo de valores estão limitados aos aceites pela norma IEEE 754 para aritmética de vírgula flutuante. Se precisar de uma elevada precisão ou de um intervalo mais amplo de valores, use, em alternativa, conversões string para NUMERIC ou BIGNUMERIC.
Quando usa string para NUMERIC ou conversões BIGNUMERIC, o Pub/Sub assume 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 trata a string como bytes codificados com o BigDecimalByteStringEncoder.

Se o tópico da subscrição tiver um esquema associado, a propriedade de codificação de mensagens tem de ser definida como JSON.
Se existirem campos do BigQuery que não estejam presentes nas mensagens, estes campos do BigQuery têm de estar no modo NULLABLE.
Se as mensagens tiverem campos adicionais que não estão presentes no esquema do BigQuery e estes campos puderem ser ignorados, selecione a opção Ignorar campos desconhecidos.
Só pode selecionar uma das propriedades de subscrição, Usar esquema de tópicos ou Usar esquema de tabelas.

Pode não ver as alterações ao esquema da tabela do BigQuery a produzirem efeito imediato com as mensagens escritas na tabela do BigQuery. Por exemplo, se a opção Ignorar campos desconhecidos estiver ativada e um campo estiver presente nas mensagens, mas não no esquema do BigQuery, as mensagens escritas na tabela do BigQuery podem continuar a não conter o campo depois de o adicionar ao esquema do BigQuery. Eventualmente, o esquema é sincronizado e as mensagens subsequentes incluem o campo.

Quando usa a opção Usar esquema de tabela para a sua subscrição do BigQuery, também pode tirar partido da captura de dados de alterações (CDC) do BigQuery. A CDC atualiza as tabelas do BigQuery processando e aplicando alterações às linhas existentes.

Para saber mais acerca desta funcionalidade, consulte o artigo Atualize a tabela de streams com a captura de dados de alterações.

Para saber como usar esta funcionalidade com subscrições do BigQuery, consulte o artigo Captura de dados de alterações do BigQuery.

Ignorar campos desconhecidos

Esta opção é usada com a opção Usar esquema de tópicos ou Usar esquema de tabelas. Quando ativada, esta opção permite que o Pub/Sub ignore qualquer campo presente no esquema do tópico ou na mensagem, mas não no esquema do BigQuery. Os campos que não fazem parte do esquema do BigQuery são ignorados quando a mensagem é escrita na tabela do BigQuery.

Sem a opção Eliminar campos desconhecidos definida, as mensagens com campos adicionais não são escritas no BigQuery e permanecem na fila de mensagens pendentes da subscrição, a menos que configure um tópico de mensagens não entregues.

A definição Ignorar campos desconhecidos não afeta os campos que não estão definidos no esquema do tópico do Pub/Sub nem no esquema da tabela do BigQuery. Neste caso, é entregue uma mensagem do Pub/Sub válida à subscrição. No entanto, como o BigQuery não tem colunas definidas para estes campos adicionais, estes campos são ignorados durante o processo de escrita do BigQuery. Para evitar este comportamento, certifique-se de que qualquer campo contido na mensagem do Pub/Sub também está contido no esquema da tabela do BigQuery.

O comportamento relativamente a campos adicionais 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 estes fatores afetam o processamento de campos adicionais, consulte a documentação do seu tipo de esquema e codificação específicos.

Escreva metadados

Esta opção permite que o Pub/Sub escreva os metadados de cada mensagem em colunas adicionais na tabela do BigQuery. Caso contrário, os metadados não são escritos na tabela do BigQuery.

Se selecionar a opção Escrever metadados, certifique-se de que a tabela do BigQuery tem os campos descritos na tabela seguinte.

Se não selecionar a opção Escrever metadados, a tabela do BigQuery de destino só requer o campo data, a menos que use_topic_schema seja verdadeiro. Se selecionar as opções Escrever metadados e Usar esquema de tópicos, o esquema do tópico não pode conter campos com nomes que correspondam aos dos parâmetros de metadados. Esta limitação inclui versões em camel case destes parâmetros em snake case.

Parâmetros
`subscription_name`	STRING Nome de uma subscrição.
`message_id`	STRING ID de uma mensagem
`publish_time`	TIMESTAMP A hora de publicação de uma mensagem.
`data`	BYTES, STRING ou JSON O corpo da mensagem. O campo `data` é obrigatório para todas as tabelas do BigQuery de destino que não selecionam Usar esquema de tópicos ou Usar esquema de tabelas. Se o campo for do tipo JSON, o corpo da mensagem tem de ser JSON válido.
`attributes`	STRING ou JSON Um objeto JSON que contém todos os atributos da mensagem. Também contém campos adicionais que fazem parte da mensagem do Pub/Sub, incluindo a chave de ordenação, se estiver presente.

Propriedades do Cloud Storage

Quando seleciona um tipo de fornecimento de subscrição como Escrever no Cloud Storage, pode especificar as seguintes propriedades adicionais.

Nome do contentor

Tem de existir um contentor do Cloud Storage antes de criar uma subscrição do Cloud Storage.

As mensagens são enviadas como lotes e armazenadas no contentor do Cloud Storage. Um único lote ou ficheiro é armazenado como um objeto no contentor.

O contentor do Cloud Storage tem de ter a opção Requester Pays desativada.

Para criar um contentor do Cloud Storage, consulte o artigo Crie contentores.

Prefixo, sufixo e data/hora do nome do ficheiro

Os ficheiros de saída do Cloud Storage gerados pela subscrição do Cloud Storage são armazenados como objetos no contentor do Cloud Storage. O nome do objeto armazenado no contentor do Cloud Storage tem o seguinte formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

A lista seguinte inclui detalhes do formato de ficheiro e dos campos que pode personalizar:

<file-prefix> é o prefixo do nome de ficheiro personalizado. Este é um campo opcional.
<UTC-date-time> é uma string gerada automaticamente e personalizável com base na hora em que o objeto é criado.
<uuid> é uma string aleatória gerada automaticamente para o objeto.
<file-suffix> é o sufixo do nome de ficheiro personalizado. Este é um campo opcional. O sufixo do nome do ficheiro não pode terminar em "/".
Pode alterar o prefixo e o sufixo do nome do ficheiro:
- Por exemplo, se o valor do prefixo do nome do ficheiro for prod_ e o valor do sufixo do nome do ficheiro for _archive, um nome de objeto de exemplo é prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.
- Se não especificar o prefixo e o sufixo do nome de ficheiro, o nome do objeto armazenado no contentor do Cloud Storage tem o seguinte 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 ficheiro. Para mais informações, consulte o artigo Acerca dos objetos do Cloud Storage.
Pode alterar a forma como a data e a hora são apresentadas no nome do ficheiro:
- Os correspondentes de data/hora obrigatórios que pode usar apenas uma vez: ano (YYYY ou YY), mês (MM), dia (DD), hora (hh), minuto (mm) e segundo (ss). Por exemplo, YY-YYYY ou MMM é inválido.
- Correspondedores opcionais que pode usar apenas uma vez: separador de data/hora (T) e desvio do fuso horário (Z ou +00:00).
- Elementos opcionais que pode usar várias vezes: hífen (-), sublinhado (_), dois pontos (:) e barra (/).
- Por exemplo, se o valor do formato de data/hora do nome do ficheiro for YYYY-MM-DD/hh_mm_ssZ, um nome de objeto de exemplo é prod_2023-09-25/04_10_00Z_uNiQuE_archive.
- Se o formato de data/hora do nome do ficheiro terminar num caráter que não seja um correspondente, esse caráter substitui o separador entre <UTC-date-time> e <uuid>. Por exemplo, se o valor do formato de data/hora do nome do ficheiro for YYYY-MM-DDThh_mm_ss-, um nome de objeto de exemplo é prod_2023-09-25T04_10_00-uNiQuE_archive.

Criação de lotes de ficheiros

As subscrições do Cloud Storage permitem-lhe decidir quando quer criar um novo ficheiro de saída que é armazenado como um objeto no contentor do Cloud Storage. O Pub/Sub escreve um ficheiro de saída quando uma das condições de processamento em lote especificadas é cumprida. Seguem-se as condições de processamento em lote do Cloud Storage:

Duração máxima do lote de armazenamento. Esta é uma definição obrigatória. A subscrição do Cloud Storage escreve um novo ficheiro de saída se o valor especificado da duração máxima for excedido. Se não especificar o valor, é aplicado um valor predefinido de 5 minutos. Seguem-se os valores aplicáveis para a duração máxima:
- Valor mínimo = 1 minuto
- Valor predefinido = 5 minutos
- Valor máximo = 10 minutos
Storage batch max bytes. Esta é uma definição opcional. A subscrição do Cloud Storage escreve um novo ficheiro de saída se o valor especificado de bytes máximos for excedido. Seguem-se os valores aplicáveis para o número máximo de bytes:
- Valor mínimo = 1 KB
- Valor máximo = 10 GiB
Storage batch max messages. Esta é uma definição opcional. A subscrição do Cloud Storage escreve um novo ficheiro de saída se o número especificado de mensagens máximas for excedido. Seguem-se os valores aplicáveis para o número máximo de mensagens:
- Valor mínimo = 1000

Por exemplo, pode configurar a duração máxima como 6 minutos e o tamanho máximo como 2 GB. Se, ao 4.º minuto, o ficheiro de saída atingir um tamanho de 2 GB, o Pub/Sub finaliza o ficheiro anterior e começa a escrever num novo ficheiro.

Uma subscrição do Cloud Storage pode escrever em vários ficheiros num contentor do Cloud Storage em simultâneo. Se tiver configurado a sua subscrição para criar um novo ficheiro a cada 6 minutos, pode observar a criação de vários ficheiros do Cloud Storage a cada 6 minutos.

Em algumas situações, o Pub/Sub pode começar a escrever num novo ficheiro antes da hora configurada pelas condições de processamento em lote de ficheiros. Um ficheiro também pode exceder o valor de bytes máximo se a subscrição receber mensagens maiores do que o valor de bytes máximo.

Formato de ficheiro

Quando cria uma subscrição do Cloud Storage, pode especificar o formato dos ficheiros de saída que vão ser armazenados num contentor do Cloud Storage como Texto ou Avro.

Texto: as mensagens são armazenadas como texto simples. Um caráter de nova linha separa uma mensagem da mensagem anterior no ficheiro. Apenas os payloads das mensagens são armazenados, não os atributos nem outros metadados.
Avro: as mensagens são armazenadas no formato binário Apache Avro. Quando seleciona Avro, pode ativar as seguintes propriedades adicionais:
- Escrever metadados: esta opção permite-lhe armazenar os metadados da mensagem juntamente com a mensagem. Os metadados, como os campos subscription_name, message_id, publish_time e attributes, são escritos em campos de nível superior no objeto Avro de saída, enquanto todas as outras propriedades de mensagens que não sejam dados (por exemplo, uma ordering_key, se presente) são adicionadas como entradas no mapa attributes.
  
  Se a opção Escrever metadados estiver desativada, apenas a carga útil da mensagem é escrita no objeto Avro de saída. Segue-se o esquema Avro para as mensagens de saída com a opção write metadata desativada:
```
{
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessage",
  "fields": [
    { "name": "data", "type": "bytes" }
  ]
}
```
  Segue-se o esquema Avro para as mensagens de saída com a opção write metadata ativada:
```
{
  "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 do tópico: esta opção permite que o Pub/Sub use o esquema do tópico do Pub/Sub ao qual a subscrição está anexada ao escrever ficheiros Avro.
  
  Quando usar esta opção, lembre-se de verificar os seguintes requisitos adicionais:
  - O esquema do tópico tem de estar no formato Apache Avro.
  - Se as opções usar esquema de tópicos e escrever metadados estiverem ativadas, o esquema de tópicos tem de ter um objeto Record na raiz. O Pub/Sub expande a lista de campos do registo para incluir os campos de metadados. Como resultado, o registo não pode conter campos com o mesmo nome que os campos de metadados (subscription_name, message_id, publish_time ou attributes).

Conta de serviço

Tem as seguintes opções para escrever mensagens numa tabela do BigQuery ou num contentor do Cloud Storage:

Configure uma conta de serviço personalizada para que apenas os utilizadores que tenham a autorização iam.serviceAccounts.actAs na conta de serviço possam criar uma subscrição que escreva na tabela ou no contentor. Um exemplo de função que inclui a autorização iam.serviceAccounts.actAs é a função utilizador da conta de serviço (roles/iam.serviceAccountUser).
Use o agente de serviço do Pub/Sub predefinido que permite a qualquer utilizador com a capacidade de criar subscrições no projeto criar uma subscrição que escreve na tabela ou no contentor. O agente do serviço Pub/Sub é a predefinição quando não especifica uma conta de serviço personalizada.