Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 aux objets stockés.

Cette page explique comment inspecter les métadonnées de contexte de base, récupérer des charges utiles de données étendues, supprimer des enrichissements d'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 les enrichissements d'objets, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre bucket ou projet :

Afficher les métadonnées d'enrichissement d'objets de base : lecteur des objets Storage (roles/storage.objectViewer)
Récupérer les données étendues d'enrichissement 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 les enrichissements d'objets :

Afficher les métadonnées de contexte d'enrichissement d'objets de base : storage.objects.get
Récupérer les données étendues d'enrichissement d'objets : storage.objects.viewFullContext
Supprimer 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 contexts.custom propriété. Chaque modèle utilise une clé réservée préfixée par 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 : contiennent la clé de contexte, l'état d'exécution du modèle (value), les horodatages et l'URL du type protobuf. Les opérations describe et get d'objet standard renvoient ces métadonnées.
Données étendues (preview) : contiennent la charge utile d'enrichissement JSON structurée complète (jusqu'à 128 Kio). Cette charge utile inclut des informations telles que les coordonnées du polygone 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 Google Cloud console ou l'API JSON :

Console

Dans la Google Cloud console, accédez à la page Buckets de Cloud Storage.

Accéder à la page "Buckets"
Dans la liste des buckets, cliquez sur le nom du bucket contenant l'objet que vous souhaitez inspecter.

Dans le tableau Objets , la colonne Contextes personnalisés affiche une puce pour chaque modèle ayant traité un objet (Content Safety, Face Detector, Label Detector, Object Detector ou PDF Classification).
Pour inspecter un objet individuel, cliquez sur son nom.
Sur la page Détails de l'objet, accédez au champ Contextes personnalisés. Si le champ comporte plusieurs puces, cliquez sur pour développer la ligne.
Pointez sur une puce de modèle ou cliquez dessus pour afficher ses métadonnées de contexte de base :
- Clé de contexte : clé de modèle réservée, telle que google:annotation:label-detector-v1.
- Valeur de contexte : état d'exécution du modèle (SUCCESS ou FAILURE).
- Heure de création et Heure de dernière modification : horodatages indiquant quand Cloud Storage a créé et mis à jour l'enrichissement pour la dernière fois.
- Afficher le hub de configuration : ouvre la page Enrichissements d'objets. Lorsque vous affichez une puce à partir du tableau Objets du bucket, vous pouvez également cliquer sur Filtrer les contextes pour filtrer les objets du bucket par ce contexte.

API JSON

Vous devez installer et initialiser la gcloud CLI installée et initialisée, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

Utilisez cURL pour envoyer une requête Objects: get avec le paramètre de requête projection=full à l'API JSON :

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?projection=full"

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.

La réponse renvoie la structure contexts.custom :

{
  "kind": "storage#object",
  "id": "my-bucket/image.jpg/1700000000000000",
  "name": "image.jpg",
  "bucket": "my-bucket",
  "contexts": {
    "custom": {
      "google:annotation:label-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

Le champ value indique l'état d'exécution du modèle pour l'objet, tel que SUCCESS ou FAILURE.

Récupérer des données étendues

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

Vous devez installer et initialiser la gcloud CLI installée et initialisée, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.

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.googleapis.com/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'objets 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 :

Vous devez installer et initialiser la gcloud CLI installée et initialisée, ce qui vous permet de générer un jeton d'accès pour l'en-tête Authorization.
Utilisez cURL pour appeler l'API JSON avec une POST requête d'objet de réécriture et le dropContextGroups=custom paramètre de requête :
```
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Length: 0" \
  "https://storage.googleapis.com/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"
```
Où :
- SOURCE_BUCKET est le 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 les contextes d'objet en bloc.

Surveiller les métriques d'enrichissement d'objets

Vous pouvez suivre le débit de traitement des enrichissements, 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' storage.googleapis.com espace de noms sur la gcs_bucket ressource surveillée :

Type de métrique (préfixé par `storage.googleapis.com/`)	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 pendant 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 dans le 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èles 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 d'alertes, consultez Métriques Cloud Monitoring pour Cloud Storage et Créer des graphiques avec l'explorateur de métriques.