Criar uma inscrição para receber eventos

Um registro identifica uma assinatura de um barramento específico. A inscrição define os critérios de correspondência que determinam quais mensagens são encaminhadas para um destino. Ele também especifica o pipeline pelo qual as mensagens correspondentes devem ser roteadas. Um pipeline permite configurar um destino de destino e também oferece a opção de transformar os eventos correspondentes antes de enviá-los ao destino.

Observe o seguinte:

  • Um pipeline e uma inscrição precisam estar no mesmo projeto do Google Cloud. O bus pode estar no mesmo projeto ou em um projeto diferente.
  • Um pipeline pode ser usado para várias inscrições.
  • Apenas um destino pode ser o destino das mensagens roteadas por um pipeline.
  • Antes de configurar um pipeline ou uma inscrição, você precisa ter criado um bus avançado do Eventarc.

Funções exigidas

Uma função do Identity and Access Management (IAM) contém um conjunto de permissões que permite realizar ações específicas nos recursos do Google Cloud. Os papéis e as permissões a seguir são necessários ao criar um pipeline e uma inscrição para encaminhar mensagens:

  • Para receber a permissão necessária para criar um pipeline, peça ao administrador para conceder a você o papel do IAM de desenvolvedor do Eventarc (roles/eventarc.developer) no seu projeto de pipeline. Esse papel predefinido contém a permissão eventarc.pipelines.create, que é necessária para criar um pipeline.
  • Para receber a permissão necessária para criar uma inscrição, peça ao administrador para conceder a você o papel do IAM de desenvolvedor do Eventarc (roles/eventarc.developer) no projeto de inscrição. Esse papel predefinido contém a permissão eventarc.enrollments.create, que é necessária para criar uma inscrição.
  • Para receber a permissão necessária para usar um bus, peça ao administrador para conceder a você o papel do IAM de Usuário da bus de mensagens do Eventarc (roles/eventarc.messageBusUser) no projeto da bus. Esse papel predefinido contém a permissão eventarc.buses.use, que é necessária para usar um barramento.

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso. Também é possível conseguir essas permissões com papéis personalizados ou outros papéis predefinidos.

Inscrever-se para receber eventos

É possível criar um pipeline e uma inscrição no console do Google Cloud ou usando a Google Cloud CLI.

Console

No console do Google Cloud, é possível criar o pipeline e a inscrição ao mesmo tempo na página Pipelines.

  1. Para criar uma inscrição, acesse a página Eventarc > Pipelines no console do Google Cloud.

    Acessar "Pipelines"

  2. Clique em Criar pipeline.

  3. No painel Detalhes do pipeline, faça o seguinte:

    1. Insira um Nome do pipeline. Esse é o ID do seu pipeline.
    2. Na lista Região, selecione uma região para implantar o pipeline. O pipeline precisa ser criado na mesma região do barramento. Para mais informações, consulte Locais avançados do Eventarc.
    3. Opcional: é possível modificar a configuração padrão para tentar novamente os eventos.
    4. Em Criptografia, aceite a chave de criptografia gerenciada pelo Google padrão ou selecione Chave do Cloud KMS. Para mais informações, consulte Usar chaves de criptografia gerenciadas pelo cliente (CMEK).

    5. Se você selecionar Chave do Cloud KMS, faça o seguinte:

      1. Na lista Tipo de chave, selecione um método para gerenciar as chaves.

        Você pode gerenciar as chaves manualmente ou usar o Autokey, que permite gerar chaves e chaveiros sob demanda. Se a opção Autokey estiver desativada, ela ainda não estará integrada ao tipo de recurso atual.

      2. Em Selecionar uma chave gerenciada pelo cliente, selecione uma chave.

        É necessário selecionar uma região para visualizar as chaves gerenciadas pelo cliente.

      3. Opcional: para inserir manualmente o nome do recurso da chave, na lista Selecionar uma chave gerenciada pelo cliente, clique em Inserir chave manualmente e insira o nome da chave no formato especificado.

      4. Se solicitado, conceda o papel cloudkms.cryptoKeyEncrypterDecrypter ao Agente de serviço do Eventarc.

    6. Opcional: para adicionar rótulos, clique em Adicionar rótulo. Os rótulos são pares de chave-valor que ajudam você a organizar seus recursos do Google Cloud. Para mais informações, consulte O que são rótulos?

    7. Clique em Continuar.

  4. No painel Matrículas, faça o seguinte:

    1. Clique em Adicionar uma inscrição.
    2. Insira um nome de inscrição.
    3. Na lista Ônibus, selecione um ônibus para assinar.

    4. No campo Expressão CEL, escreva uma expressão de avaliação usando CEL. Exemplo:

      message.type == "google.cloud.dataflow.job.v1beta3.statusChanged"

      A expressão padrão, true, indica que todas as mensagens são roteadas sem filtros.

    5. Clique em Concluído.

    6. Você pode adicionar outra inscrição ou clicar em Continuar.

  5. Opcional: no painel Mediação de eventos, faça o seguinte ou clique em Continuar:

    1. Marque a caixa de seleção Aplicar uma transformação.

    2. Na lista Formato de entrada, selecione o formato aplicável.

      Ao aplicar uma transformação, é necessário especificar um formato de dados de entrada para um pipeline e todos os eventos precisam corresponder a esse formato.

    3. Para formatos Avro ou Protobuf, é necessário especificar um esquema de entrada. Se preferir, faça upload de um esquema de entrada. Para mais informações, consulte Formatar eventos recebidos.

    4. No campo Expressão CEL, escreva uma expressão de transformação usando CEL.

    5. Clique em Continuar.

  6. No painel Destino, faça o seguinte:

    1. Na lista Tipo de destino, selecione um tipo de destino para encaminhar mensagens. Dependendo do tipo de destino, faça o seguinte:

    2. Especifique um anexo de rede.

      Um anexo de rede é um recurso que permite que uma rede VPC do produtor inicie conexões com uma rede VPC do consumidor. Para publicar eventos, o Eventarc Advanced usa o anexo de rede para estabelecer uma conexão com o endpoint hospedado em uma rede VPC.

      É possível criar um anexo de rede que aceite automaticamente conexões de qualquer interface do Private Service Connect que se refira ao anexo de rede. Crie o anexo de rede na mesma rede e região que contém o endpoint de destino.

      Se você estiver encaminhando mensagens para um destino do Google usando um endereço DNS, como o Cloud Run, o Pub/Sub, Workflows ou outro bus avançado do Eventarc, verifique se o Acesso privado do Google está ativado na sub-rede usada no anexo de rede. Caso contrário, não será possível resolver o endereço DNS.

    3. Se aplicável, selecione um formato na lista Formato de saída.

      Se um formato de dados de entrada não for especificado para um pipeline, não será possível definir um formato de saída.

    4. Se aplicável, aplique uma Vinculação de mensagem. Para mais informações, consulte Definir uma vinculação de mensagem.

    5. Para ativar a autenticação, marque a caixa de seleção Ativar autenticação.

      1. Na lista Auth header, selecione o tipo de token a ser gerado e anexe como um cabeçalho Authorization na solicitação HTTP:

        • Um token OAuth geralmente é usado apenas ao chamar APIs do Google hospedadas em *.googleapis.com. Como alternativa, especifique o escopo desse token. Caso contrário, o padrão será https://www.googleapis.com/auth/cloud-platform. Para serviços do Google Cloud, é uma prática recomendada usar o escopo https://www.googleapis.com/auth/cloud-platform, que inclui todas as APIs do Google Cloud, além de Identity and Access Management (IAM), que fornece controle de acesso refinado.

          Todas as solicitações para outro bus avançado do Eventarc, Pub/Sub ou Workflows precisam ter um cabeçalho de autorização HTTP com um token OAuth assinado pelo Google para uma das contas de serviço autorizadas.

        • Um token OIDC pode ser usado em vários cenários, incluindo endpoints em que você pretende validar o token. Além disso, especifique o público-alvo desse token. Em geral, ele precisa corresponder ao URL do pipeline de destino. Se não for especificado, o URL inteiro será usado, incluindo todos os parâmetros de solicitação.

          O Cloud Run executa uma verificação do IAM em cada solicitação, e você pode usar a permissão run.routes.invoke para configurar quem pode acessar seu serviço do Cloud Run das seguintes maneiras:

          • Conceda a permissão para selecionar contas de serviço ou grupos para permitir o acesso ao serviço. Todas as solicitações precisam ter um cabeçalho de autorização HTTP com um token do OpenID Connect assinado pelo Google para uma das contas de serviço autorizadas.

          • Conceda a permissão a allUsers para permitir o acesso não autenticado.

          Para mais informações, consulte Controle de acesso do Cloud Run.

        Saiba mais sobre os tipos de token.

      2. Na lista Conta de serviço, selecione a conta de serviço que vai invocar o serviço de destino. ou crie uma nova conta de serviço.

        Ele especifica o e-mail da conta de serviço do IAM associado ao pipeline e ao qual você concedeu papéis específicos exigidos pelo Eventarc Advanced.

  7. Clique em Criar.

gcloud

Ao usar a CLI gcloud, primeiro crie o pipeline e, em seguida, crie a inscrição usando os comandos apropriados.

Pipeline

  1. Abra um terminal.

  2. Crie um pipeline usando o comando gcloud beta eventarc pipelines create:

    gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=DESTINATION_KEY \
    --location=REGION

    Substitua:

    • PIPELINE_NAME: o ID do pipeline ou um nome totalmente qualificado

    • DESTINATION_KEY: um ou mais pares de chave-valor para configurar um destino para o pipeline

      É necessário definir apenas uma das seguintes chaves:

      É necessário definir a seguinte chave:

      • network_attachment: um recurso que permite que uma rede VPC de produtor inicie conexões com uma rede VPC de consumidor. Para publicar eventos, o Eventarc Advanced usa o anexo de rede para estabelecer uma conexão com o endpoint hospedado em uma rede VPC.

        É possível criar um anexo de rede que aceite automaticamente conexões de qualquer interface do Private Service Connect que se refira ao anexo de rede. Crie o anexo de rede na mesma rede e região que contém o recurso de destino.

        Se você estiver roteando mensagens para um destino do Google usando um endereço DNS, como o Cloud Run, o Pub/Sub, o Workflows ou outro bus do Eventarc Advanced, verifique se o Acesso privado do Google está ativado na sub-rede usada no anexo de rede. Caso contrário, não será possível resolver o endereço DNS.

      Para ativar a autenticação, defina uma das seguintes chaves:

      • google_oidc_authentication_service_account: o e-mail da conta de serviço usado para gerar um token OIDC, que pode ser usado em vários cenários, incluindo endpoints em que você pretende validar o token. Opcionalmente, é possível definir google_oidc_authentication_audience para especificar o público-alvo desse token. Geralmente, ele precisa corresponder ao URL do pipeline de destino. Se não for especificado, o URL inteiro será usado, incluindo todos os parâmetros de solicitação.

        O Cloud Run executa uma verificação do IAM em cada solicitação, e você pode usar a permissão run.routes.invoke para configurar quem pode acessar seu serviço do Cloud Run das seguintes maneiras:

        • Conceda a permissão para selecionar contas de serviço ou grupos para permitir o acesso ao serviço. Todas as solicitações precisam ter um cabeçalho de autorização HTTP com um token do OpenID Connect assinado pelo Google para uma das contas de serviço autorizadas.

        • Conceda a permissão a allUsers para permitir o acesso não autenticado.

        Para mais informações, consulte Controle de acesso do Cloud Run .

      • oauth_token_authentication_service_account: o e-mail da conta de serviço usado para gerar um token OAuth, que geralmente só é usado ao chamar APIs do Google hospedadas em *.googleapis.com. Também é possível definir oauth_token_authentication_scope para especificar o escopo desse token. Caso contrário, o padrão será https://www.googleapis.com/auth/cloud-platform. Para serviços do Google Cloud, é uma prática recomendada usar o escopo https://www.googleapis.com/auth/cloud-platform, que inclui todas as APIs do Google Cloud, além de Identity and Access Management (IAM), que fornece controle de acesso refinado.

        Todas as solicitações para outro bus avançado do Eventarc, Pub/Sub ou Workflows precisam ter um cabeçalho de autorização HTTP com um token OAuth assinado pelo Google para uma das contas de serviço autorizadas.

        Saiba mais sobre os tipos de token.

      Opcional: é possível definir uma das seguintes chaves:

      • output_payload_format_avro_schema_definition
      • output_payload_format_json

      • output_payload_format_protobuf_schema_definition

        Se você definir um formato de saída, também precisará especificar um formato de entrada (consulte as flags input-payload-format-* abaixo).

      Opcional: se http_endpoint_uri não for usado como uma chave de destino, defina as seguintes chaves:

      • project: o ID do projeto do Google Cloud do recurso de destino. Por padrão, o ID do projeto do pipeline é usado.
      • location: o local do recurso de destino. Por padrão, o local do pipeline é usado.

    • REGION: um local do Eventarc Advanced compatível.

      Como alternativa, defina a propriedade de local da CLI gcloud:

      gcloud config set eventarc/location REGION

    Opcional: é possível usar as seguintes flags:

    • --async para retornar do comando imediatamente, sem aguardar a conclusão da operação em andamento.
    • --crypto-key para especificar o nome totalmente qualificado de uma chave de criptografia gerenciada pelo cliente. Se não for especificado, chaves gerenciadas pelo Google serão usadas.
    • --logging-config para configurar o nível de registro, que precisa ser um destes: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

    • --mediations para aplicar uma transformação. transformation_template é o único modelo aceito, e apenas uma mediação por pipeline é aceita. Por exemplo:

      --mediations=transformation_template='message.removeFields(["id\ ","credit_card_number","age"])'

      Se você estiver aplicando uma transformação, é necessário usar uma das flags a seguir para especificar um formato de entrada.

    • Uma das seguintes opções para especificar um formato de entrada:

      • --input-payload-format-avro-schema-definition
      • --input-payload-format-json
      • --input-payload-format-protobuf-schema-definition

    • --max-retry-attempts, --max-retry-delay e --min-retry-delay para tentar novamente

    Exemplo:

    gcloud beta eventarc pipelines create my-pipeline \
    --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment,oauth_token_authentication_service_account=example-service-account@example-project.gserviceaccount.iam.com,oauth_token_authentication_scope='https://www.googleapis.com/auth/cloud-platform',output_payload_format_avro_schema_definition='{"type": "record","name": "my_record", "fields": [{"name": "my_field", "type":"string"}]}' \
    --input-payload-format-avro-schema-definition='{"type":"record", "name": "my_record", "fields": [{"name": "my_field","type": "string"}]}' \
    --location=us-central1 \
    --async

    Para mais detalhes e exemplos, consulte a documentação da CLI gcloud.

Registro

  1. Abra um terminal.

  2. Crie uma inscrição usando o comando gcloud beta eventarc enrollments create:

    gcloud beta eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=REGION

    Substitua:

    • ENROLLMENT_NAME: o ID da inscrição ou um nome totalmente qualificado.
    • MATCH_EXPRESSION: a expressão correspondente para essa inscrição usando CEL, por exemplo, "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'"
    • PIPELINE_NAME: o ID do pipeline de destino ou o nome totalmente qualificado para essa inscrição
    • BUS_NAME: o ID do bus avançado do Eventarc ou o nome totalmente qualificado dele.
    • PROJECT_ID: o ID do projeto do Google Cloud para o bus.

    • REGION: um local do Eventarc Advanced compatível.

      Como alternativa, defina a propriedade de local da CLI gcloud:

      gcloud config set eventarc/location REGION

    Opcional: use a flag a seguir:

    • --async para retornar do comando imediatamente, sem aguardar a conclusão da operação em andamento.

    Exemplo:

    gcloud beta eventarc enrollments create my-enrollment \
    --cel-match="message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'" \
    --destination-pipeline=my-pipeline \
    --message-bus=my-message-bus \
    --message-bus-project=another-google-cloud-project \
    --location=us-central1 \
    --async

Excluir uma inscrição

É possível excluir uma inscrição no console do Google Cloud ou usando a Google Cloud CLI.

Console

  1. Para excluir uma inscrição, no console do Google Cloud, acesse a página Eventarc > Pipelines.

    Acessar "Pipelines"

  2. Clique no nome do pipeline de onde você quer excluir a inscrição.

    O painel Detalhes do pipeline é aberto.

  3. Clique em Continuar.

    O painel Matrículas é aberto.

  4. Para a matrícula que você quer excluir, clique no ícone de exclusão .

  5. Clique em Salvar.

gcloud

  1. Abra um terminal.

  2. Exclua uma inscrição usando o comando gcloud beta eventarc enrollments delete:

    gcloud beta eventarc enrollments delete ENROLLMENT_NAME \
      --location=REGION

    Substitua:

Excluir um pipeline

É possível excluir um pipeline no console do Google Cloud ou usando a Google Cloud CLI.

A exclusão de um pipeline pode levar mais de 10 minutos.

Console

  1. Para excluir um pipeline, no console do Google Cloud, acesse a página Eventarc > Pipelines.

    Acessar "Pipelines"

  2. Na lista de pipelines, marque a caixa de seleção ao lado do nome do pipeline que você quer excluir.

  3. Clique em Excluir.

  4. Digite Delete para confirmar a exclusão.

  5. Clique em Excluir.

gcloud

  1. Abra um terminal.

  2. Exclua um pipeline usando o comando gcloud beta eventarc pipelines delete:

    gcloud beta eventarc pipelines delete PIPELINE_NAME \
      --location=REGION

    Substitua:

A seguir