Abonnement à des événements Object Storage

Ce tutoriel vous explique comment vous abonner à des événements Object Storage à l'aide de l'interface de ligne de commande IBM Cloud® Code Engine.

Souvent, dans les environnements distribués, vous avez besoin que vos applications ou vos travaux réagissent aux messages (événements) générés à partir d'autres composants, qui sont généralement appelés des producteurs d'événements. Avec Code Engine, vos applications ou vos travaux peuvent recevoir des événements d'intérêt grâce à un abonnement à des producteurs d'événements. Les informations relatives aux événements sont reçues sous forme de demandes HTTP POST pour les applications et sous forme de variables d'environnement pour les travaux.

Avant de commencer

Tous les utilisateurs Code Engine doivent avoir un compte de paiement à la carte. Les tutoriels peuvent entraîner des coûts. Utilisez l'estimateur de coût pour générer une estimation du coût en fonction de l'utilisation envisagée. Pour plus d'informations, voir Tarification Code Engine.

Détermination de votre compartiment et de votre région Object Storage

Le producteur d'événement Object Storage génère des événements en fonction des opérations sur des objets dans des compartiments IBM Cloud Object Storage.

Installez l'interface de ligne de commande du plug-in Object Storage.
```
ibmcloud plugin install cloud-object-storage
```
Créez une instance de ressource Object Storage. Par exemple, créez une ressource Object Storage nommée mycloud-object-storage qui utilise le plan de service IBM Cloud Lite.
```
ibmcloud resource service-instance-create mycloud-object-storage cloud-object-storage lite global
```
Affichez les détails de l'instance de ressource Object Storage que vous avez créée. Utilisez les détails pour obtenir le CRN (nom de ressource de cloud) depuis votre instance Object Storage. Le CRN identifie l'instance Object Storage que vous voulez utiliser. Il correspond à la valeur de la zone ID dans la sortie de la commande ibmcloud resource service-instance COS_INSTANCE_NAME.
```
ibmcloud resource service-instance mycloud-object-storage
```
Exemple de sortie
```
Name:                  mycloud-object-storage
ID:                    crn:v1:bluemix:public:cloud-object-storage:global:a/ab9d57f699655f028880abcd2ccdb524:910b727b-abcd-4a73-abcd-77c68bfeabcd::
GUID:                  910b727b-abcd-4a73-abcd-77c68bfeabcd
Location:              global
Service Name:          cloud-object-storage
Service Plan Name:     lite
Resource Group Name:   Default
State:                 active
Type:                  service_instance
Sub Type:
Created at:            2020-10-14T19:09:22Z
Created by:            user@us.ibm.com
Updated at:            2020-10-14T19:09:22Z
[...]
```
Si vous ne connaissez pas votre nom d'instance Object Storage, exécutez ibmcloud resource service-instances --service-name cloud-object-storage pour afficher la liste des instances Object Storage.

Pour plus d'informations sur les instances Object Storage, voir Initiation à IBM Cloud Object Storage.
Configurez votre numéro CRN Object Storage que vous avez trouvé à l'étape précédente pour spécifier une instance Object Storage à utiliser. Veillez à copier l'intégralité de l'ID qui commence par crn:. Dans cet exemple, l'option --force est utilisée pour forcer la configuration à utiliser le CRN spécifié, ce qui peut être utile s'il existe plusieurs instances Object Storage.
```
ibmcloud cos config crn --crn CRN --force
```
Exemple de sortie
```
Saving new Service Instance ID...
OK
Successfully stored your service instance ID.
```
Identifiez un compartiment auquel vous abonner. Pour afficher la liste des compartiments associés à votre instance Object Storage, exécutez la commande :
```
ibmcloud cos buckets
```
Pour créer un compartiment,
```
ibmcloud cos bucket-create -bucket BUCKET_NAME
```
Identifiez l'emplacement et le plan du compartiment Object Storage. Utilisez par exemple le compartiment mybucket.
```
ibmcloud cos bucket-location-get --bucket mybucket
```
Exemple de sortie
```
Details about bucket mybucket:
Region: us-south
Class: Standard
```

Votre compartiment Object Storage doit être un compartiment régional se trouvant dans la même région que votre projet Code Engine.

Affectation du rôle Gestionnaire de notifications à Code Engine

Pour pouvoir créer un abonnement Object Storage, vous devez affecter le rôle Notifications Manager (gestionnaire de notifications) dans un projet Code Engine. En tant que gestionnaire de notifications, Code Engine peut afficher, modifier et supprimer des notifications pour un compartiment Object Storage.

Seuls les administrateurs de compte peuvent affecter le rôle Gestionnaire de notifications.

Identifiez le projet Code Engine que vous souhaitez utiliser. Vous pouvez utiliser la commande ibmcloud ce project list pour afficher une liste de projets. Utilisez la commande ibmcloud ce project select pour sélectionner votre projet comme contexte actuel. Par exemple, pour sélectionner un projet nommé myproject
```
ibmcloud ce project select -n myproject
```

Affectez le rôle Gestionnaire de notifications avec la commande ibmcloud iam authorization-policy-create.

Par exemple, pour affecter le rôle de gestionnaire de notifications (Notifications Manager) à un projet nommé myproject pour une instance Object Storage nommée mycosinstance, exécutez :

ibmcloud iam authorization-policy-create codeengine cloud-object-storage "Notifications Manager" --source-service-instance-name PROJECT --target-service-instance-name COS-INSTANCE

Une fois que vous avez affecté le rôle de gestionnaire de notifications à votre projet, vous pouvez créer des abonnements Object Storage pour tous les compartiments régionaux de votre instance Object Storage qui se trouvent dans la même région que votre projet.

Le tableau suivant récapitule les options utilisées avec la commande iam authorization-policy-create dans cet exemple. Pour plus d'informations sur la commande et ses options, voir la commande ibmcloud iam authorization-policy-create.

iam authorization-policy-create command components
Option de commande	Description
`codeengine`	Service source qui peut obtenir une autorisation d'accès.
`cloud-object-storage`	Service cible auquel le service source peut être autorisé à accéder.
`Notifications Manager`	Rôles permettant d'accéder au service source.
`source-service-instance-name`	Nom du projet `codeengine` auquel vous voulez autoriser l'accès.
`target-service-instance-name`	Nom de l'instance `cloud-object-storage` à laquelle vous voulez accéder.

Vérifiez que le rôle Gestionnaire de notifications est défini.

ibmcloud iam authorization-policies

Exemple de sortie

ID:                        abcd1234-a123-b456-bdd9-849e337c4460
Source service name:       codeengine
Source service instance:   1234abcd-b456-c789-a7c5-ef82e56fb24c
Target service name:       cloud-object-storage
Target service instance:   a1b2c3d4-cbad-567a-8cea-77c68bfe97c9
Roles:                     Notifications Manager

Créez votre application (ou votre travail)

Alors que les évènements peuvent être utilisés pour déclencher des applications ou des travaux, ce tutoriel utilise une application.

Créez une application nommée cos-app avec la commande ibmcloud ce app create en utilisant une image portant la désignation cos-listen. Cette application consigne chaque événement lorsqu'il se produit. Cette image est issue de cos-listen.go, disponible dans le dépôt « Samples for IBM Cloud Code Engine » GitHub.

ibmcloud ce app create --name cos-app --image icr.io/codeengine/cos-listen

Exécutez ibmcloud ce application get --name cos-app pour vous assurer que votre application est à l'état Ready. L'application est à l'état prêt si le récapitulatif de statut indique que celle-ci a été déployée avec succès.

Pour plus d'informations sur cette application, consultez le fichier « readme » de IBM Cloud Object Storage.

Créer un abonnement

Une fois votre application prête, vous pouvez créer un abonnement Object Storage avec la commande ibmcloud ce sub cos create pour pouvoir commencer à recevoir des événements Object Storage.

Par exemple, créez un abonnement Object Storage nommé cos-sub. Cet abonnement transmet tout type d'opération de compartiment du compartiment mybucket à une application appelée cos-app.

ibmcloud ce sub cos create --name cos-sub --destination cos-app --bucket mybucket --event-type all

Exécutez la commande ibmcloud ce sub cos get -n cos-sub pour rechercher des informations sur votre abonnement.

Exemple de sortie

Par défaut, la ibmcloud ce sub cos get commande renvoie deux éléments. La première partie inclut des informations relatives à l'abonnement Object Storage, telles qu'un nom d'abonnement, une destination, un préfixe, un suffixe et un type d'événement. La seconde inclut des informations d'événement liées aux ressources concernant l'abonnement Object Storage qui peuvent être utilisées à des fins de débogage. Par défaut, les informations sur les événements sont disponibles pendant 1 heure après leur survenue.

Getting COS event subscription 'cos-sub'...
OK
Name:          cos-sub
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m16s
Created:       2021-02-01T13:11:31-05:00
Destination:  App:cos-app
Bucket:       mybucket
EventType:    all
Ready:        true
Conditions:
    Type            OK    Age  Reason
    CosConfigured   true  38s
    Ready           true  38s
    ReadyForEvents  true  38s
    SinkProvided    true  38s
Events:
    Type    Reason          Age  Source                Messages
    Normal  CosSourceReady  39s  cossource-controller  CosSource is ready

Par défaut, la commande subscription cos create vérifie d'abord si l'application de destination existe. Si la vérification de la destination échoue car le nom d'application que vous avez fourni n'existe pas dans votre projet, la commande subscription cos create renvoie une erreur. Si vous voulez créer un abonnement sans créer d'abord l'application, utilisez l'option --force. Avec l'option --force, la commande ignore l'étape de vérification de la destination. Notez que la zone Ready de l'abonnement affiche false jusqu'à ce que l'application de destination soit créée. Ensuite, l'abonnement passe automatiquement à l'état Ready: true.

Après la création de l'abonnement mais avant la transmission des résultats via la commande subscription cos create, la commande subscription cos create demande régulièrement à l'abonnement son statut pour vérifier qu'il est prêt. Cette interrogation continue de l'état dure par défaut 15 secondes avant d'arriver à expiration. Si l'état de l'abonnement affiche Ready:true, un succès est renvoyé, sinon une erreur est consignée. Vous pouvez modifier le délai d'attente de la commande subscription cos create avant le dépassement de délai avec l'option --wait-timeout. Vous pouvez également ignorer l'étape d'interrogation de l'état en définissant l'option --no-wait sur false.

Pour plus d'informations sur les en-têtes et le corps, voir Informations relatives aux en-têtes et au corps HTTP pour les événements.

Notez que les abonnements peuvent affecter la manière dont une application est mise à l'échelle. Pour plus d'informations, voir Configuration de la mise à l'échelle d'application.

Test de votre abonnement

Téléchargez un fichier .txt dans votre compartiment. Par exemple, vous pouvez utiliser la commande ibmcloud cos object-put pour télécharger l'objet sample.txt dans un compartiment pour lequel le paramètre sample a la valeur --key.
```
ibmcloud cos object-put --bucket mybucket --key sample --body sample.txt
```
Affichez l'événement traité à l'aide de la commande ibmcloud ce app logs.
```
ibmcloud ce app logs --name cos-app
```
Exemple de sortie

Cette commande renvoie des informations de journal qui incluent des informations sur l'événement transmis à votre application de destination. Dans la sortie suivante, vous pouvez voir qu'une opération d'Write a été effectuée sur l'objet sample dans le compartiment nommé mybucket.
```
Body: {"bucket":"mybucket","endpoint":"","key":"sample","notification":{"bucket_name":"mybucket","content_type":"text/plain","event_type":"Object:Write","format":"2.0","object_length":"1960","object_name":"sample","request_id":"103dd6f7-dd7b-4f49-86db-c2ff4b678b0a","request_time":"2021-02-11T16:57:42.373Z"},"operation":"Object:Write"}
```

Mise à jour de votre abonnement Object Storage

Maintenant que vous savez que votre abonnement Object Storage a été créé et que l'abonnement Object Storage est prêt à traiter des événements, vous pouvez mettre à jour l'abonnement Object Storage à l'aide de la commande ibmcloud ce sub cos update. Par exemple, vous pouvez modifier votre abonnement pour qu'il s'exécute uniquement lorsque des opérations spécifiques sont effectuées sur un sous-ensemble d'objets dans le compartiment.

Mettez à jour l'abonnement Object Storage pour transmettre les événements uniquement lorsque des opérations delete (suppression) sont effectuées sur des fichiers dont le préfixe de nom est test.
```
ibmcloud ce sub cos update --name cos-sub --event-type delete --prefix test
```

Exécutez la commande ibmcloud ce sub cos get pour rechercher des informations sur votre abonnement.

ibmcloud ce sub cos get --name cos-sub

Exemple de sortie

Dans la sortie ci-dessous, vous constatez que les valeurs mises à jour de Prefix et EventType s'affichent.

Getting COS event subscription 'cos-sub'...
OK
Name:          cos-sub
ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f
Project Name:  myproject
Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111
Age:           4m16s
Created:       2021-02-01T13:11:31-05:00
Destination:  App:cos-app
Bucket:       mybucket
EventType:    delete
Prefix:       test
Ready:        true
Conditions:
    Type            OK    Age  Reason
    CosConfigured   true  24m
    Ready           true  24m
    ReadyForEvents  true  24m
    SinkProvided    true  24m
Events:
    Type    Reason          Age               Source                Messages
    Normal  CosSourceReady  9s (x2 over 24m)  cossource-controller  CosSource is ready

Supprimez un objet de votre compartiment qui possède le préfixe test. Par exemple, supprimez un fichier dont le nom (ou la clé) est test2.txt. Vous pouvez utiliser la commande ibmcloud cos object-delete pour supprimer un objet de votre compartiment ou utiliser la console Object Storage.
Affichez l'événement traité à l'aide de la commande ibmcloud ce app logs.
```
ibmcloud ce app logs --name cos-app
```
Exemple de sortie

Cette commande renvoie des informations de journal qui incluent des informations sur l'événement transmis à votre application de destination. Dans la sortie suivante, vous pouvez voir qu'une opération d'Delete a été effectuée sur l'objet .txt dans le compartiment nommé mybucket.
```
Body: {"bucket":"mybucket","endpoint":"",""key":"test2.txt","notification":{"bucket_name":"mybucket","event_type":"Object:Delete","format":"2.0","object_length":"41","object_name":"test2.txt","request_id":"c1099857-f1f3-4d74-9ac4-8d374582f77d","request_time":"2021-09-15T15:22:01.205Z"},"operation":"Object:Delete"}
```

Tutoriel sur le nettoyage de Object Storage

Prêt à supprimer votre abonnement Object Storage et votre application ? Vous pouvez utiliser les commandes ibmcloud ce app delete et ibmcloud ce sub cos delete.

Pour retirer votre abonnement, entrez :

ibmcloud ce sub cos delete --name cos-sub

Pour retirer votre application, entrez :

ibmcloud ce app delete --name cos-app

Prêt à supprimer votre compartiment et instance de service Object Storage ? Vous pouvez utiliser la commande ibmcloud cos bucket-delete pour supprimer le compartiment. Pour supprimer votre instance de service Object Storage, utilisez la commande ibmcloud resource service-instance-delete.