Notifications Pub/Sub pour Cloud Storage

Configuration

Cette page présente les notifications Pub/Sub pour Cloud Storage.

Présentation

Les notifications Pub/Sub envoient des informations concernant les modifications apportées aux objets de vos buckets à Pub/Sub. Ces informations sont ajoutées à un sujet 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 Pub/Sub dans un projet pour lequel vous disposez des autorisations suffisantes. Une fois la notification reçue par le sujet Pub/Sub, le message associé peut être transmis aux abonnés du sujet. Consultez la section Prérequis pour découvrir comment associer vos buckets Cloud Storage à un sujet Pub/Sub.

Autres options de notification

L'abonnement aux notifications 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 Run 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 Pub/Sub, utilisez Cloud Run Functions. Cloud Run Functions vous permet d'exécuter des fonctions C#, Go, Java, Node.js, Python, PHP et Ruby lorsqu'un objet de votre bucket est modifié. Notez que votre bucket doit se trouver dans le même projet que Cloud Run Functions. Consultez le tutoriel associé pour découvrir un exemple d'utilisation de Cloud Run Functions avec Cloud Storage.

  • Notification de modification d'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. Cette fonctionnalité n'est généralement pas recommandée, car les notifications 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 dans Pub/Sub qui reçoit des 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. Un bucket peut avoir jusqu'à 100 configurations de notification au total et jusqu'à 10 configurations de notification déclenchant un événement spécifique.

Par exemple, si vous disposez d'une configuration de notification qui envoie des notifications de suppression à un sujet 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 Pub/Sub utilisés pour les notifications de suppression ou pour 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énement

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, la réécriture ou la restauration 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 remplacés ou supprimés dans le cadre de la configuration du cycle de vie du bucket. Cela n'inclut pas les objets qui sont obsolètes (voir OBJECT_ARCHIVE) ni les importations en plusieurs parties annulées.
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 est devenue obsolète (soit parce qu'elle a été explicitement rendue obsolète, soit parce qu'elle a été remplacée lors de l'importation d'un objet portant le même nom).

Pour les autres événements Cloud Storage, tels que les opérations de bucket ou les lectures d'objets, vous pouvez activer le type de journal d'audit approprié dans Cloud Audit Logs et acheminer les journaux d'audit vers Pub/Sub à l'aide d'un filtre.

Remplacer des objets

Le remplacement d'un objet existant par un nouvel 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 remplacé. L'événement OBJECT_FINALIZE contient un attribut supplémentaire, overwroteGeneration, qui indique le numéro de génération de l'objet qui a été remplacé. L'événement OBJECT_ARCHIVE ou OBJECT_DELETE contient un attribut supplémentaire, overwrittenByGeneration, qui indique le numéro de génération du nouvel objet.

Format des notifications

Les notifications envoyées au sujet 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 Pub/Sub. Les notifications comportent toujours l'ensemble de paires valeur/clé suivant, quelle que soit leur charge utile.

Nom d'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é.
eventTime 2021-01-15T01:30:15.01Z Heure de l'événement, exprimée au format RFC 3339.

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

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

Outre les attributs mentionnés ci-dessus, une configuration de notification peut comporter jusqu'à 10 attributs personnalisés. Les attributs personnalisés sont définis lors de la création d'une configuration de notification, à l'aide de l'option --custom-attributes dans une commande gcloud storage 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" à Pub/Sub. 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.

Les notifications ne sont pas nécessairement publiées dans l'ordre dans lequel 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 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 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