Publier et recevoir des événements en créant un bus et un abonnement

Ce guide de démarrage rapide explique comment publier et recevoir des messages d'événement en créant un bus Eventarc Advanced et en vous inscrivant à votre projet Google Cloud.

Un bus vous permet de centraliser le flux de messages dans votre système et agit comme un routeur. Il reçoit des événements d'une source de messages ou publiés par un fournisseur, et les évalue en fonction d'un enregistrement.

Un enregistrement identifie un abonnement à un bus spécifique et définit les critères de correspondance des messages, ce qui les achemine vers une ou plusieurs destinations.

Dans le cadre de ce guide démarrage rapide, vous allez effectuer les étapes suivantes :

  1. Créez un sous-réseau et activez l'accès privé à Google.

  2. créer un rattachement de réseau.

  3. Déployer un service récepteur d'événements sur Cloud Run.

  4. Créez un bus Eventarc Advanced.

  5. Créez une inscription Eventarc Advanced.

  6. Publiez un message d'événement sur le bus.

  7. Afficher les données d'événement dans les journaux Cloud Run.

Vous pouvez suivre ce guide de démarrage rapide dans Google Cloud CLI.

Avant de commencer

Les contraintes de sécurité définies par votre organisation peuvent vous empêcher d'effectuer les étapes suivantes. Pour obtenir des informations de dépannage, consultez la page Développer des applications dans un environnement Google Cloud limité.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. Install the Google Cloud CLI.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com
  7. Install the Google Cloud CLI.

  8. To initialize the gcloud CLI, run the following command: 

    gcloud init

  9. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  10. Make sure that billing is enabled for your Google Cloud project.

  11. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs: 

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

  12. Mettez à jour les composants gcloud : 
    gcloud components update

  13. Connectez-vous à votre compte : 
    gcloud auth login

  14. Définissez la variable de configuration utilisée dans ce guide de démarrage rapide: 
    REGION=REGION

    Remplacez REGION par un emplacement compatible pour le bus.

  15. Si vous êtes le créateur du projet, vous disposez du rôle de base Propriétaire (roles/owner). Par défaut, ce rôle Identity and Access Management (IAM) inclut les autorisations nécessaires pour accéder à la plupart des ressources Google Cloud. Vous pouvez ignorer cette étape.

    Si vous n'êtes pas le créateur du projet, les autorisations requises doivent être accordées au compte principal approprié sur le projet. Par exemple, un compte principal peut être un compte Google (pour les utilisateurs finaux) ou un compte de service (pour les applications et les charges de travail de calcul).

    Notez que par défaut, les autorisations Cloud Build incluent des autorisations permettant d'importer et de télécharger des artefacts Artifact Registry.

    Autorisations requises

    Pour obtenir les autorisations nécessaires pour suivre ce guide de démarrage rapide, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

    Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

  16. Attribuez les rôles suivants sur le projet au compte de service Compute Engine par défaut. Ces rôles sont nécessaires lors de la création et du déploiement de votre image de conteneur : 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.writer
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/storage.objectUser

    Remplacez PROJECT_NUMBER par votre numéro de projet Google Cloud. Vous pouvez trouver le numéro de votre projet sur la page Bienvenue de la console Google Cloud ou en exécutant la commande suivante :

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

  17. Par défaut, seuls les propriétaires de projet, les éditeurs de projet, ainsi que les administrateurs et les demandeurs Cloud Run peuvent appeler les services Cloud Run. Pour configurer l'authentification, attribuez le rôle Demandeur Cloud Run (run.invoker) de votre projet Google Cloud à un compte de service :
    1. Créez un compte de service. À des fins de test, vous allez associer ce compte de service à un pipeline Eventarc Advanced pour représenter l'identité du pipeline. 
      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
       Remplacez SERVICE_ACCOUNT_NAME par le nom que vous souhaitez donner à votre compte de service.
    2. Attribuez le rôle IAM roles/run.invoker au compte de service: 
      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/run.invoker

    Notez que vous pouvez 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. C'est ainsi que l'accès est configuré dans ce guide de démarrage rapide.
    • 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.

Créer un sous-réseau et activer l'accès privé à Google

Sauf si vous créez une règle d'administration qui l'interdit, les nouveaux projets Google Cloud démarrent avec un réseau cloud privé virtuel (VPC) par défaut (un réseau VPC en mode automatique) qui possède un sous-réseau dans chaque région. Les sous-réseaux sont associés à des plages d'adresses IP.

Étant donné que vous acheminez des messages vers une destination Cloud Run à l'aide d'une adresse DNS, vous devez activer l'Accès privé à Google sur le sous-réseau utilisé dans l'association réseau. Sinon, l'adresse DNS ne peut pas être résolue. Pour en savoir plus sur la mise en réseau privée et Cloud Run, consultez la page Recevoir des requêtes provenant de réseaux VPC.

Créez un sous-réseau dans le réseau par défaut de votre projet et utilisez l'option --enable-private-ip-google-access pour activer l'accès privé à Google:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Remplacez SUBNET_NAME par le nom de votre sous-réseau, par exemple my-subnet.

Les plages d'adresses IP des sous-réseaux doivent être uniques et ne pas se chevaucher dans un réseau VPC et un réseau VPC appairé. Pour en savoir plus sur les types de sous-réseaux et les plages de sous-réseaux valides, consultez la section Sous-réseaux.

Créer 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.

Créez un rattachement de réseau dans le même réseau et la même région que le point de terminaison de destination de l'événement, qui accepte automatiquement les connexions de n'importe quelle interface Private Service Connect qui fait référence au rattachement de réseau:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Remplacez ATTACHMENT_NAME par le nom de votre pièce jointe réseau (par exemple, my-network-attachment).

Créer un dépôt standard Artifact Registry

Créez un dépôt standard Artifact Registry pour stocker votre image de conteneur.

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Remplacez REPOSITORY par un nom unique pour le dépôt Artifact Registry (par exemple, my-repo).

Déployer un service récepteur d'événements sur Cloud Run

Déployez un service Cloud Run qui consigne le contenu d'un événement. Ce service n'est accessible qu'à partir des réseaux VPC du même projet, et l'URL du service n'est pas accessible directement, car le service n'autorise que des appels authentifiés.

  1. Clonez le dépôt GitHub.

    git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

  2. Accédez au répertoire contenant l'exemple de code Cloud Run :

    cd eventarc-samples/eventarc-advanced-quickstart/

  3. Créez une image de conteneur Docker et transférez-la vers votre dépôt:

    gcloud builds submit \
    --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

  4. Déployez l'image de conteneur dans Cloud Run :

    gcloud run deploy SERVICE_NAME \
    --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --platform managed \
    --ingress internal \
    --no-allow-unauthenticated \
    --region=$REGION

    Remplacez SERVICE_NAME par le nom de votre service, par exemple my-service.

Lorsque l'URL du service Cloud Run s'affiche, le déploiement est terminé. Notez cette URL afin de pouvoir l'utiliser lors d'une étape ultérieure.

Créer un bus Eventarc Advanced

Créez un bus Eventarc Advanced dans votre projet à l'aide de la commande gcloud beta eventarc message-buses create:

gcloud beta eventarc message-buses create BUS_NAME \
    --location=$REGION

Remplacez BUS_NAME par l'ID ou l'identifiant complet de votre bus (par exemple, my-bus).

Pour en savoir plus, consultez la section Créer un bus pour acheminer les messages.

Créer une inscription Eventarc Advanced

Une inscription détermine les messages qui sont acheminés vers une destination. Il spécifie également le pipeline par lequel les messages doivent être acheminés. Le pipeline permet de configurer une destination pour les messages d'événement.

Pour en savoir plus, consultez la section Créer une inscription pour recevoir des événements.

Lorsque vous utilisez la gcloud CLI, vous devez d'abord créer un pipeline, puis un enregistrement.

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

    gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --location=$REGION

    Remplacez les éléments suivants :

    • PIPELINE_NAME: ID du pipeline ou nom complet.
    • CLOUD_RUN_SERVICE_URL: URL complète de votre service Cloud Run (par exemple, https://SERVICE_NAME-abcdef-uc.a.run.app). Il s'agit de la destination de vos messages d'événement.

    Notez que la clé google_oidc_authentication_service_account spécifie une adresse e-mail de compte de service utilisée pour générer un jeton OIDC.

  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 == 'hello-world-type'").

Publier un message d'événement sur le bus

Pour publier directement un message dans votre bus, vous pouvez utiliser la commande gcloud beta eventarc message-buses publish ou envoyer une requête à l'API REST Eventarc Publishing. Pour en savoir plus, consultez la section Publier des événements directement.

Le message doit être au format CloudEvents, une spécification permettant d'uniformiser la description des données d'événement. L'élément data correspond à la charge utile de votre événement. Tout fichier JSON valide peut être placé dans ce champ. Pour en savoir plus sur les attributs de contexte CloudEvents, consultez la section Format d'événement.

Voici des exemples de publication directe d'un événement sur un bus Eventarc Advanced:

Exemple 1

Vous pouvez publier un événement sur un bus à l'aide de la gcloud CLI et d'un --event-data et d'autres options d'attribut d'événement:

gcloud beta eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Exemple 2

Vous pouvez publier un événement sur un bus en tant que message JSON à l'aide de gcloud CLI et d'un indicateur --json-message:

gcloud beta eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Une fois l'événement publié, vous devriez recevoir le message "Événement publié avec succès".

Afficher les données d'événement dans les journaux Cloud Run

Après avoir publié un événement sur votre bus Eventarc Advanced, vous pouvez consulter les journaux de votre service Cloud Run pour vérifier que l'événement a été reçu comme prévu.

  1. Filtrez les entrées de journal et renvoyez la sortie à l'aide de la commande gcloud logging read:

    gcloud logging read 'textPayload: "hello-world-data"'

  2. Recherchez une entrée de journal semblable à ceci :

    insertId: 670808e70002b5c6477709ae
labels:
instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
resource:
labels:
...
type: cloud_run_revision
textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
  }'"
timestamp: '2024-10-10T17:03:35.177606Z'

Vous avez créé un bus et un enregistrement Eventarc Advanced, publié un message d'événement sur le bus et vérifié le résultat attendu dans les journaux du service récepteur d'événements.

Effectuer un nettoyage

Une fois que vous avez terminé les tâches décrites dans ce guide de démarrage rapide, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées:

  1. Supprimez un sous-réseau VPC.

  2. Supprimez un rattachement de réseau VPC.

  3. Supprimez un dépôt Artifact Registry.

  4. Supprimez un service Cloud Run.

  5. Supprimez les ressources Eventarc Advanced:

    1. Supprimer un enregistrement

    2. Supprimez un pipeline.

    3. Supprimez un bus.

Vous pouvez également supprimer votre projet Google Cloud pour éviter des frais. La suppression de votre projet Google Cloud arrête la facturation de toutes les ressources utilisées dans ce projet.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Étape suivante