Déclencheurs Google Cloud Pub/Sub

Les fonctions Cloud Functions peuvent être déclenchées par les messages publiés dans les sujets Pub/Sub dans le même projet Cloud contenant la fonction. Pub/Sub est un service de messagerie distribué dans le monde entier qui effectue un scaling automatique en fonction des besoins et vous permet de développer des services robustes à l'échelle mondiale.

Types d'événement

Un seul événement Pub/Sub est utilisé par Cloud Functions. Il est associé à la valeur du type de déclencheur suivante : google.pubsub.topic.publish.

Cet événement est envoyé lorsqu'un message est publié dans un sujet Pub/Sub, qui est spécifié lorsqu'une fonction est déployée. Chaque message publié dans ce sujet déclenche l'exécution de la fonction avec le contenu des messages transmis en tant que données d'entrée.

Structure de l'événement

Les fonctions Cloud Functions déclenchées à partir d'un sujet Pub/Sub reçoivent des événements conformes au type PubsubMessage, avec la mise en garde suivante : publishTime et messageId ne sont pas directement disponibles dans le PubsubMessage. À la place, vous pouvez accéder à publishTime et messageId via l'ID de l'événement et les propriétés d'horodatage des métadonnées de l'événement. Ces métadonnées sont accessibles via l'objet de contexte transmis à votre fonction lorsqu'elle est appelée.

La charge utile de l'objet PubsubMessage (les données que vous avez publiées sur le sujet) est stockée sous la forme d'une chaîne encodée en base64 dans l'attribut data du PubsubMessage. Pour extraire la charge utile de l'objet PubsubMessage, vous devrez peut-être décoder l'attribut de données comme indiqué dans les exemples ci-dessous.

Exemple de code

Node.js 8+

/**
     * Background Cloud Function to be triggered by Pub/Sub.
     * This function is exported by index.js, and executed when
     * the trigger topic receives a message.
     *
     * @param {object} pubSubEvent The event payload.
     * @param {object} context The event metadata.
     */
    exports.helloPubSub = (pubSubEvent, context) => {
      const name = pubSubEvent.data
        ? Buffer.from(pubSubEvent.data, 'base64').toString()
        : 'World';

      console.log(`Hello, ${name}!`);
    };

Node.js 6 (obsolète)

/**
     * Background Cloud Function to be triggered by Pub/Sub.
     * This function is exported by index.js, and executed when
     * the trigger topic receives a message.
     *
     * @param {object} event The Cloud Functions event.
     * @param {function} callback The callback function.
     */
    exports.helloPubSub = (event, callback) => {
      const pubsubMessage = event.data;
      const name = pubsubMessage.data
        ? Buffer.from(pubsubMessage.data, 'base64').toString()
        : 'World';

      console.log(`Hello, ${name}!`);

      callback();
    };

Python

def hello_pubsub(event, context):
        """Background Cloud Function to be triggered by Pub/Sub.
        Args:
             event (dict):  The dictionary with data specific to this type of
             event. The `data` field contains the PubsubMessage message. The
             `attributes` field will contain custom attributes if there are any.
             context (google.cloud.functions.Context): The Cloud Functions event
             metadata. The `event_id` field contains the Pub/Sub message ID. The
             `timestamp` field contains the publish time.
        """
        import base64

        print("""This Function was triggered by messageId {} published at {}
        """.format(context.event_id, context.timestamp))

        if 'data' in event:
            name = base64.b64decode(event['data']).decode('utf-8')
        else:
            name = 'World'
        print('Hello {}!'.format(name))

Go


    // Package helloworld provides a set of Cloud Functions samples.
    package helloworld

    import (
    	"context"
    	"log"
    )

    // PubSubMessage is the payload of a Pub/Sub event.
    type PubSubMessage struct {
    	Data []byte `json:"data"`
    }

    // HelloPubSub consumes a Pub/Sub message.
    func HelloPubSub(ctx context.Context, m PubSubMessage) error {
    	name := string(m.Data)
    	if name == "" {
    		name = "World"
    	}
    	log.Printf("Hello, %s!", name)
    	return nil
    }
    

Publier un message à partir d'une fonction

Vous pouvez également publier un message dans un sujet Pub/Sub à partir d'une fonction. Cela vous permet de déclencher des appels de fonctions Cloud ultérieurs à l'aide des messages Cloud Pub/Sub. Cette technique vous permet :

  • d'associer des appels de fonction séquentiels ;
  • de distribuer (ou d'effectuer une distribution ramifiée) des groupes de tâches en parallèle sur plusieurs instances de Cloud Functions.

Dans l'exemple suivant, une fonction publish HTTP envoie un message à un sujet Pub/Sub, qui à son tour déclenche une fonction subscribe.

Dans cet extrait, la fonction publish publie un message sur un sujet Pub/Sub :

Node.js

/**
     * Publishes a message to a Cloud Pub/Sub Topic.
     *
     * @example
     * gcloud functions call publish --data '{"topic":"[YOUR_TOPIC_NAME]","message":"Hello, world!"}'
     *
     *   - Replace `[YOUR_TOPIC_NAME]` with your Cloud Pub/Sub topic name.
     *
     * @param {object} req Cloud Function request context.
     * @param {object} req.body The request body.
     * @param {string} req.body.topic Topic name on which to publish.
     * @param {string} req.body.message Message to publish.
     * @param {object} res Cloud Function response context.
     */
    exports.publish = async (req, res) => {
      if (!req.body.topic || !req.body.message) {
        res
          .status(500)
          .send(
            'Missing parameter(s); include "topic" and "subscription" properties in your request.'
          );
        return;
      }

      console.log(`Publishing message to topic ${req.body.topic}`);

      // References an existing topic
      const topic = pubsub.topic(req.body.topic);

      const messageObject = {
        data: {
          message: req.body.message,
        },
      };
      const messageBuffer = Buffer.from(JSON.stringify(messageObject), 'utf8');

      // Publishes a message
      try {
        await topic.publish(messageBuffer);
        res.status(200).send('Message published.');
      } catch (err) {
        console.error(err);
        res.status(500).send(err);
        return Promise.reject(err);
      }
    };

Cet extrait illustre la fonction subscribe qui est déclenchée lorsque le message est publié dans le sujet Pub/Sub :

Node.js

/**
     * Triggered from a message on a Cloud Pub/Sub topic.
     *
     * @param {object} pubsubMessage The Cloud Pub/Sub Message object.
     * @param {string} pubsubMessage.data The "data" property of the Cloud Pub/Sub Message.
     */
    exports.subscribe = pubsubMessage => {
      // Print out the data from Pub/Sub, to prove that it worked
      console.log(Buffer.from(pubsubMessage.data, 'base64').toString());
    };

En production, vous pouvez utiliser l'utilitaire de ligne de commande cURL pour appeler la fonction publish, comme suit :

    curl https://GCF_REGION-GCP_PROJECT_ID.cloudfunctions.net/publish -X POST  -d "{\"topic\": \"PUBSUB_TOPIC\", \"message\":\"YOUR_MESSAGE\"}" -H "Content-Type: application/json"
    

Toutefois, à des fins de test et de débogage, utilisez plutôt la commande gcloud functions call pour appeler directement la fonction. Dans les étapes suivantes, vous allez apprendre à exécuter l'exemple ci-dessus à l'aide de la commande gcloud functions call :

  1. Créez un sujet Pub/Sub, où MY_TOPIC est le nom du nouveau sujet que vous créez :

    gcloud pubsub topics create MY_TOPIC
  2. Déployez la fonction publish, où RUNTIME est le nom de l'environnement d'exécution que vous utilisez (par exemple, nodejs8) :

    gcloud functions deploy publish --trigger-http --runtime RUNTIME
  3. Déployez la fonction subscribe :

    gcloud functions deploy subscribe --trigger-topic MY_TOPIC --runtime RUNTIME
  4. Appelez directement la fonction publish à l'aide de la commande gcloud functions call et fournissez les données requises au format JSON dans l'argument --data :

    gcloud functions call publish --data '{"topic":"MY_TOPIC","message":"Hello World!"}'
  5. Recherchez la fonction subscribe dans les journaux. L'affichage de vos résultats dans le journal peut prendre quelques minutes :

    gcloud functions logs read subscribe

Un résultat semblable à celui-ci doit s'afficher :

    D    ...Function execution started
    I    ...{"data":{"message":"Hello World!"}}
    D    ...Function execution took 753 ms, finished with status: 'ok'
    

Déployer votre fonction

La commande gcloud suivante déploie une fonction qui se déclenche lorsqu'un message est publié dans un sujet Pub/Sub :

    gcloud functions deploy FUNCTION_NAME --trigger-topic TOPIC_NAME FLAGS...
    
Argument Description
FUNCTION_NAME Nom de la fonction.
--trigger-topic TOPIC_NAME Nom du sujet Pub/Sub auquel la fonction est abonnée. Si le sujet n'existe pas, il est créé lors du déploiement.
FLAGS... Les options supplémentaires à spécifier lors du déploiement, telles que --runtime. Pour accéder aux informations complètes, consultez la documentation sur gcloud functions deploy.

Consultez le Tutoriel Pub/Sub pour obtenir un exemple complet d'utilisation des déclencheurs Pub/Sub.

Déclencheurs de l'ancien service Cloud Pub/Sub

La commande gcloud ci-dessous déploie une fonction déclenchée par les notifications de l'ancien service Pub/Sub sur un sujet spécifique. Ces notifications sont compatibles avec les anciennes fonctions qui utilisent déjà ces événements. Nous vous recommandons cependant d'utiliser l'option --trigger-topic, car les anciennes notifications risquent d'être supprimées plus tard.

    gcloud functions deploy FUNCTION_NAME \
    --trigger-resource TOPIC_NAME \
    --trigger-event providers/cloud.pubsub/eventTypes/topic.publish \
    FLAGS...
    

Étapes suivantes

Reportez-vous au Tutoriel Pub/Sub pour obtenir un exemple de mise en œuvre d'une fonction d'arrière-plan déclenchée par Pub/Sub.