Gérer les enrichissements d'objets

Une fois que vous avez configuré les enrichissements d'objets, Cloud Storage évalue les objets éligibles de manière asynchrone et associe les métadonnées d'enrichissement directement à vos objets stockés.

Cette page explique comment inspecter les métadonnées de contexte de base, récupérer les charges utiles de données étendues, supprimer les enrichissements des objets et surveiller la progression du traitement dans Cloud Monitoring.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour afficher, récupérer et supprimer des enrichissements d'objets, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre bucket ou votre projet :

• Afficher les métadonnées de base des enrichissements d'objets : Lecteur des objets Storage (roles/storage.objectViewer)
• Récupérer les données étendues des enrichissements d'objets : Utilisateur d'objets Storage (roles/storage.objectUser)
• Supprimer les enrichissements d'objets lors de la réécriture d'objets : Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour afficher, récupérer et supprimer les enrichissements d'objets. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour afficher, récupérer et supprimer des enrichissements d'objets :

• Afficher les métadonnées de contexte des enrichissements d'objets de base : storage.objects.get
• Récupérez les données étendues des enrichissements d'objets : storage.objects.viewFullContext
• Ignorer les enrichissements d'objets lors de la réécriture d'objets :
  • storage.objects.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.update

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Afficher les enrichissements d'objets

Cloud Storage associe les métadonnées d'enrichissement directement à vos objets en tant que contextes d'objet gérés par Google sous la propriété contexts.custom. Chaque modèle utilise une clé réservée précédée du préfixe google:annotation: (par exemple, google:annotation:label-detector-v1 ou google:annotation:face-detector-v1).

Cloud Storage organise les données d'enrichissement en deux niveaux :

• Métadonnées de contexte : contient la clé de contexte, l'état d'exécution du modèle (value), les codes temporels et l'URL du type protobuf. Les opérations d'objet standards describe et get renvoient ces métadonnées.
• Données étendues (preview) : contient la charge utile d'enrichissement JSON structurée complète (jusqu'à 128 Kio). Cette charge utile inclut des détails tels que les coordonnées des polygones de délimitation, les scores de confiance de la classification, les expressions faciales et les évaluations de sécurité.

Afficher les métadonnées de contexte de base

Pour vérifier quels modèles ont traité un objet et afficher les métadonnées de contexte de base, utilisez la console Cloud de Confiance ou l'API JSON :

Récupérer des données étendues

Pour récupérer l'intégralité des données d'enrichissement structurées (telles que les cadres de délimitation, les polygones de délimitation, les étiquettes ou les visages détectés), appelez la méthode viewFullContext (preview) à l'aide de l'API JSON.

1. Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

2. Utilisez cURL pour envoyer une requête viewFullContext à l'API JSON, en spécifiant la clé de contexte du modèle que vous souhaitez inspecter :

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Accept: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

   Où :

   • BUCKET_NAME est le nom du bucket contenant l'objet. Exemple :my-bucket
   • OBJECT_NAME correspond au nom encodé au format URL de l'objet. Exemple :image.jpg
   • CONTEXT_KEY est la clé de contexte du modèle. Exemple : google:annotation:label-detector-v1.

   La réponse contient la structure extendedData avec la charge utile d'enrichissement complète :

   {
     "kind": "storage#objectFullContext",
     "type": "CUSTOM",
     "key": "google:annotation:label-detector-v1",
     "value": "SUCCESS",
     "createTime": "2026-09-29T17:20:00.000Z",
     "updateTime": "2026-09-29T17:20:00.000Z",
     "extendedData": {
       "@type": "type.googleapis.com/google.protobuf.Struct",
       "modelName": "label-detector",
       "modelVersion": "v1",
       "labelAnnotationGroup": {
         "labelAnnotations": [
           {
             "description": "Night",
             "knowledgeGraphId": "/m/01d74z",
             "score": 0.92,
             "topicality": 0.19
           }
         ]
       }
     }
   }
   

Pour obtenir des schémas et des champs JSON détaillés pour chaque modèle, consultez Modèles et schémas compatibles.

Supprimer les enrichissements d'objets

Si vous devez respecter des règles de conservation des données ou si vous n'avez plus besoin des métadonnées d'enrichissement, vous pouvez les supprimer de vos objets.

Étant donné que Google gère les clés de contexte commençant par le préfixe google:, vous ne pouvez pas les modifier ni les supprimer à l'aide des méthodes de mise à jour des métadonnées standards. Au lieu de cela, vous les supprimez lors d'une opération de réécriture, de copie ou de composition d'objet en spécifiant le paramètre dropContextGroups=custom, qui supprime tous les contextes d'objet de l'objet.

Pour supprimer les contextes d'objet (y compris les enrichissements d'objets) lors de la réécriture d'un objet à l'aide de l'API JSON, procédez comme suit :

1. Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

2. Utilisez cURL pour appeler l'API JSON avec une requête de réécriture d'objet POST et le paramètre de requête dropContextGroups=custom :

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Length: 0" \
     "https://storage.s3nsapis.fr/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"

   Où :

   • SOURCE_BUCKET correspond au nom du bucket contenant l'objet source. Exemple :my-source-bucket
   • SOURCE_OBJECT correspond au nom encodé au format URL de l'objet source. Exemple :image.jpg
   • DESTINATION_BUCKET est le nom du bucket de destination (peut correspondre au bucket source). Exemple : my-source-bucket.
   • DESTINATION_OBJECT correspond au nom encodé au format URL de l'objet de destination (peut correspondre à l'objet source). Exemple : image.jpg.

Pour gérer et supprimer des contextes sur des milliards d'objets, consultez Gérer des contextes d'objets de manière groupée.

Surveiller les métriques d'enrichissement d'objets

Vous pouvez suivre le débit de traitement de l'enrichissement, les objets en attente et le nombre d'exécutions de modèles à l'aide de Cloud Monitoring. Cloud Storage exporte les métriques suivantes sous l'espace de noms storage.googleapis.com sur la ressource surveillée gcs_bucket :

Type de métrique (précédé de storage.googleapis.com/)	Genre et type	Description et libellés
auto_annotate/operations/pending_objects	GAUGE, INT64	Nombre total d'objets en attente d'enrichissement dans le bucket. Échantillonnage toutes les 300 secondes.
auto_annotate/operations/processed_object_count	DELTA, INT64	Nombre total d'objets traités par les enrichissements d'objets pendant la période. Échantillonnage toutes les 300 secondes.
auto_annotate/operations/model_count	DELTA, INT64	Nombre total de modèles exécutés dans le bucket au cours de la période, regroupés par model_name, model_version et status (par exemple, SUCCESS ou FAILURE).
auto_annotate/operations/request_count	DELTA, INT64	Nombre total d'appels d'API effectués pendant la période, regroupés par method et response_code.
auto_annotate/storage/annotated_objects	GAUGE, INT64	Instantané quotidien du nombre total d'objets du bucket pour lesquels des enrichissements ont été générés, regroupés par type et data_locations.
auto_annotate/storage/model_outputs	GAUGE, INT64	Instantané quotidien du nombre total de sorties de modèle stockées dans le bucket, regroupées par model_name, model_version, status, type et data_locations.

Pour en savoir plus sur l'interrogation des métriques et la configuration des alertes, consultez Métriques Cloud Monitoring pour Cloud Storage et Créer des graphiques avec l'explorateur de métriques.

Étapes suivantes

• Configurer les enrichissements d'objets
• Analysez les enrichissements d'objets avec SQL dans BigQuery.
• Consultez les modèles et les schémas de sortie compatibles.
• Consultez la présentation des enrichissements d'objets.
• Examinez la ressource et les méthodes de l'API JSON featureConfigs.
• En savoir plus sur les contextes d'objet
• Gérez des objets de manière groupée avec les opérations de stockage par lot.