Créer une inscription pour recevoir des événements

Un enregistrement identifie un abonnement à un bus spécifique. L'enregistrement définit les critères de correspondance qui déterminent les messages à acheminer vers une destination. Il spécifie également le pipeline par lequel les messages correspondants doivent être acheminés. Un pipeline vous permet de configurer une destination cible et vous offre également la possibilité de transformer les événements correspondants avant de les distribuer à la destination.

Veuillez noter les points suivants :

  • Un pipeline et un enregistrement doivent appartenir au même projet Google Cloud. (Le bus peut appartenir au même projet ou à un autre.)
  • Un même pipeline peut être utilisé pour plusieurs inscriptions.
  • Une seule destination peut être la cible des messages acheminés par un pipeline.
  • Avant de configurer un pipeline ou un enregistrement, vous devez déjà avoir créé un bus Eventarc Advanced.

Rôles requis

Un rôle IAM (Identity and Access Management) contient un ensemble d'autorisations qui vous permet d'effectuer des actions spécifiques sur les ressources Google Cloud. Les rôles et autorisations suivants sont requis lorsque vous créez un pipeline et une inscription pour acheminer des messages:

  • Pour obtenir l'autorisation dont vous avez besoin pour créer un pipeline, demandez à votre administrateur de vous accorder le rôle IAM Développeur Eventarc (roles/eventarc.developer) sur votre projet de pipeline. Ce rôle prédéfini contient l'autorisation eventarc.pipelines.create, qui est requise pour créer un pipeline.
  • Pour obtenir l'autorisation dont vous avez besoin pour créer une inscription, demandez à votre administrateur de vous accorder le rôle IAM Développeur Eventarc (roles/eventarc.developer) sur votre projet d'inscription. Ce rôle prédéfini contient l'autorisation eventarc.enrollments.create, qui est requise pour créer une inscription.
  • Pour obtenir l'autorisation dont vous avez besoin pour utiliser un bus, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur du bus de messages Eventarc (roles/eventarc.messageBusUser) sur votre projet de bus. Ce rôle prédéfini contient l'autorisation eventarc.buses.use, qui est requise pour utiliser un bus.

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès. Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

S'inscrire pour recevoir des événements

Vous pouvez créer un pipeline et un enregistrement dans la console Google Cloud ou à l'aide de Google Cloud CLI.

Console

Dans la console Google Cloud, vous pouvez créer le pipeline et l'inscription en même temps sur la page Pipelines.

  1. Pour créer une inscription, dans la console Google Cloud, accédez à la page Eventarc > Pipelines.

    Accéder à la page Pipelines

  2. Cliquez sur Create pipeline (Créer un pipeline).

  3. Dans le volet Détails du pipeline, procédez comme suit:

    1. Saisissez un nom de pipeline. Il s'agit de l'ID de votre pipeline.
    2. Dans la liste Région, sélectionnez une région dans laquelle déployer votre pipeline. Le pipeline doit être créé dans la même région que le bus. Pour en savoir plus, consultez la page Emplacements Eventarc avancés.
    3. Facultatif: Vous pouvez modifier la configuration par défaut pour réessayer les événements.
    4. Pour Chiffrement, acceptez la clé de chiffrement gérée par Google par défaut ou sélectionnez Clé Cloud KMS. Pour en savoir plus, consultez la section Utiliser des clés de chiffrement gérées par le client (CMEK).

    5. Si vous sélectionnez Clé Cloud KMS, procédez comme suit:

      1. Dans la liste Type de clé, sélectionnez une méthode pour gérer vos clés.

        Vous pouvez gérer vos clés manuellement ou utiliser Autokey, qui vous permet de générer des trousseaux de clés et des clés à la demande. Si l'option Autokey est désactivée, cela indique qu'elle n'est pas encore intégrée au type de ressource actuel.

      2. Dans Sélectionner une clé gérée par le client, sélectionnez une clé.

        Notez que vous devez sélectionner une région avant de pouvoir afficher vos clés gérées par le client.

      3. (Facultatif) Pour saisir manuellement le nom de ressource de la clé, dans la liste Sélectionner une clé gérée par le client, cliquez sur Saisir la clé manuellement, puis saisissez le nom de clé au format spécifié.

      4. Si vous y êtes invité, attribuez le rôle cloudkms.cryptoKeyEncrypterDecrypter à l'agent de service Eventarc.

    6. Facultatif: Pour ajouter des libellés, cliquez sur Ajouter un libellé. Les libellés sont des paires clé/valeur qui vous aident à organiser vos ressources Google Cloud. Pour en savoir plus, consultez la section Que sont les libellés ?

    7. Cliquez sur Continuer.

  4. Dans le volet Inscriptions, procédez comme suit:

    1. Cliquez sur Ajouter une inscription.
    2. Saisissez un nom d'inscription.
    3. Dans la liste Bus, sélectionnez un bus auquel vous souhaitez vous abonner.

    4. Dans le champ Expression CEL, écrivez une expression d'évaluation à l'aide du CEL. Exemple :

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

      Notez que l'expression par défaut, true, indique que tous les messages sont acheminés sans filtrage.

    5. Cliquez sur OK.

    6. Vous pouvez ajouter une autre inscription ou cliquer sur Continuer.

  5. Facultatif: Dans le volet Médiation des événements, procédez comme suit ou cliquez sur Continuer:

    1. Cochez la case Appliquer une transformation.

    2. Dans la liste Format entrant, sélectionnez le format applicable.

      Notez que lorsque vous appliquez une transformation, vous devez spécifier un format de données entrantes pour un pipeline, et que tous les événements doivent correspondre à ce format.

    3. Pour les formats Avro ou Protobuf, vous devez spécifier un schéma d'entrée. Vous pouvez également importer un schéma d'entrée. Pour en savoir plus, consultez la section Formater les événements reçus.

    4. Dans le champ Expression CEL, écrivez une expression de transformation à l'aide du CEL.

    5. Cliquez sur Continuer.

  6. Dans le volet Destination, procédez comme suit:

    1. Dans la liste Type de destination, sélectionnez un type de destination vers lequel acheminer les messages. En fonction du type de destination, procédez comme suit:

      • Point de terminaison HTTP: spécifiez l'URI de destination. L'hôte peut être une adresse IP statique adressable à partir d'un réseau VPC (Virtual Private Cloud) ou le nom d'hôte DNS (Domain Name System) interne d'un service pouvant être résolu à l'aide de Cloud DNS.

        Notez que vous pouvez utiliser ce type de destination pour cibler une fonction Cloud Run.

      • Bus Eventarc Advanced: sélectionnez un bus Eventarc Advanced.

      • Workflows workflow (Workflow Workflows) : sélectionnez un workflow Workflows.

      • Sujet Pub/Sub: sélectionnez ou créez un sujet Pub/Sub.

      • Service Cloud Run (via HTTP): sélectionnez un service Cloud Run qui recevra des événements sous la forme de requêtes HTTP POST envoyées à son chemin d'URL racine (/). Vous pouvez également spécifier un chemin d'URL relatif sur le service de destination auquel les événements doivent être envoyés.

      • Job Cloud Run (via HTTP): sélectionnez une job Cloud Run qui recevra des événements sous la forme de requêtes HTTP POST.

    2. Spécifiez un rattachement de réseau.

      Un rattachement de réseau est une ressource qui permet à un réseau VPC producteur d'établir des connexions à un réseau VPC consommateur. Pour publier des événements, Eventarc Advanced utilise le rattachement de réseau afin d'établir une connexion au point de terminaison hébergé dans un réseau VPC.

      Vous pouvez créer un rattachement de réseau qui accepte automatiquement les connexions de n'importe quelle interface Private Service Connect qui fait référence au rattachement de réseau. Créez le rattachement de réseau dans le même réseau et la même région que ceux contenant le point de terminaison de destination.

      Si vous acheminez des messages vers une destination Google à l'aide d'une adresse DNS (par exemple, Cloud Run, Pub/Sub, Workflows ou un autre bus Eventarc Advanced), assurez-vous que l'Accès privé à Google est activé sur le sous-réseau utilisé dans l'association réseau. Sinon, l'adresse DNS ne peut pas être résolue.

    3. Le cas échéant, sélectionnez un format dans la liste Format sortant.

      Notez que si un format de données entrantes n'est pas spécifié pour un pipeline, vous ne pouvez pas définir de format sortant.

    4. Le cas échéant, appliquez une liaison de messages. Pour en savoir plus, consultez la section Définir une liaison de message.

    5. Pour activer l'authentification, cochez la case Activer l'authentification.

      1. Dans la liste En-tête d'authentification, sélectionnez le type de jeton à générer et joignez-le en tant qu'en-tête Authorization dans la requête HTTP:

        • Un jeton OAuth ne doit généralement être utilisé que pour appeler les API Google hébergées sur *.googleapis.com. Vous pouvez également spécifier la portée de ce jeton. Sinon, la valeur par défaut est https://www.googleapis.com/auth/cloud-platform. Pour les services Google Cloud, il est recommandé d'utiliser le champ d'application https://www.googleapis.com/auth/cloud-platform, qui inclut toutes les API Google Cloud, ainsi que Identity and Access Management (IAM), qui fournit un contrôle des accès précis.

          Notez que toutes les requêtes envoyées à un autre bus Eventarc Advanced, Pub/Sub ou Workflows doivent comporter un en-tête d'autorisation HTTP contenant un jeton OAuth signé par Google pour l'un des comptes de service autorisés.

        • Un jeton OIDC peut être utilisé dans de nombreux scénarios, y compris les points de terminaison où vous prévoyez de valider le jeton vous-même. Spécifiez également l'audience à laquelle ce jeton est destiné. En règle générale, il doit correspondre à l'URL du pipeline cible. Si cette option n'est pas spécifiée, l'URL complète est utilisée, y compris les paramètres de requête.

          Notez que Cloud Run effectue une vérification IAM à chaque requête. Vous pouvez utiliser l'autorisation run.routes.invoke pour configurer les utilisateurs autorisés à accéder à votre service Cloud Run de deux manières:

          • Accordez l'autorisation de sélectionner des comptes de service ou des groupes pour autoriser l'accès au service. Toutes les requêtes doivent comporter un en-tête d'autorisation HTTP contenant un jeton OpenID Connect signé par Google pour l'un des comptes de service autorisés.

          • Accordez l'autorisation à allUsers pour autoriser l'accès non authentifié.

          Pour en savoir plus, consultez la section Contrôle des accès pour Cloud Run.

        En savoir plus sur les types de jetons

      2. Dans la liste Compte de service, sélectionnez le compte de service qui appellera votre service de destination. Vous pouvez également créer un nouveau compte de service.

        Cela spécifie l'adresse e-mail du compte de service IAM associé au pipeline et auquel vous avez précédemment attribué des rôles spécifiques requis par Eventarc Advanced.

  7. Cliquez sur Créer.

gcloud

Lorsque vous utilisez gcloud CLI, créez d'abord le pipeline, puis l'enregistrement à l'aide des commandes appropriées.

Pipeline

  1. Ouvrez un terminal.

  2. Créez un pipeline à l'aide de la commande gcloud beta eventarc pipelines create:

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

    Remplacez les éléments suivants :

    • PIPELINE_NAME: ID du pipeline ou nom complet

    • DESTINATION_KEY: une ou plusieurs paires clé-valeur pour configurer une destination pour le pipeline

      Vous ne devez définir qu'une seule des clés suivantes:

      Vous devez définir la clé suivante:

      • network_attachment : ressource qui permet à un réseau VPC producteur d'établir des connexions à un réseau VPC consommateur. Pour publier des événements, Eventarc Advanced utilise le rattachement de réseau afin d'établir une connexion au point de terminaison hébergé dans un réseau VPC.

        Vous pouvez créer un rattachement de réseau qui accepte automatiquement les connexions de n'importe quelle interface Private Service Connect qui fait référence au rattachement de réseau. Créez le rattachement de réseau dans le même réseau et la même région que ceux contenant la ressource de destination.

        Si vous acheminez des messages vers une destination Google à l'aide d'une adresse DNS (par exemple, Cloud Run, Pub/Sub, Workflows ou un autre bus Eventarc Advanced), assurez-vous que l'Accès privé à Google est activé sur le sous-réseau utilisé dans l'association réseau. Sinon, l'adresse DNS ne peut pas être résolue.

      Pour activer l'authentification, vous pouvez définir une des clés suivantes:

      • google_oidc_authentication_service_account : adresse e-mail du compte de service utilisée pour générer un jeton OIDC, qui peut être utilisé dans de nombreux scénarios, y compris les points de terminaison où vous souhaitez valider le jeton vous-même. Vous pouvez éventuellement définir google_oidc_authentication_audience pour spécifier l'audience à laquelle ce jeton est destiné. En règle générale, il doit correspondre à l'URL du pipeline cible. Si cette option n'est pas spécifiée, l'URL complète est utilisée, y compris les paramètres de requête.

        Notez que Cloud Run effectue une vérification IAM à chaque requête. Vous pouvez utiliser l'autorisation run.routes.invoke pour configurer les utilisateurs autorisés à accéder à votre service Cloud Run de deux manières:

        • Accordez l'autorisation de sélectionner des comptes de service ou des groupes pour autoriser l'accès au service. Toutes les requêtes doivent comporter un en-tête d'autorisation HTTP contenant un jeton OpenID Connect signé par Google pour l'un des comptes de service autorisés.

        • Accordez l'autorisation à allUsers pour autoriser l'accès non authentifié.

        Pour en savoir plus, consultez la section Contrôle des accès pour Cloud Run .

      • oauth_token_authentication_service_account : adresse e-mail du compte de service utilisée pour générer un jeton OAuth, qui ne doit généralement être utilisée que pour appeler les API Google hébergées sur *.googleapis.com. Vous pouvez également définir oauth_token_authentication_scope pour spécifier la portée de ce jeton. Sinon, la valeur par défaut est https://www.googleapis.com/auth/cloud-platform. Pour les services Google Cloud, il est recommandé d'utiliser le champ d'application https://www.googleapis.com/auth/cloud-platform, qui inclut toutes les API Google Cloud, ainsi que Identity and Access Management (IAM), qui fournit un contrôle des accès précis.

        Notez que toutes les requêtes envoyées à un autre bus Eventarc Advanced, Pub/Sub ou Workflows doivent comporter un en-tête d'autorisation HTTP contenant un jeton OAuth signé par Google pour l'un des comptes de service autorisés.

        En savoir plus sur les types de jetons

      Facultatif: vous pouvez définir une des clés suivantes:

      • output_payload_format_avro_schema_definition
      • output_payload_format_json

      • output_payload_format_protobuf_schema_definition

        Notez que si vous définissez un format de sortie, vous devez également spécifier un format d'entrée (voir les options input-payload-format-* suivantes).

      Facultatif: Si http_endpoint_uri n'est pas utilisé comme clé de destination, vous pouvez définir les clés suivantes:

      • project : ID de projet Google Cloud de la ressource de destination. Par défaut, l'ID de projet du pipeline est utilisé.
      • location : emplacement de la ressource de destination. Par défaut, l'emplacement du pipeline est utilisé.

    • REGION: un emplacement Eventarc Advanced compatible

      Vous pouvez également définir la propriété d'emplacement de gcloud CLI:

      gcloud config set eventarc/location REGION

    Facultatif: vous pouvez utiliser les options suivantes:

    • --async pour quitter immédiatement la commande, sans attendre la fin de l'opération en cours.
    • --crypto-key pour spécifier le nom complet d'une clé de chiffrement gérée par le client. Si ce n'est pas spécifié, des clés gérées par Google sont utilisées.
    • --logging-config pour configurer le niveau de journalisation, qui doit correspondre à l'un des éléments suivants: NONE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY.

    • --mediations pour appliquer une transformation ; transformation_template est le seul modèle compatible et une seule médiation par pipeline est acceptée. Par exemple:

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

      Notez que si vous appliquez une transformation, vous devez utiliser l'une des options suivantes pour spécifier un format d'entrée.

    • L'un des éléments suivants pour spécifier un format d'entrée:

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

    • --max-retry-attempts, --max-retry-delay et --min-retry-delay pour réessayer des événements

    Exemple :

    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

    Pour en savoir plus et obtenir des exemples, consultez la documentation de gcloud CLI.

Inscription

  1. Ouvrez un terminal.

  2. Créez une inscription à l'aide de la commande 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

    Remplacez les éléments suivants :

    • ENROLLMENT_NAME: ID de l'enregistrement ou nom complet
    • MATCH_EXPRESSION: expression de correspondance pour cette inscription à l'aide du langage CEL (par exemple, "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'")
    • PIPELINE_NAME: ID du pipeline cible ou son nom complet pour cet enregistrement
    • BUS_NAME: ID du bus Eventarc Advanced ou son nom complet
    • PROJECT_ID: ID de projet Google Cloud du bus

    • REGION: un emplacement Eventarc Advanced compatible

      Vous pouvez également définir la propriété d'emplacement de gcloud CLI:

      gcloud config set eventarc/location REGION

    Facultatif: vous pouvez utiliser l'option suivante:

    • --async pour quitter immédiatement la commande, sans attendre la fin de l'opération en cours

    Exemple :

    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

Supprimer une inscription

Vous pouvez supprimer une inscription dans la console Google Cloud ou à l'aide de Google Cloud CLI.

Console

  1. Pour supprimer une inscription, dans la console Google Cloud, accédez à la page Eventarc > Pipelines.

    Accéder à la page Pipelines

  2. Cliquez sur le nom du pipeline dont vous souhaitez supprimer l'inscription.

    Le volet Détails du pipeline s'ouvre.

  3. Cliquez sur Continuer.

    Le volet Inscriptions s'ouvre.

  4. Pour l'inscription que vous souhaitez supprimer, cliquez sur l'icône de suppression .

  5. Cliquez sur Enregistrer.

gcloud

  1. Ouvrez un terminal.

  2. Supprimez une inscription à l'aide de la commande gcloud beta eventarc enrollments delete:

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

    Remplacez les éléments suivants :

Supprimer un pipeline

Vous pouvez supprimer un pipeline dans la console Google Cloud ou à l'aide de Google Cloud CLI.

Notez que la suppression d'un pipeline peut prendre plus de 10 minutes.

Console

  1. Pour supprimer un pipeline, dans la console Google Cloud, accédez à la page Eventarc > Pipelines.

    Accéder à la page Pipelines

  2. Dans la liste des pipelines, cochez la case à côté du nom du pipeline que vous souhaitez supprimer.

  3. Cliquez sur Supprimer.

  4. Confirmez la suppression en saisissant Delete.

  5. Cliquez sur Supprimer.

gcloud

  1. Ouvrez un terminal.

  2. Supprimez un pipeline à l'aide de la commande gcloud beta eventarc pipelines delete:

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

    Remplacez les éléments suivants :

Étape suivante