Criar uma inscrição para receber eventos

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=LOCATION

   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.

     Você precisa definir apenas uma das seguintes chaves:

     • http_endpoint_uri: um URI de destino. O host pode ser um endereço IP estático endereçável de uma rede de nuvem privada virtual (VPC) ou o nome do host interno do Sistema de Nomes de Domínio (DNS) de um serviço resolvível usando o Cloud DNS. Também é possível definir http_endpoint_message_binding_template para especificar uma vinculação de mensagem.

       É possível usar essa chave para segmentar uma função do Cloud Run, um job do Cloud Run ou um serviço do Cloud Run que vai receber eventos como solicitações HTTP POST.

     • message_bus: o ID de um barramento do Eventarc Advanced.

     • pubsub_topic: o ID de um tópico do Pub/Sub.

     • workflow: o ID de um fluxo de trabalho do Workflows.

     Para http_endpoint_uri apenas (incluindo URLs do Cloud Run), defina a seguinte chave:

     • network_attachment: um recurso que permite que uma rede VPC produtora inicie conexões com uma rede VPC consumidora. 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 encaminhando mensagens para um destino do Google usando um endereço DNS, por exemplo, o Cloud Run, 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 muitos cenários, incluindo endpoints em que você pretende validar o token por conta própria. Opcionalmente, você pode definir google_oidc_authentication_audience para especificar o público-alvo a que esse token se destina. Em geral, ele precisa corresponder ao URL do pipeline de destino. Se não for especificado, todo o URL será usado, incluindo 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 o serviço do Cloud Run de uma 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ó deve ser usado ao chamar APIs do Google hospedadas em *.googleapis.com. Se quiser, defina 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 doGoogle 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 do gerenciamento de identidade e acesso (IAM), que fornece controle de acesso refinado.

       Todos os pedidos para outro barramento do Eventarc Advanced, 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: você pode 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, especifique também um formato de entrada (consulte as flags input-payload-format-* a seguir).

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

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

   • LOCATION: uma região do Eventarc Advanced compatível

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

     gcloud config set eventarc/location LOCATION
     

   Opcional: você pode 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, Google-owned and managed keys serão usados.
   • --logging-config para configurar o nível de geração de registros, 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 compatível, 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, precisará 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 eventos de nova tentativa

   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=LOCATION

   Substitua:

   • ENROLLMENT_NAME: o ID da inscrição ou um nome totalmente qualificado
   • MATCH_EXPRESSION: a expressão de correspondência para esta 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 dele para esta inscrição.
   • BUS_NAME: o ID do barramento avançado do Eventarc ou o nome totalmente qualificado dele.
   • PROJECT_ID: o ID do projeto Google Cloud para o barramento

   • LOCATION: uma região do Eventarc Advanced compatível

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

     gcloud config set eventarc/location LOCATION
     

   Opcional: você pode usar a seguinte flag:

   • --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
   

Pipeline

Para criar um pipeline, use o método projects.locations.pipelines.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• name: o nome completo do recurso do pipeline no formato projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME

  Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud do pipeline
  • LOCATION: a região em que o pipeline será implantado, por exemplo, us-central1.
  • PIPELINE_NAME: o nome do pipeline
• LABEL_KEY e LABEL_VALUE: opcional. Um mapa de pares de chave e valor de rótulo que ajudam a organizar seus recursos do Google Cloud . Para mais informações, consulte O que são rótulos?
• ANNOTATION_KEY e ANNOTATION_VALUE: opcional. Um mapa de pares de chave e valor de anotação de texto em formato livre. É possível usá-las para anexar informações arbitrárias associadas ao recurso. Para mais informações, consulte Anotações.
• LOG_SEVERITY: opcional. A gravidade mínima do evento descrito em uma entrada de registro. Uma destas opções: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. O padrão é NONE. Para mais informações, consulte LogSeverity.
• destinations: o destino para onde as mensagens serão encaminhadas. Apenas um destino é aceito: httpEndpoint, messageBus, topic ou workflow. Para mais informações, consulte o destino Destination. Por exemplo, substitua o seguinte:
  • HTTP_URI: um URI de destino. O host pode ser um endereço IP estático endereçável de uma rede de nuvem privada virtual (VPC) ou o nome de host interno do sistema de nomes de domínio (DNS) de um serviço resolvível usando o Cloud DNS. Também é possível definir messageBindingTemplate para especificar uma vinculação de mensagem.
  • networkAttachment: aplicável somente a httpEndpoint (incluindo URLs do Cloud Run). O nome completo do recurso de um anexo de rede neste formato: projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION /networkAttachments/NETWORK_ATTACHMENT_NAME. Um anexo de rede é um recurso que permite que uma rede de nuvem privada virtual do produtor inicie conexões com uma rede VPC do consumidor e precisa ser especificado. 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, por exemplo, o Cloud Run, 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.

  • SERVICE_ACCOUNT_EMAIL: o nome do e-mail da conta de serviço usado para gerar um token OIDC que pode ser usado em muitos cenários, incluindo endpoints em que você pretende validar o token por conta própria. Opcionalmente, você pode definir audience para especificar o público-alvo a que esse token se destina. Em geral, ele precisa corresponder ao URL do pipeline de destino. Se não for especificado, todo o URL será usado, incluindo os parâmetros de solicitação.

    Como alternativa, use oauthToken para especificar o e-mail da conta de serviço usado para gerar um token OAuth, que geralmente deve ser usado apenas ao chamar APIs do Google hospedadas em *.googleapis.com. Também é possível definir 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 do gerenciamento de identidade e acesso (IAM), que fornece controle de acesso refinado.

    Todas as solicitações para outro barramento do Eventarc Advanced, 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.

Corpo JSON da solicitação:

{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}

Para enviar a solicitação, expanda uma destas opções:

cat > request.json << 'EOF'
{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}
EOF

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelines?pipeline_id=PIPELINE_NAME"

@'
{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}
'@  | Out-File -FilePath request.json -Encoding utf8

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelines?pipeline_id=PIPELINE_NAME" | Select-Object -Expand Content

Se houver êxito, o corpo da resposta conterá uma instância de Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Registro

Para criar uma inscrição, use o método projects.locations.enrollments.create.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

• ENROLLMENT_NAME: o nome de exibição da sua inscrição, por exemplo, my_enrollment.
• MATCH_EXPRESSION: uma expressão CEL que identifica a quais mensagens essa inscrição se aplica. Por exemplo, message.type == 'hello-world-type'.
• destination: o nome completo do recurso do pipeline de destino no formato projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME.

  Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud do pipeline
  • LOCATION: a região em que o pipeline é implantado, por exemplo, us-central1.
  • PIPELINE_NAME: o nome do pipeline
• message_bus: o nome completo do recurso do barramento que identifica a origem das mensagens no formato projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME.

  Substitua:

  • BUS_PROJECT_ID: o Google Cloud ID do projeto de ônibus
  • BUS_LOCATION: a região em que o barramento é implantado, por exemplo, us-central1.
  • BUS_NAME: o nome do barramento de mensagens

Corpo JSON da solicitação:

{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}

Para enviar a solicitação, expanda uma destas opções:

cat > request.json << 'EOF'
{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}
EOF

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/enrollments?enrollment_id=ENROLLMENT_NAME"

@'
{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/enrollments?enrollment_id=ENROLLMENT_NAME" | Select-Object -Expand Content

Se houver êxito, o corpo da resposta conterá uma instância de Operation:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/enrollments/ENROLLMENT_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}