Notification de modification d'objet


La fonctionnalité de notification de modification d'objet permet de notifier une application lorsqu'un objet est mis à jour ou ajouté à un bucket.

Notez que cette fonctionnalité est distincte des notifications Cloud Pub/Sub pour Cloud Storage. Les notifications Cloud Pub/Sub sont recommandées pour suivre les modifications apportées aux objets de vos buckets Cloud Storage, car elles sont plus rapides, plus flexibles, plus faciles à configurer et plus économiques.

Fonctionnement de la notification de modification d'objet

Une application cliente peut émettre une requête lui permettant de surveiller les modifications apportées aux objets d'un bucket particulier.

L'émission d'une telle requête crée un nouveau canal de notification. Un canal de notification est le moyen par lequel un message de notification est envoyé à une application surveillant un bucket. À l'heure actuelle, un seul canal de notification, le Webhook, est compatible.

Une fois qu'un canal de notification est mis en place, Cloud Storage notifie l'application chaque fois qu'un objet est ajouté, mis à jour ou supprimé du bucket. Par exemple, lorsque vous ajoutez une image à un bucket, une application peut être notifiée pour créer une vignette.

La figure ci-dessous montre un exemple de flux de données pour une application traitant les notifications de modification. Tout serveur d'applications pouvant recevoir des requêtes HTTPS POST peut être utilisé pour traiter les notifications de modification.

Composants d'une notification de modification d'objet
Composants d'une notification de modification d'objet

Détails de la notification de modification d'objet

Terminologie

Le tableau suivant contient une description de plusieurs termes utilisés tout au long de la documentation relative aux notifications de modification d'objet :

Terme Description
URL de l'application URL de votre application. Il s'agit de l'adresse à laquelle les notifications seront envoyées. Notez qu'il doit s'agir d'une URL HTTPS. Les URL HTTP ne sont pas autorisées.
Identifiant de canal Identifiant d'un canal de notification. Cette valeur doit être unique dans un bucket particulier. S'il existe plusieurs canaux de notification pour un même bucket, chaque canal doit avoir un identifiant de canal distinct. Cet identifiant sera envoyé à l'application avec chaque message de notification.
Identifiant de ressource Identifiant opaque pour la ressource surveillée. L'identifiant de ressource est requis pour l'arrêt d'un canal de notification. Vous pouvez extraire cet identifiant de la réponse à une requête de surveillance ou de l'en-tête X-Goog-Resource-Id des messages d'événements de notification.
Jeton Client (facultatif) Les jetons client peuvent être utilisés pour valider les événements de notification. Pour ce faire, définissez un jeton client personnalisé avec votre requête de surveillance. Les messages de notification contiendront ce jeton afin que vous puissiez vérifier leur authenticité.

Surveiller un bucket

Pour commencer à surveiller les événements des notifications de modification dans un bucket, vous pouvez utiliser la commande gsutil notification watchbucket :

gsutil notification watchbucket [-i ChannelId] [-t ClientToken] ApplicationUrl gs://BucketName

Un canal de notification est créé et permet d'envoyer des événements de notification à l'URL de l'application donnée pour le bucket donné. Le canal de notification inclut le jeton client personnalisé et l'identifiant de canal, le cas échéant.

Pour en savoir plus sur cette commande, exécutez la commande gsutil help notification watchbucket.

Voici un exemple de requête POST générée par gsutil pour surveiller un bucket :

POST /storage/v1/b/BucketName/o/watch?alt=json HTTP/1.1
Host: www.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "token": "ClientToken",
  "type": "web_hook",
  "id": "ChannelId",
  "address": "ApplicationUrl"
}

Autorisation de notification

Lors de la surveillance d'un bucket, le canal de notification en cours de création sera associé au projet de la console Google Cloud Platform de l'application à l'origine de la requête API. Cela signifie, par exemple, que si un utilisateur accorde l'accès à une application installée ou à une application Web via un flux OAuth2, un canal de notification créé par l'application sera associé au projet de cette application et non au projet contenant le bucket surveillé.

La configuration de l'autorisation dans un scénario de notification de modification d'objet s'effectue en trois étapes :

Créer un compte de service

Un compte de service étant associé à un projet, l'utilisation d'un compte de service pour surveiller un bucket crée un canal de notification dans le projet du compte de service.

Vous devez utiliser un compte de service existant ou en créer un et télécharger la clé privée associée.

Configurer gsutil pour utiliser le compte de service

Pour configurer gsutil afin qu'il utilise le compte de service, vous pouvez utiliser le SDK Google Cloud pour ajouter le compte de service en tant que compte avec identifiants. Il est ainsi possible de travailler avec les ressources de Google Cloud Platform, y compris la notification de modification d'objet. Après avoir ajouté les identifiants, toutes les commandes gsutil suivantes utiliseront les identifiants du compte de service.

Pour créer des identifiants basés sur le compte de service :

  1. Assurez-vous de disposer de la dernière version du SDK Cloud. Vous pouvez mettre à jour vos composants en exécutant la commande suivante :
    gcloud components update
    
  2. Utilisez la commande gcloud auth activate-service-account et indiquez l'adresse électronique ainsi que la clé privée du compte de service.
    gcloud auth activate-service-account service-account-email --key-file path/to/key.p12
    

    où :

    • service-account-email est l'adresse e-mail du compte de service, qui se présentera comme suit : 1234567890123-abcdefghijklmonpqrstuvwxz01234567@developer.gserviceaccount.com.
    • path/to/key.p12 est la clé qu'il vous a été demandé de télécharger lors de la création du compte de service. Si vous avez perdu la clé, vous pouvez revenir à la page des identifiants de la console Google Cloud Platform et générer une nouvelle clé.
  3. Confirmez que le compte de service est bien celui qui est actuellement authentifié.
    $ gcloud auth list
    Credentialed accounts:
    - 1234567890123-abcdefghijklmonpqrstuvwxz01234567@developer.gserviceaccount.com (active)
    

    Vous devez voir active au niveau des identifiants du compte de service. Toutes les commandes gsutil de notification d'objet que vous exécutez utilisent désormais les identifiants du compte de service.

Identifier un domaine pour recevoir des notifications

Les requêtes de surveillance n'aboutiront que si l'URL de notification correspond à un domaine inscrit sur la liste blanche du projet du canal de notification.

Pour ajouter un domaine à la liste blanche :

  1. Pour valider la propriété de votre domaine, appliquez le processus de vérification Search Console.
  2. Dans la console GCP, accédez à l'onglet "Validation de domaine" sur la page "Identifiants".

    Accéder à la page Identifiants

  3. Cliquez sur Ajouter un domaine.
  4. Dans la boîte de dialogue Configure webhook notifications for (Configurer des notifications Webhook pour), saisissez le domaine à valider.

    Boîte de dialogue "Configure webhook notifications" (Configurer des notifications Webhook)

  5. Cliquez sur Add domain (Ajouter un domaine).

    Pour résoudre les problèmes liés à la validation d'un domaine :

    • Le domaine doit être enregistré dans la Search Console à l'aide d'une URL https:// ou de la méthode de validation du fournisseur de nom de domaine.
    • Vérifiez que vous êtes propriétaire ou collaborateur du projet dans la console GCP (consultez la section Membres du projet et autorisations) et que vous êtes propriétaire du domaine qui recevra les notifications. Si vous n'êtes pas le propriétaire du domaine, contactez-le pour qu'il vous ajoute en tant que propriétaire confirmé (consultez la section Ajouter ou supprimer des propriétaires).
    • Vous pouvez utiliser l'explorateur d'API Google avec les outils pour les webmasters afin de répertorier les sites du domaine, mais surtout afin de savoir si la propriété siteUrl du domaine commence par https://.

Supprimer un canal de notification

Pour arrêter un canal de notification, vous pouvez utiliser la commande gsutil notification stopchannel, comme suit :

gsutil notification stopchannel ChannelId ResourceId

Tous les événements de notification correspondant à la paire identifiant de ressource/identifiant de canal spécifiée sont arrêtés. Les canaux actifs supplémentaires pour la même ressource ne seront pas affectés. Les identifiants de ressource et de canal peuvent se trouver dans la réponse à une requête de surveillance ou dans le corps des messages d'événements de notification.

Pour en savoir plus sur cette commande, exécutez la commande gsutil help notification stopchannel.

Voici un exemple de requête POST générée par gsutil pour arrêter un canal :

POST /storage/v1/channels/stop HTTP/1.1
Host: www.googleapis.com
Content-Length: 200
User-Agent: google-api-python-client/1.0
Content-Type: application/json
Authorization: Bearer oauth2_token

{
  "resourceId": "ResourceId",
  "id": "ChannelId"
}

Types de messages d'événements de notification

Synchronisation

Un événement de notification est envoyé lorsqu'un nouveau canal de notification est créé suite à l'envoi d'une requête de surveillance. Une fois l'événement de synchronisation reçu, toutes les modifications ultérieures apportées au bucket seront envoyées à l'URL de l'application configurée pour le canal.

La notification sera envoyée sous la forme d'une requête POST à l'URL d'application configurée. La requête n'ayant pas de corps, les métadonnées de notification de synchronisation sont contenues dans les en-têtes de la requête. Voici un exemple de requête de notification de synchronisation :

POST /ApplicationUrlPath
Accept: */*
Content-Type: application/json; charset="utf-8"
Content_Length: 0
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: sync
X-Goog-Resource-Uri: https://www.googleapis.com/storage/v1/b/BucketName/o?alt=json
Ajout, mise à jour ou suppression d'objet

Un événement de notification est envoyé lorsqu'un nouvel objet est ajouté à un bucket, que le contenu ou les métadonnées d'un objet existant sont modifiés ou qu'un objet est supprimé d'un bucket.

La notification est envoyée sous la forme d'une requête POST à l'URL d'application configurée. Le corps de la requête contient un message codé au format JSON, comme indiqué dans la requête de notification suivante :

POST /ApplicationUrlPath
Accept: */*
Content-Length: 1097
Content-Type: application/json; charset="utf-8"
Host: ApplicationUrlHost
X-Goog-Channel-Id: ChannelId
X-Goog-Channel-Token: ClientToken
X-Goog-Resource-Id: ResourceId
X-Goog-Resource-State: ResourceState
X-Goog-Resource-Uri: https://www.googleapis.com/storage/v1/b/BucketName/o?alt=json

{
 "kind": "storage#object",
 "id": "BucketName/ObjectName",
 "selfLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName",
 "name": "ObjectName",
 "bucket": "BucketName",
 "generation": "1367014943964000",
 "metageneration": "1",
 "contentType": "application/octet-stream",
 "updated": "2013-04-26T22:22:23.832Z",
 "size": "10",
 "md5Hash": "xHZY0QLVuYng2gnOQD90Yw==",
 "mediaLink": "https://www.googleapis.com/storage/v1/b/BucketName/o/ObjectName?generation=1367014943964000&alt=media",
 "owner": {
  "entity": "user-jane@gmail.com"
 },
 "crc32c": "C7+82w==",
 "etag": "COD2jMGv6bYCEAE="
}
ResourceState prend les valeurs suivantes :
  • exists, pour les ajouts et les mises à jour d'objets.
  • not_exists, pour les suppressions d'objets.

et où le contenu du message JSON contient la représentation actuelle de l'objet, telle que définie à la section Description de la ressource d'objet.

Fiabilité

La notification de modification d'objet tente de transmettre des notifications fiables à votre application. Sachez toutefois que les notifications peuvent être retardées indéfiniment et que la rapidité d'exécution n'est pas garantie. Il se peut que l'application ne soit pas toujours disponible, .c'est pourquoi les règles suivantes s'appliquent lors de l'envoi des notifications :

  • Si une tentative d'envoi de notification échoue, des tentatives supplémentaires sont effectuées. L'intervalle entre les tentatives d'envoi supplémentaires est déterminé par un algorithme d'intervalle exponentiel entre les tentatives avec un premier essai 30 secondes après l'échec initial. Les tentatives d'envoi suivantes sont effectuées selon des intervalles croissants, jusqu'à un maximum de 90 minutes. Notez que les intervalles entre les tentatives sont légèrement aléatoires et ne se produisent donc pas à des valeurs exponentielles exactes. Une fois l'intervalle maximum de 90 minutes atteint, les tentatives suivantes continuent toutes les 90 minutes pendant sept jours. Si la notification ne peut pas être transmise dans ce délai, elle est définitivement supprimée.
  • Si la notification ne parvient pas à l'application dans les 20 secondes ou si votre application répond par l'un des codes de réponse HTTP suivants, la tentative de d'envoi de notification est traitée comme un échec et fera l'objet d'une nouvelle tentative :
    • 500 Erreur interne au serveur.
    • 502 Passerelle incorrecte
    • 503 Service indisponible.
    • 504 Expiration du délai de la passerelle
  • Si votre application répond avec l'un des codes de réponse HTTP suivants, la tentative de notification est considérée comme réussie :
    • 102 Traitement en cours
    • 200 OK
    • 201 Créée
    • 202 Acceptée
    • 204 Aucun contenu
  • Tout autre code de réponse HTTP renvoyé par l'application est traité comme un échec permanent et ne fait pas l'objet d'une nouvelle tentative.

Exemple d'application cliente

Cette section explique comment créer une application cliente App Engine qui traite les événements de notification de modification.

La figure suivante illustre la chronologie des événements de base impliqués dans la réception d'une notification, de la création d'un bucket au traitement des événements de notification de modification associés :

Chronologie d'une notification de modification d'objet
Chronologie d'une notification de modification d'objet

L'exemple d'application contient une classe appelée MainPage. Lorsque l'utilisateur met à jour ou ajoute un objet au bucket, la classe MainPage traite l'événement de notification. Pour des raisons de simplicité, la méthode post qui effectue réellement le traitement enregistre simplement un message avec l'heure à laquelle la notification a été reçue. Vous pouvez remplacer ce code par votre logique de traitement actuelle. Si vous n'êtes pas encore à l'aise pour développer des applications App Engine, essayez de déployer un exemple d'application ou de suivre un tutoriel avant de continuer.

  1. Configurer l'application
    Créez le fichier de configuration app.yaml pour spécifier l'application cliente chargée de gérer les événements de notification de modification pour le bucket.
    application: <ApplicationId>
    version: 1
    runtime: python27
    api_version: 1
    threadsafe: true
    
    handlers:
    - url: /.*
      script: change_notification_client.app
    
  2. Créer l'application
    L'exemple suivant met en œuvre une application cliente pour la gestion des événements de notification des modifications pour un bucket. Nommez-la change_notification_client.py, puis déployez votre application :
    """Notification handling for Google Cloud Storage."""
    
    import json
    import logging
    
    import webapp2
    
    class MainPage(webapp2.RequestHandler):
      """Process notification events."""
      def get(self):
        logging.info("Get request to notification page.")
        self.response.write("Welcome to the notification app.")
    
      def post(self):  # pylint: disable-msg=C6409
        """Process the notification event.
    
        This method is invoked when the notification channel is first created with
        a sync event, and then subsequently every time an object is added to the
        bucket, updated (both content and metadata) or removed. It records the
        notification message in the log.
        """
    
        logging.debug(
            '%s\n\n%s',
            '\n'.join(['%s: %s' % x for x in self.request.headers.iteritems()]),
            self.request.body)
    
        # The following code is for demonstration. Replace
        # it with your own notification processing code.
    
        if 'X-Goog-Resource-State' in self.request.headers:
          resource_state = self.request.headers['X-Goog-Resource-State']
          if resource_state == 'sync':
            logging.info('Sync message received.')
          else:
            an_object = json.loads(self.request.body)
            bucket = an_object['bucket']
            object_name = an_object['name']
            logging.info('%s/%s %s', bucket, object_name, resource_state)
        else:
          logging.info("Other post.")
    
    logging.getLogger().setLevel(logging.DEBUG)
    app = webapp2.WSGIApplication([('/', MainPage)], debug=True)
    
  3. Accorder l'autorisation d'accès de l'application au bucket
    Si votre bucket appartient à un compte de service différent de celui de votre application App Engine, accordez au bucket le rôle PROPRIÉTAIRE de l'application en exécutant la commande suivante :
    gsutil acl ch -u ApplicationId@appspot.gserviceaccount.com:OWNER gs://BucketName
    
  4. Commencer à surveiller les modifications d'objets dans le bucket
    Créez un canal de notification pour votre application en surveillant le bucket avec gsutil :
    gsutil notification watchbucket ApplicationUrl gs://BucketName
    
    ApplicationUrl est l'URL de votre application App Engine, par exemple https://ApplicationId.appspot.com/.
  5. Tester l'application
    Pour voir si l'application fonctionne comme prévu, procédez comme suit :
    1. Pour vous assurer que l'application a été déployée et fonctionne correctement, exécutez la commande curl suivante :
      curl -X Post https://<ApplicationId>.appspot.com
      
      Si vous avez utilisé votre propre nom de domaine pour déployer l'application, utilisez-le à la place de appspot.com dans la commande précédente.
    2. Accédez à la page de journalisation de votre projet. Actualisez la liste des messages enregistrés, si nécessaire. Vérifiez que le message de journal émis par l'application est enregistré.
    3. Ajoutez un objet au bucket. Vous pouvez utiliser l'outil gsutil comme suit :
      gsutil cp ObjectName gs://BucketName/
      
      Cloud Storage notifie l'application, qui enregistre ensuite un message.
    4. Accédez à la page de journalisation de votre projet. Actualisez la liste des messages enregistrés et recherchez le message pour la copie d'objet.
  6. Supprimer le canal de notification
    Supprimez le canal de notification en indiquant les identifiants de canal et de ressource renvoyés lorsque vous avez utilisé la commande de notification pour surveiller le bucket.
    gsutil notification stopchannel <channel_id> <resource_identifier>
    

Haut de page

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.