Cloud Pub/Sub Notifications pour Cloud Storage

Vous trouverez sur cette page la présentation de Cloud Pub/Sub Notifications pour Cloud Storage. Pour apprendre à configurer et à utiliser cette fonctionnalité, consultez la page Enregistrer des modifications d'objets.

Présentation

Les notifications Cloud Pub/Sub envoient des informations concernant les modifications apportées aux objets de vos buckets à Cloud Pub/Sub. Ces informations sont ajoutées à un sujet Cloud Pub/Sub de votre choix sous forme de messages. Par exemple, vous pouvez suivre les créations et les suppressions d'objets dans votre bucket. Chaque notification contient des informations qui décrivent l'événement l'ayant déclenchée ainsi que l'objet modifié.

Vous pouvez envoyer des notifications à n'importe quel sujet Cloud Pub/Sub dans un projet pour lequel vous disposez des autorisations suffisantes. Une fois reçu par le sujet Cloud Pub/Sub, le message peut être envoyé à n'importe quel nombre d'abonnés au sujet. Consultez la section Prérequis pour découvrir comment associer vos buckets Cloud Storage à un sujet Cloud Pub/Sub.

Autres options de notification

S'abonner aux notifications Cloud Pub/Sub est un moyen polyvalent de déclencher des alertes et des actions en réponse à des modifications effectuées au sein d'un bucket. Les options suivantes sont également disponibles :

  • Cloud Functions : si vous souhaitez simplement déclencher une fonction légère et autonome en réponse à des événements sans avoir à gérer un sujet Cloud Pub/Sub, utilisez Cloud Functions. Ce service permet d'exécuter des fonctions JavaScript lorsqu'un objet de votre bucket est modifié. Notez que vos buckets doivent se trouver dans le même projet que Cloud Functions. Consultez le tutoriel associé pour découvrir un exemple d'utilisation de Cloud Functions avec Cloud Storage.

  • Notification de modification des objets : il s'agit d'une fonctionnalité distincte et plus ancienne de Cloud Storage, qui permet de générer des notifications. Elle envoie des messages HTTPS à une application cliente que vous avez configurée séparément. En règle générale, les notifications Cloud Pub/Sub sont moins coûteuses, plus faciles à utiliser et plus flexibles.

Configurations de notification

Une configuration de notification est une règle que vous associez à un bucket et qui spécifie les éléments suivants :

  • Le sujet Cloud Pub/Sub qui reçoit les notifications
  • Les événements qui déclenchent l'envoi d'une notification
  • Les informations contenues dans les notifications

Vous pouvez associer plusieurs configurations de notification à un bucket. Pour chaque événement, il est possible de définir jusqu'à 10 configurations déclenchant une notification.

Par exemple, si vous disposez d'une configuration de notification qui envoie des notifications de suppression à un sujet Cloud Pub/Sub, vous pouvez en ajouter une deuxième au bucket qui envoie des notifications de suppression à un autre sujet. Si vous essayez toutefois de créer plus de 10 configurations de notification de ce genre, vous obtenez une erreur. Outre ces configurations de notification, vous pouvez également créer des configurations qui envoient des notifications associées à d'autres événements (tels que la création d'objets) aux sujets Cloud Pub/Sub utilisés par les notifications de suppression ou à d'autres sujets.

Chaque configuration de notification est identifiée par un nombre entier, qui est renvoyé :

  • au moment de la création de la configuration de notification ;
  • lorsque vous répertoriez les configurations de notification associées à un bucket ;
  • dans l'attribut notificationConfig de chaque notification déclenchée par la configuration de notification.

Chaque création et suppression de configuration de notification incrémente le numéro de métagénération du bucket.

Types d'événements

La liste suivante répertorie les types d'événements actuellement compatibles avec Cloud Storage :

Type d'événement Description
OBJECT_FINALIZE Envoyé lorsqu'un objet (ou une nouvelle génération d'un objet existant) est bien créé dans le bucket. Cela inclut la copie ou la réécriture d'un objet existant. Les échecs d'importation ne génèrent pas cet événement.
OBJECT_METADATA_UPDATE Envoyé lorsque les métadonnées d'un objet existant sont modifiées.
OBJECT_DELETE Envoyé lorsqu'un objet a été définitivement supprimé. Cela inclut les objets écrasés ou supprimés dans le cadre de la configuration du cycle de vie du bucket. Pour les buckets sur lesquels la gestion des versions d'objets est activée, cet événement n'est pas envoyé lorsqu'un objet est archivé (voir OBJECT_ARCHIVE), même si l'archivage s'effectue via la méthode storage.objects.delete.
OBJECT_ARCHIVE Envoyé uniquement lorsque la gestion des versions d'objets est activée sur un bucket. Cet événement indique que la version en ligne d'un objet a été archivée (soit à la suite d'un archivage, soit parce qu'elle a été écrasée lors de l'importation d'un objet portant le même nom).

Écraser des objets

L'écrasement d'un objet existant par un autre objet portant le même nom déclenche deux événements distincts : OBJECT_FINALIZE pour la nouvelle version de l'objet et OBJECT_ARCHIVE ou OBJECT_DELETE pour l'objet écrasé. L'événement OBJECT_FINALIZE contient un attribut supplémentaire, overwroteGeneration, qui fournit le numéro de génération de l'objet écrasé. L'événement OBJECT_ARCHIVE ou OBJECT_DELETE contient un attribut supplémentaire, overwrittenByGeneration, qui fournit le numéro de génération du nouvel objet.

Format des notifications

Les notifications envoyées au sujet Cloud Pub/Sub comprennent deux parties :

  • Attributs : ensemble de paires valeur/clé décrivant l'événement.
  • Charge utile : chaîne contenant les métadonnées de l'objet modifié.

Attributs

Les attributs sont des paires valeur/clé présentes dans toutes les notifications que Cloud Storage envoie à votre sujet Cloud Pub/Sub. Les notifications comportent toujours l'ensemble de paires valeur/clé suivant, quelle que soit leur charge utile :

Nom de l'attribut Exemple Description
notificationConfig projects/_/buckets/foo/notificationConfigs/3 Identifiant de la configuration de notification qui a déclenché cette notification.
eventType OBJECT_FINALIZE Type d'événement qui vient de se produire. Consultez la section Types d'événements pour obtenir la liste des valeurs possibles.
payloadFormat JSON_API_V1 Format de la charge utile de l'objet. Consultez la section Charge utile pour obtenir la liste des valeurs possibles.
bucketId foo Nom du bucket qui contient l'objet modifié.
objectId bar Nom de l'objet modifié.
objectGeneration 123456 Numéro de génération de l'objet modifié.

Les notifications comportent parfois l'ensemble de paires valeur/clé suivant, quelle que soit leur charge utile :

Nom de l'attribut Exemple Description
overwrittenByGeneration 107458 Numéro de génération de l'objet qui a écrasé celui associé à cette notification. Cet attribut n'apparaît que dans les événements OBJECT_ARCHIVE ou OBJECT_DELETE en cas d'écrasement.
overwroteGeneration 352947 Numéro de génération de l'objet qui a été écrasé par celui associé à cette notification. Cet attribut n'apparaît que dans les événements OBJECT_FINALIZE en cas d'écrasement.

La paire valeur/clé suivante est obsolète. Elle n'apparaît pas pour les nouveaux abonnements et n'apparaîtra plus à compter du 1er juin 2018 :

Nom de l'attribut Exemple Description
Ressource projects/_/buckets/foo/objects/bar#123456 Chemin d'accès de l'objet Cloud Storage ayant été modifié.

En plus des attributs ci-dessus, les notifications peuvent contenir des attributs personnalisés. Ceux-ci sont définis lors de la création d'une configuration de notification, à l'aide de l'indicateur -m dans une commande gsutil notification ou de l'objet custom_attributes dans le corps d'une requête JSON POST notificationConfigs.

Charge utile

La charge utile est une chaîne contenant les métadonnées de l'objet modifié. Lorsque vous créez une configuration de notification, vous spécifiez un type de charge utile à inclure dans les notifications déclenchées par cette configuration. Vous pouvez spécifier les types de données suivants :

Type de charge utile Description
AUCUN Aucune charge n'est incluse dans la notification.
JSON_API_V1 La charge utile sera une chaîne UTF-8 contenant la représentation de ressource des métadonnées de l'objet.

Dans le cas des notifications OBJECT_DELETE, les métadonnées contenues dans la charge utile représentent les métadonnées de l'objet avant sa suppression, avec une propriété timeDeleted supplémentaire. Pour toutes les autres notifications, les métadonnées incluses dans la charge utile représentent les métadonnées de l'objet après sa modification.

Par exemple, supposons que vous disposiez d'une configuration de notification qui suive les événements OBJECT_METADATA_UPDATE. Si un utilisateur modifie la propriété contentType d'un objet en remplaçant binary/octet-stream par video/mp4, une notification OBJECT_METADATA_UPDATE est envoyée et les métadonnées de la charge incluent "contentType":"video/mp4".

Garanties de distribution

Lorsque vous ajoutez une configuration de notification, l'envoi par Cloud Storage de notifications associées à celle-ci peut prendre jusqu'à 30 secondes. Une fois ce processus lancé, Cloud Storage garantit une distribution "au moins une fois" à Cloud Pub/Sub. Cloud Pub/Sub offre également une distribution "au moins une fois" au destinataire, ce qui signifie que vous pouvez recevoir plusieurs messages avec plusieurs ID représentant le même événement Cloud Storage. Le délai de distribution n'est actuellement soumis à aucun contrat de niveau de service, mais les notifications sont généralement acheminées en quelques secondes. Dans de rares cas, la distribution des notifications peut prendre beaucoup plus de temps.

Les notifications ne sont pas nécessairement publiées dans l'ordre dans lequel Cloud Pub/Sub les reçoit. Si vous envisagez de modifier l'objet Cloud Storage en fonction d'une notification, nous vous recommandons d'utiliser son numéro de génération et son numéro de métagénération comme conditions préalables de votre requête de mise à jour.

Si l'envoi d'une notification à un sujet Cloud Pub/Sub ne cesse d'échouer, Cloud Storage peut la supprimer au bout de sept jours. Un échec de distribution peut se produire lorsque le sujet Cloud Pub/Sub n'existe plus, lorsque Cloud Storage n'a plus l'autorisation de publier des messages dans celui-ci, ou lorsque le projet qui le détient a dépassé son quota de publication.

Étapes suivantes

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

Envoyer des commentaires concernant…

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