Crie subscrições do Cloud Storage

Este documento descreve como criar uma subscrição do Cloud Storage. Pode usar a Trusted Cloud consola, a CLI do Google Cloud, a biblioteca cliente ou a API Pub/Sub para criar uma subscrição do Cloud Storage.

Antes de começar

Antes de ler este documento, certifique-se de que conhece o seguinte:

Funções e autorizações necessárias

Segue-se uma lista de diretrizes relativas a funções e autorizações:

  • Para criar uma subscrição, tem de configurar o controlo de acesso ao nível do projeto.

  • Também precisa de autorizações ao nível do recurso se as suas subscrições e tópicos estiverem em projetos diferentes, conforme abordado mais adiante nesta secção.

  • Para criar uma subscrição do Cloud Storage, o agente do serviço Pub/Sub ou uma conta de serviço personalizada tem de ter autorização para escrever no contentor do Cloud Storage específico e para ler os metadados do contentor. Para mais informações sobre como conceder estas autorizações, consulte a secção seguinte deste documento.

Para receber as autorizações de que precisa para criar subscrições do Cloud Storage, peça ao seu administrador para lhe conceder a função de IAM Editor do Pub/Sub (roles/pubsub.editor) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para criar subscrições do Cloud Storage. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para criar subscrições do Cloud Storage:

  • Crie uma subscrição: pubsub.subscriptions.create
  • Anexe uma subscrição a um tópico: pubsub.topics.attachSubscription
  • Extrair de uma subscrição: pubsub.subscriptions.consume
  • Obtenha uma subscrição: pubsub.subscriptions.get
  • Anuncie uma subscrição: pubsub.subscriptions.list
  • Atualize uma subscrição: pubsub.subscriptions.update
  • Elimine uma subscrição: pubsub.subscriptions.delete
  • Obtenha a Política IAM para uma subscrição: pubsub.subscriptions.getIamPolicy
  • Configure a política IAM para uma subscrição: pubsub.subscriptions.setIamPolicy

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Para permitir que um principal num projeto crie uma subscrição do Cloud Storage noutro projeto, tem de conceder a esse principal a função de Editor do Pub/Sub (roles/pubsub.editor) em ambos os projetos. Isto concede as autorizações necessárias para criar a nova subscrição e anexá-la ao tópico original. Trusted Cloud A função Editor do Pub/Sub (roles/pubsub.editor) no tópico também ajuda a anexar subscrições num projeto diferente ao tópico. Trusted Cloud

Atribua funções a contas de serviço

Alguns Trusted Cloud by S3NS serviços têm Trusted Cloudcontas de serviço geridas que permitem que os serviços acedam aos seus recursos. Estas contas de serviço são conhecidas como agentes de serviço. O Pub/Sub cria e mantém um agente de serviço para cada projeto no formato service-project-number@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com.

Pode escolher entre permitir que o agente de serviço do Pub/Sub ou uma conta de serviço personalizada escrevam no contentor do Cloud Storage.

A concessão de autorização ao agente do serviço Pub/Sub significa que qualquer utilizador que tenha autorização para criar uma subscrição no seu projeto pode escrever no contentor do Cloud Storage. Se quiser fornecer uma autorização mais detalhada para escrever no contentor do Cloud Storage, configure uma conta de serviço personalizada.

Para mais informações sobre o IAM do Cloud Storage, consulte o artigo Cloud Storage Identity and Access Management.

Atribua funções do Cloud Storage ao agente do serviço Pub/Sub

Se quiser criar uma subscrição do Cloud Storage através do agente de serviço do Pub/Sub, este tem de ter autorização para escrever no contentor do Cloud Storage específico e para ler os metadados do contentor.

Conceda as funções Storage Object Creator (roles/storage.objectCreator) e Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) ao agente de serviço do Pub/Sub. Conceda a autorização no contentor individual.

Grupo

  1. Na Trusted Cloud consola, aceda à página Cloud Storage.

    Aceda ao Cloud Storage

  2. Clique no contentor do Cloud Storage para o qual quer escrever mensagens.

    É apresentada a página Detalhes do contentor.

  3. Na página Detalhes do contentor, clique no separador Autorizações.

  4. No separador Autorizações > Ver por responsáveis, clique em Conceder acesso.

    É aberta a página Conceder acesso.

  5. Na secção Adicionar responsáveis, introduza o nome do agente do serviço Pub/Sub para o projeto que contém a subscrição.

    O formato do agente do serviço é service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com. Por exemplo, para um projeto com PROJECT_NUMBER=112233445566, o agente de serviço tem o formato service-112233445566@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com.

  6. No menu pendente Atribuir funções > Selecionar uma função, introduza Creator e selecione a função Criador de objetos de armazenamento.

  7. Clique em Adicionar outra função.

  8. No menu pendente Selecionar uma função, introduza Bucket Reader e selecione a função Leitor de contentores antigos de armazenamento.

  9. Clique em Guardar.

Projeto

  1. Na Trusted Cloud consola, aceda à página IAM.

    Aceda ao IAM

  2. No separador Autorizações > Ver por responsáveis, clique em Conceder acesso.

    É aberta a página Conceder acesso.

  3. Na secção Adicionar responsáveis, introduza o nome do agente do serviço Pub/Sub.

    O formato do agente do serviço é service-PROJECT_NUMBER@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com. Por exemplo, para um projeto com PROJECT_NUMBER=112233445566, o agente de serviço tem o formato service-112233445566@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com.

  4. No menu pendente Atribuir funções > Selecionar uma função, introduza Storage Admin e selecione a função Administrador de armazenamento.

  5. Clique em Guardar.

Atribua funções do Cloud Storage a uma conta de serviço personalizada

Se quiser usar uma conta de serviço personalizada para escrever num contentor do Cloud Storage, tem de definir as seguintes autorizações:

  • A conta de serviço personalizada tem de ter autorização para escrever no contentor do Cloud Storage específico e para ler os metadados do contentor.
  • O agente do serviço Pub/Sub tem de ter a autorização iam.serviceAccounts.getAccessToken na conta de serviço personalizada.
  • O utilizador que cria a subscrição tem de ter iam.serviceAccounts.actAs autorização na conta de serviço personalizada.

Crie a conta de serviço e conceda autorizações com os seguintes passos:

  1. Crie a conta de serviço personalizada. A conta de serviço tem de estar no mesmo projeto que a subscrição.

  2. Conceda as funções Storage Object Creator (roles/storage.objectCreator) e Storage Legacy Bucket Reader (roles/storage.legacyBucketReader) à conta de serviço personalizada.

    Pode conceder autorização à conta de serviço numa única tabela no projeto ou em todas as tabelas do projeto. Para tal, consulte a secção adequada em Atribua Trusted Cloud funções ao agente do serviço Pub/Sub. No procedimento, substitua o endereço de email do agente do serviço Pub/Sub pelo endereço de email da conta de serviço personalizada.

  3. Conceda ao agente do serviço Pub/Sub a autorização iam.serviceAccounts.getAccessToken na conta de serviço personalizada ou em todas as contas de serviço no projeto. Pode conceder esta autorização atribuindo a função roles/iam.serviceAccountTokenCreator ao agente de serviço do Pub/Sub.

    Escolha o método adequado com base nos seus requisitos.

Conta de serviço

  1. Na Trusted Cloud consola, aceda à página Contas de serviço.

    Aceda a Contas de serviço

  2. Introduza o nome da conta de serviço personalizada no Filtro.

  3. Selecione a conta de serviço na lista.

  4. Clique em Principais com acesso.

  5. Clique em Conceder acesso.

  6. Na secção Adicionar responsáveis, introduza o nome do agente do serviço Pub/Sub para o projeto que contém a subscrição. O formato do agente do serviço é service-project-number@gcp-sa-pubsub.s3ns.iam.gserviceaccount.com. Por exemplo, para um projeto com project-number=112233445566, o agente de serviço tem o formato service-112233445566@gcp-sa-pubsub.s3ns.iam.gserviceaccount.com.

  7. No menu pendente Selecionar uma função, introduza Service Account, e selecione a função Criador de tokens de contas de serviços.

  8. Clique em Guardar.

Projeto

  1. Na Trusted Cloud consola, aceda à página IAM.

    Aceda ao IAM

  2. Clique em Conceder acesso.

  3. Na secção Adicionar membros, introduza o nome da sua conta de serviço personalizada.

  4. Na secção Atribuir funções, clique em Adicionar outra função.

  5. No menu pendente Selecionar uma função, introduza Service Account, e selecione a função Criador de tokens de contas de serviços.

  6. Clique em Guardar.

Se criou a conta de serviço personalizada, já deve ter a autorização iam.serviceAccounts.actAs necessária. Se precisar de conceder a outra pessoa a autorização na conta de serviço:

  1. Na Trusted Cloud consola, aceda à página Contas de serviço.

    Aceda a Contas de serviço

  2. Introduza o nome da conta de serviço personalizada no Filtro.

  3. Selecione a conta de serviço na lista.

  4. Clique em Principais com acesso.

  5. Clique em Conceder acesso.

  6. Na secção Adicionar responsáveis, introduza o nome da conta à qual quer conceder acesso.

  7. No menu pendente Selecionar uma função, introduza Service Account e selecione a função Utilizador da conta de serviço.

  8. Clique em Guardar.

Propriedades da subscrição do Cloud Storage

Quando configura uma subscrição do Cloud Storage, tem de especificar as propriedades comuns a todos os tipos de subscrição e algumas propriedades adicionais específicas da subscrição do Cloud Storage.

Propriedades comuns da subscrição

Saiba mais sobre as propriedades de subscrição comuns que pode definir em todas as subscrições.

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.

Crie uma subscrição do Cloud Storage

Consola

  1. Na Trusted Cloud consola, aceda à página Subscrições.

    Aceder a Subscrições

  2. Clique em Criar subscrição.

  3. No campo ID da subscrição, introduza um nome.

    Para obter informações sobre como atribuir um nome a uma subscrição, consulte as diretrizes para atribuir um nome a um tópico ou a uma subscrição.

  4. Escolha ou crie um tópico no menu pendente.

    A subscrição recebe mensagens do tópico.

    Para obter informações sobre como criar um tópico, consulte o artigo Crie e faça a gestão de tópicos.

  5. Selecione Tipo de fornecimento como Escrever para o Cloud Storage.

  6. Para o contentor do Cloud Storage, clique em Procurar.

    • Pode selecionar um contentor existente de qualquer projeto adequado.

    • Também pode clicar no ícone de criação e seguir as instruções no ecrã para criar um novo contentor.

      Depois de criar o contentor, selecione-o para a subscrição do Cloud Storage.

      Para mais informações sobre como criar um contentor, consulte o artigo Crie contentores.

    Quando especifica o contentor, o Pub/Sub verifica se existem as autorizações adequadas no contentor para o agente do serviço Pub/Sub. Se existirem problemas de autorizações, é apresentada uma mensagem semelhante à 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.

  7. Se tiver problemas de autorização, clique em Definir autorização e siga as instruções no ecrã.

    Em alternativa, siga as instruções em Atribua funções do Cloud Storage ao agente de serviço do Pub/Sub.

  8. Em Formato de ficheiro, selecione Texto ou Avro.

    Se selecionar Avro, também pode especificar opcionalmente se quer armazenar os metadados das mensagens 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 o formato de ficheiro.

  9. Opcional: pode especificar o prefixo, o sufixo e a data/hora do nome do ficheiro para todos os ficheiros que vão ser escritos no contentor do Cloud Storage. Um ficheiro é armazenado como um objeto no contentor.

    Para mais informações sobre como definir o prefixo, o sufixo e a data/hora do nome do ficheiro, consulte o artigo Prefixo, sufixo e data/hora do nome do ficheiro.

  10. Para o Processamento em lote de ficheiros, especifique um tempo máximo a decorrer antes de criar um novo ficheiro.

    Opcionalmente, também pode definir o tamanho máximo do ficheiro ou o número máximo de mensagens para os ficheiros.

    Para mais informações acerca das opções de processamento em lote de ficheiros, consulte o artigo Processamento em lote de ficheiros.

  11. Recomendamos vivamente que ative a Dead Lettering para processar falhas de mensagens.

    Para mais informações, consulte o artigo Tópico de mensagens não entregues.

  12. Pode manter as outras definições como predefinições e clicar em Criar.

gcloud

  1. In the Trusted Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Trusted 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.

  2. Para criar uma subscrição 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

    Se quiser usar uma conta de serviço personalizada, forneça-a como um argumento adicional:

    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
    --cloud-storage-service-account-email=SERVICE_ACCOUNT_NAME

    No comando, apenas SUBSCRIPTION_ID, a flag --topic e a flag --cloud-storage-bucket são obrigatórias. As restantes flags são opcionais e podem ser omitidas.

    Substitua o seguinte:

    • SUBSCRIPTION_ID: o nome ou o ID da sua nova subscrição do Cloud Storage.
    • TOPIC_ID: o nome ou o ID do seu tópico.
    • BUCKET_NAME: especifica o nome de um contentor existente. Por exemplo, prod_bucket. O nome do contentor não pode incluir o ID do projeto. Para criar um contentor, consulte o artigo Crie contentores.
    • CLOUD_STORAGE_FILE_PREFIX: especifica o prefixo do nome do ficheiro do Cloud Storage. Por exemplo, log_events_.
    • CLOUD_STORAGE_FILE_SUFFIX: especifica o sufixo do nome do ficheiro do Cloud Storage. Por exemplo, .txt.
    • CLOUD_STORAGE_FILE_DATETIME_FORMAT: Especifica o formato de data/hora para o nome do ficheiro do Cloud Storage. Por exemplo, YYYY-MM-DD/hh_mm_ssZ.
    • CLOUD_STORAGE_MAX_DURATION: a duração máxima que pode decorrer antes de ser criado um novo ficheiro do Cloud Storage. O valor tem de estar entre 1 m e 10 m. Por exemplo, 5m.
    • CLOUD_STORAGE_MAX_BYTES: o número máximo de bytes que podem ser escritos num ficheiro do Cloud Storage antes de ser criado um novo ficheiro. O valor tem de estar entre 1 KB e 10 GB. Por exemplo, 20MB.
    • CLOUD_STORAGE_MAX_MESSAGES: o número máximo de mensagens que podem ser escritas num ficheiro do Cloud Storage antes de ser criado um novo ficheiro. O valor tem de ser igual ou superior a 1000. Por exemplo, 100000.
    • CLOUD_STORAGE_OUTPUT_FORMAT: O formato de saída dos dados escritos no Cloud Storage. Os valores são os seguintes:
      • text: as mensagens são escritas como texto simples, separadas por uma nova linha.
      • avro: as mensagens são escritas como um binário Avro. --cloud-storage-write-metadata e --cloud-storage-use-topic-schema só afetam subscrições com o formato de saída avro.
    • SERVICE_ACCOUNT_NAME: especifica o nome da conta de serviço a usar para escrever no Cloud Storage.

    3. C++

    Antes de experimentar este exemplo, siga as C++instruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C++ Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& bucket) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

    C#

    Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API C# Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    
using Google.Cloud.PubSub.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateCloudStorageSubscriptionSample
{
    public Subscription CreateCloudStorageSubscription(string projectId, string topicId, string subscriptionId,
        string bucket, string filenamePrefix, string filenameSuffix, TimeSpan maxDuration)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            CloudStorageConfig = new CloudStorageConfig
            {
                Bucket = bucket,
                FilenamePrefix = filenamePrefix,
                FilenameSuffix = filenameSuffix,
                MaxDuration = Duration.FromTimeSpan(maxDuration)
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

    Go

    Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Go Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, topic, subscription, bucket string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// bucket := "my-bucket" // bucket must not have the gs:// prefix
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		CloudStorageConfig: &pubsubpb.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat: &pubsubpb.CloudStorageConfig_AvroConfig_{
				AvroConfig: &pubsubpb.CloudStorageConfig_AvroConfig{
					WriteMetadata: true,
				},
			},
			MaxDuration: durationpb.New(1 * time.Minute),
			MaxBytes:    1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create cloud storage sub: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

    Java

    Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Java Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

    Node.js

    Antes de experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName,
  subscriptionName,
  bucket,
  filenamePrefix,
  filenameSuffix,
  maxDuration,
) {
  const options = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

    Node.js

    Antes de experimentar este exemplo, siga as instruções de configuração do Node.js no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Node.js do Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    /**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
import {CreateSubscriptionOptions, PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName: string,
  subscriptionName: string,
  bucket: string,
  filenamePrefix: string,
  filenameSuffix: string,
  maxDuration: number,
) {
  const options: CreateSubscriptionOptions = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

    PHP

    Antes de experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API PHP Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub GCS subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $bucket The Cloud Storage bucket name without any prefix like "gs://".
 */
function create_cloud_storage_subscription($projectId, $topicName, $subscriptionName, $bucket)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = ['bucket' => $bucket];
    $subscription->create([
        'cloudStorageConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

    Python

    Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Pub/Sub com as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Pub/Sub.

    Para se autenticar no Pub/Sub, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

    Antes de executar exemplos de código, defina a variável GOOGLE_CLOUD_UNIVERSE_DOMAIN environment como s3nsapis.fr. 

    from google.cloud import pubsub_v1
from google.protobuf import duration_pb2

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bucket = "my-bucket"

filename_prefix = "log_events_"
filename_suffix = ".avro"
# Either CloudStorageConfig.AvroConfig or CloudStorageConfig.TextConfig
# defaults to TextConfig
avro_config = pubsub_v1.types.CloudStorageConfig.AvroConfig(write_metadata=True)

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)
max_duration = duration_pb2.Duration()
max_duration.FromSeconds(300)

cloudstorage_config = pubsub_v1.types.CloudStorageConfig(
    bucket=bucket,
    filename_prefix=filename_prefix,
    filename_suffix=filename_suffix,
    avro_config=avro_config,
    # Min 1 minutes, max 10 minutes
    max_duration=max_duration,
    # Min 1 KB, max 10 GiB
    max_bytes=10000000,
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "cloud_storage_config": cloudstorage_config,
        }
    )

print(f"CloudStorage subscription created: {subscription}.")
print(f"Bucket for subscription is: {bucket}")
print(f"Prefix is: {filename_prefix}")
print(f"Suffix is: {filename_suffix}")

Monitorize uma subscrição do Cloud Storage

O Cloud Monitoring fornece várias métricas para monitorizar subscrições.

Para ver uma lista de todas as métricas disponíveis relacionadas com o Pub/Sub e as respetivas descrições, consulte a documentação de monitorização do Pub/Sub.

Também pode monitorizar as subscrições no Pub/Sub.

O que se segue?