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.
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.
- Attribuez au compte de service le rôle IAM
roles.pubsub.publisher
pour le sujet Pub/Sub souhaité.
- Attribuez au compte de service le rôle IAM
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 transferttopic-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 transferttopic-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 transferttopic-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 :
- Envoyer un e-mail
- Démarrer une tâche Dataflow
- Enregistrer des métadonnées dans Cloud SQL
- Enregistrer des métadonnées dans Spanner
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.