Cette page a été traduite par l'API Cloud Translation.

Notifications Pub/Sub

Après avoir effectué un transfert du service de transfert de stockage, vous pouvez avoir besoin de démarrer une nouvelle tâche, de gérer une erreur rencontrée lors d'un transfert ou d'enregistrer un transfert dans un journal. Pub/Sub fournit une file d'attente à laquelle vos programmes peuvent s'abonner pour recevoir des messages une fois un transfert terminé. Cela vous permet de réutiliser le code et de programmer les étapes suivantes en fonction de l'état d'un transfert.

Pour plus d'informations sur Pub/Sub, consultez la page Qu'est-ce que Pub/Sub ?

Prérequis

Avant de pouvoir utiliser cette fonctionnalité, procédez comme suit :

Activez l'API Pub/Sub pour le projet recevant les notifications Pub/Sub.

Activer l'API
Disposez d'un sujet Pub/Sub existant auquel vous souhaitez envoyer des notifications.
Obtenez l'adresse e-mail du compte de service associé au projet contenant votre bucket de service de transfert de stockage.
1. Attribuez au compte de service le rôle IAM roles.pubsub.publisher pour le sujet Pub/Sub souhaité.
Remarque : Il peut s'écouler quelques secondes entre l'attribution du rôle et son application à votre compte de service. Si vous accordez cette autorisation de manière automatisée, attendez 30 secondes avant de configurer le service de transfert de stockage.

Configurer les paramètres de notification

Pour configurer les paramètres de notification Pub/Sub du service de transfert de stockage, vous utilisez l'API transferJobs du service de transfert de stockage pour créer un message NotificationConfig. Le sujet recevra des notifications sur le canal Pub/Sub configuré.

Spécifiez les éléments suivants dans votre message NotificationConfig :

Le sujet Pub/Sub auquel envoyer des notifications
Le format du message ("JSON" ou "NONE")
Les types d'événements souhaités, correspondant aux TransferOperation.Statuses terminés :
- "TRANSFER_OPERATION_SUCCESS"
- "TRANSFER_OPERATION_FAILED"
- "TRANSFER_OPERATION_ABORTED"

Voici un exemple de message NotificationConfig :

{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_SUCCESS"],
     "payloadFormat": "JSON"
   },
   ...
}

Remplacez l'élément suivant :

project-id : ID de projet Google Cloud du transfert
topic-id : nom du sujet Pub/Sub

Pour en savoir plus, consultez la section spécification REST Pub Sub du service de transfert de stockage.

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 clé/valeur contenues dans toutes les notifications envoyées par le service de transfert de stockage à votre sujet Pub/Sub. Les notifications comportent toujours l'ensemble de paires valeur/clé suivant, quelle que soit leur charge utile.

Pour plus d'informations sur le format des messages Pub/Sub, consultez la page PubsubMessage.

Nom de l'attribut	Exemple	Description
`eventType`	`TRANSFER_OPERATION_SUCCESS`	État de `TransferOperation`, depuis `NotificationConfig.EventType`
`payloadFormat`	`"JSON"`	Format du message, `"JSON"` ou `"NONE"`. Depuis `NotificationConfig.PayloadFormat`.
`projectId`	`project-3`	ID du projet hôte de transfert.
`transferJobName`	`transferJobs/123`	Nom de la tâche de transfert.
`transferOperationName`	`transferOperations/456`	Nom de l'opération de transfert.

Charge utile

La charge utile contient les métadonnées TransferOperation. 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 charge utile suivants :

Type de charge utile	Description
AUCUN	Aucune charge n'est incluse dans la notification.
JSON	La charge utile est formatée comme une réponse JSON, dans l'application/json.

Exemples de configurations de notification Pub/Sub

Recevoir des notifications uniquement pour les transferts ayant échoué

Pour ne recevoir des messages que pour les transferts ayant échoué, envoyez un TransferJob avec une NotificationConfig qui filtre uniquement les transferts ayant échoué :

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_FAILED"],
     "payloadFormat: "JSON"
   },
   ...
}

Remplacez l'élément suivant :

project-id : ID de projet Google Cloud du transfert
topic-id : nom du sujet Pub/Sub

Recevoir des notifications pour tous les transferts terminés

Pour recevoir des notifications pour tous les transferts terminés, quel que soit leur état, envoyez un TransferJob avec une NotificationConfig sans filtres EventType :

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "payloadFormat: "JSON"
   },
   ...
}

Remplacez l'élément suivant :

project-id : ID de projet Google Cloud du transfert
topic-id : nom du sujet Pub/Sub

Réaliser des actions arbitraires sur un transfert

Pour réaliser une action arbitraire, créez une notification Pub/Sub à l'aide d'une fonction Cloud avec un déclencheur Pub/Sub associé à une fonction Cloud d'arrière-plan. Pour plus d'informations, consultez le tutoriel sur Cloud Pub/Sub.

Exemples d'actions arbitraires :

Garanties de distribution

Le service de transfert de stockage envoie des notifications pour toutes les TransferOperations démarrées après l'ajout d'une configuration de notification et garantit au moins une distribution à 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 de service de transfert de stockage.

Les notifications ne sont pas nécessairement publiées dans l'ordre dans lequel Pub/Sub les reçoit.

Si l'envoi d'une notification à un sujet Pub/Sub ne cesse d'échouer, le service de transfert de stockage peut la supprimer au bout de sept jours. Un échec de distribution peut se produire lorsque le sujet Pub/Sub n'existe plus, lorsque le service de transfert de stockage 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.