Creare una registrazione per ricevere eventi

Pipeline

1. Apri un terminale.

2. Crea una pipeline utilizzando il comando gcloud beta eventarc pipelines create:

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

   Sostituisci quanto segue:

   • PIPELINE_NAME: l'ID della pipeline o un nome completo

   • DESTINATION_KEY: una o più coppie chiave-valore per configurare una destinazione per la pipeline

     Devi impostare una sola delle seguenti chiavi:

     • http_endpoint_uri: un URI di destinazione. L'host può essere un indirizzo IP statico indirizzabile da una rete Virtual Private Cloud (VPC) o il nome host Domain Name System (DNS) interno di un servizio risolvibile utilizzando Cloud DNS. Se vuoi, puoi anche impostare http_endpoint_message_binding_template per specificare un binding del messaggio.

       Tieni presente che puoi utilizzare questa chiave per scegliere come target una funzione Cloud Run, un job Cloud Run o un servizio Cloud Run che riceverà eventi come richieste HTTP POST.

     • message_bus: l'ID di un bus Eventarc Advanced.

     • pubsub_topic: l'ID di un argomento Pub/Sub.

     • workflow: l'ID di un workflow di Workflows.

     Solo per http_endpoint_uri (inclusi gli URL Cloud Run), devi impostare la seguente chiave:

     • network_attachment: una risorsa che consente a una rete VPC producer di avviare connessioni a una rete VPC consumer. Per pubblicare eventi, Eventarc Advanced utilizza il collegamento di rete per stabilire una connessione all'endpoint ospitato in una rete VPC.

       Puoi creare un collegamento di rete che accetta automaticamente le connessioni da qualsiasi interfaccia Private Service Connect che fa riferimento al collegamento di rete. Crea l'allegato di rete nella stessa rete e nella stessa regione contenente la risorsa di destinazione.

       Se indirizzi i messaggi a una destinazione Google utilizzando un indirizzo DNS, ad esempio Cloud Run, assicurati che l'accesso privato Google sia abilitato nella subnet utilizzata nell'allegato di rete; in caso contrario, l'indirizzo DNS non può essere risolto.

     Per abilitare l'autenticazione, puoi impostare una delle seguenti chiavi:

     • google_oidc_authentication_service_account: l'email dell'account di servizio utilizzata per generare un token OIDC che può essere utilizzato per molti scenari, inclusi gli endpoint in cui intendi convalidare il token personalmente. Se vuoi, puoi impostare google_oidc_authentication_audience per specificare il pubblico a cui è destinato questo token. In genere, deve corrispondere all'URL della pipeline di destinazione. Se non specificato, viene utilizzato l'intero URL, inclusi eventuali parametri della richiesta.

       Tieni presente che Cloud Run esegue un controllo IAM su ogni richiesta e puoi utilizzare l'autorizzazione run.routes.invoke per configurare chi può accedere al tuo servizio Cloud Run in uno dei seguenti modi:

       • Concedi l'autorizzazione per selezionare service account o gruppi per consentire l'accesso al servizio. Tutte le richieste devono avere un'intestazione di autorizzazione HTTP contenente un token OpenID Connect firmato da Google per uno degli account di servizio autorizzati.

       • Concedi l'autorizzazione a allUsers per consentire l'accesso non autenticato.

       Per saperne di più, consulta Controllo dell'accesso per Cloud Run .

     • oauth_token_authentication_service_account: l'email dell'account di servizio utilizzata per generare un token OAuth, che in genere deve essere utilizzato solo quando si chiamano le API di Google ospitate su *.googleapis.com. Se vuoi, puoi impostare oauth_token_authentication_scope per specificare l'ambito di questo token; in caso contrario, il valore predefinito è https://www.googleapis.com/auth/cloud-platform. Per i servizi Google Cloud , è una best practice utilizzare l'ambito https://www.googleapis.com/auth/cloud-platform, che include tutte le API Google Cloud , insieme a Identity and Access Management (IAM), che fornisce controllo dell'accesso granulare.

       Tieni presente che tutte le richieste a un altro bus Eventarc Advanced, Pub/Sub o Workflows devono avere un'intestazione di autorizzazione HTTP contenente un token OAuth firmato da Google per uno dei service account autorizzati.

       Scopri di più sui tipi di token.

     (Facoltativo) Puoi impostare uno dei seguenti tasti:

     • output_payload_format_avro_schema_definition
     • output_payload_format_json

     • output_payload_format_protobuf_schema_definition

       Tieni presente che se imposti un formato di output, devi specificare anche un formato di input (vedi i seguenti flag input-payload-format-*).

     (Facoltativo) Se http_endpoint_uri non viene utilizzato come chiave di destinazione, puoi impostare le seguenti chiavi:

     • project: l'ID progetto della risorsa di destinazione; per impostazione predefinita, viene utilizzato l'ID progetto della pipeline. Google Cloud
     • location: la posizione della risorsa di destinazione; per impostazione predefinita, viene utilizzata la posizione della pipeline.

   • LOCATION: un'area geografica Eventarc Advanced supportata

     In alternativa, puoi impostare la proprietà di posizione di gcloud CLI:

     gcloud config set eventarc/location LOCATION
     

   (Facoltativo) Puoi utilizzare i seguenti flag:

   • --async per tornare immediatamente dal comando, senza attendere il completamento dell'operazione in corso.
   • --crypto-key per specificare il nome completo di una chiave di crittografia gestita dal cliente; se non specificato,vengono utilizzati Google-owned and managed keys .
   • --logging-config per configurare il livello di logging, che deve essere uno dei seguenti: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

   • --mediations per applicare una trasformazione; transformation_template è l'unico modello supportato e per pipeline è supportata una sola mediazione; ad esempio:

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

     Tieni presente che, se applichi una trasformazione, devi utilizzare uno dei seguenti flag per specificare un formato di input.

   • Uno dei seguenti per specificare un formato di input:

     • --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 a eventi di nuovi tentativi

   Ad esempio:

   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
   

   Per maggiori dettagli ed esempi, consulta la documentazione di gcloud CLI.

Registrazione

1. Apri un terminale.

2. Crea una registrazione utilizzando il 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

   Sostituisci quanto segue:

   • ENROLLMENT_NAME: l'ID della registrazione o un nome completo
   • MATCH_EXPRESSION: l'espressione di corrispondenza per questa registrazione utilizzando CEL, ad esempio, "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'"
   • PIPELINE_NAME: l'ID pipeline di destinazione o il relativo nome completo per questa registrazione
   • BUS_NAME: l'ID del bus Eventarc Advanced o il suo nome completo
   • PROJECT_ID: l' Google Cloud ID progetto per il bus

   • LOCATION: una regione Eventarc Advanced supportata

     In alternativa, puoi impostare la proprietà di posizione di gcloud CLI:

     gcloud config set eventarc/location LOCATION
     

   (Facoltativo) Puoi utilizzare il seguente flag:

   • --async per tornare immediatamente dal comando, senza attendere il completamento dell'operazione in corso

   Ad esempio:

   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

Per creare una pipeline, utilizza il metodo projects.locations.pipelines.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• name: il nome completo della risorsa della pipeline nel formato projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME

  Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud per il progetto della pipeline
  • LOCATION: la regione in cui deve essere eseguito il deployment della pipeline, ad esempio us-central1
  • PIPELINE_NAME: il nome della pipeline
• LABEL_KEY e LABEL_VALUE: facoltativi. Una mappa di coppie chiave-valore di etichette che ti aiutano a organizzare le tue Google Cloud risorse. Per saperne di più, vedi Che cosa sono le etichette?
• ANNOTATION_KEY e ANNOTATION_VALUE: facoltativi. Una mappa di coppie chiave-valore di annotazione di testo in formato libero. Puoi utilizzarli per allegare informazioni arbitrarie associate alla risorsa. Per ulteriori informazioni, consulta la sezione Annotazioni.
• LOG_SEVERITY: facoltativo. La gravità minima dell'evento descritto in una voce di log. Uno tra: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY. Il valore predefinito è NONE. Per ulteriori informazioni, vedi LogSeverity.
• destinations: la destinazione a cui verranno inoltrati i messaggi. È supportata una sola destinazione: httpEndpoint, messageBus, topic o workflow. Per ulteriori informazioni, consulta l'Destination target. Ad esempio, sostituisci quanto segue:
  • HTTP_URI: un URI di destinazione. L'host può essere un indirizzo IP statico indirizzabile da una rete Virtual Private Cloud (VPC) o il nome host DNS (Domain Name System) interno di un servizio risolvibile utilizzando Cloud DNS. Se vuoi, puoi anche impostare messageBindingTemplate per specificare un binding del messaggio.
  • networkAttachment: applicabile solo a httpEndpoint (inclusi gli URL Cloud Run). Il nome completo della risorsa di un collegamento di rete in questo formato: projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION /networkAttachments/NETWORK_ATTACHMENT_NAME. Un collegamento di rete è una risorsa che consente a una rete Virtual Private Cloud producer di avviare connessioni a una rete VPC consumer e deve essere specificato. Per pubblicare eventi, Eventarc Advanced utilizza il collegamento di rete per stabilire una connessione all'endpoint ospitato in una rete VPC.

    Puoi creare un collegamento di rete che accetta automaticamente le connessioni da qualsiasi interfaccia Private Service Connect che fa riferimento al collegamento di rete. Crea il collegamento di rete nella stessa rete e nella stessa regione contenenti la risorsa di destinazione.

    Se indirizzi i messaggi a una destinazione Google utilizzando un indirizzo DNS, ad esempio Cloud Run, assicurati che l'accesso privato Google sia abilitato sulla subnet utilizzata nell'allegato di rete; in caso contrario, l'indirizzo DNS non può essere risolto.

  • SERVICE_ACCOUNT_EMAIL: il nome dell'email dell'account di servizio utilizzato per generare un token OIDC che può essere utilizzato in molti scenari, inclusi gli endpoint in cui intendi convalidare il token stesso. Se vuoi, puoi impostare audience per specificare il pubblico a cui è destinato questo token. In genere, deve corrispondere all'URL della pipeline di destinazione. Se non specificato, viene utilizzato l'intero URL, inclusi eventuali parametri della richiesta.

    In alternativa, puoi utilizzare oauthToken per specificare l'email del account di servizio utilizzata per generare un token OAuth che in genere deve essere utilizzato solo quando si chiamano le API di Google ospitate su *.googleapis.com. Se vuoi, puoi impostare scope per specificare l'ambito di questo token; in caso contrario, il valore predefinito è https://www.googleapis.com/auth/cloud-platform. Per i servizi Google Cloud, è una best practice utilizzare l'ambitohttps://www.googleapis.com/auth/cloud-platform, che include tutte le API Google Cloud , insieme a Identity and Access Management (IAM), che fornisce controllo dell'accesso granulare.

    Tieni presente che tutte le richieste a un altro bus Eventarc Advanced, Pub/Sub o Workflows devono avere un'intestazione di autorizzazione HTTP contenente un token OAuth firmato da Google per uno dei service account autorizzati.

    Scopri di più sui tipi di token.

Corpo JSON della richiesta:

{
  "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"}}}]
}

Per inviare la richiesta, espandi una di queste opzioni:

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

In caso di esito positivo, il corpo della risposta contiene un'istanza appena creata di 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
}

Registrazione

Per creare una registrazione, utilizza il metodo projects.locations.enrollments.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

• ENROLLMENT_NAME: il nome visualizzato della registrazione, ad esempio my_enrollment.
• MATCH_EXPRESSION: un'espressione CEL che identifica a quali messaggi si applica questa registrazione. Ad esempio: message.type == 'hello-world-type'.
• destination: il nome completo della risorsa della pipeline di destinazione nel formato projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME.

  Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud per il progetto della pipeline
  • LOCATION: la regione in cui viene eseguito il deployment della pipeline, ad esempio us-central1.
  • PIPELINE_NAME: il nome della pipeline
• message_bus: il nome completo della risorsa del bus che identifica l'origine dei messaggi nel formato projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME.

  Sostituisci quanto segue:

  • BUS_PROJECT_ID: l'ID progetto Google Cloud per il progetto bus
  • BUS_LOCATION: la regione in cui viene eseguito il deployment del bus, ad esempio us-central1
  • BUS_NAME: il nome del bus di messaggi

Corpo JSON della richiesta:

{
  "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"
}

Per inviare la richiesta, espandi una di queste opzioni:

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

In caso di esito positivo, il corpo della risposta contiene un'istanza appena creata di 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
}