Gestisci gli enrichment degli oggetti

Dopo aver configurato gli arricchimenti degli oggetti, Cloud Storage valuta gli oggetti idonei in modo asincrono e allega i metadati di arricchimento direttamente agli oggetti archiviati.

In questa pagina viene spiegato come ispezionare i metadati di contesto di base, recuperare i payload dei dati estesi, eliminare gli arricchimenti dagli oggetti e monitorare l'avanzamento dell'elaborazione in Cloud Monitoring.

Ottieni i ruoli richiesti

Per ottenere le autorizzazioni necessarie per visualizzare, recuperare ed eliminare gli arricchimenti degli oggetti, chiedi all'amministratore di concederti i seguenti ruoli IAM sul bucket o sul progetto:

  • Visualizza i metadati di base degli arricchimenti degli oggetti: Storage Object Viewer (roles/storage.objectViewer)
  • Recupera i dati estesi degli enrichment degli oggetti: Storage Object User (roles/storage.objectUser)
  • Elimina gli enrichment degli oggetti durante la riscrittura degli oggetti: Storage Object Admin (roles/storage.objectAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per visualizzare, recuperare ed eliminare gli arricchimenti degli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per visualizzare, recuperare ed eliminare gli arricchimenti degli oggetti sono necessarie le seguenti autorizzazioni:

  • Visualizza i metadati di contesto di base degli arricchimenti degli oggetti: storage.objects.get
  • Recupera i dati estesi degli enrichment degli oggetti: storage.objects.viewFullContext
  • Ignora gli enrichment degli oggetti durante la riscrittura degli oggetti:
    • storage.objects.get
    • storage.objects.create
    • storage.objects.delete
    • storage.objects.update

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Visualizza gli enrichment degli oggetti

Cloud Storage allega i metadati di arricchimento direttamente agli oggetti come contesti degli oggetti gestiti da Google nella proprietà contexts.custom. Ogni modello utilizza una chiave riservata con prefisso google:annotation: (ad esempio, google:annotation:label-detector-v1 o google:annotation:face-detector-v1).

Cloud Storage organizza i dati di arricchimento in due livelli:

  • Metadati di contesto: contengono la chiave di contesto, lo stato di esecuzione del modello (value), i timestamp e l'URL del tipo di protobuf. Le operazioni standard sugli oggetti describe e get restituiscono questi metadati.
  • Dati estesi (anteprima): contiene il payload di arricchimento JSON strutturato completo (fino a 128 KiB). Questo payload include dettagli come le coordinate del poligono di delimitazione, i punteggi di affidabilità della classificazione, le espressioni facciali e le valutazioni di sicurezza.

Visualizza i metadati di contesto di base

Per verificare quali modelli hanno elaborato un oggetto e visualizzare i metadati di contesto di base, utilizza la console Cloud de Confiance o l'API JSON:

Console

  1. Nella console Cloud de Confiance , vai alla pagina Bucket in Cloud Storage.

    Vai a Bucket

  2. Nell'elenco dei bucket, fai clic sul nome del bucket che contiene l'oggetto da ispezionare.

    Nella tabella Oggetti, la colonna Contesti personalizzati mostra un chip per ogni modello che ha elaborato un oggetto (Sicurezza dei contenuti, Rilevatore di volti, Rilevatore di etichette, Rilevatore di oggetti o Classificazione PDF).

  3. Per ispezionare un singolo oggetto, fai clic sul nome dell'oggetto.

  4. Nella pagina Dettagli oggetto, vai al campo Contesti personalizzati. Se il campo contiene più chip, fai clic su per espandere la riga.

  5. Tieni il puntatore sopra o fai clic su un chip del modello per visualizzare i metadati di contesto di base:

    • Chiave di contesto: la chiave del modello riservata, ad esempio google:annotation:label-detector-v1.
    • Valore del contesto: lo stato di esecuzione del modello (SUCCESS o FAILURE).
    • Data di creazione e Data ultima modifica: i timestamp di quando Cloud Storage ha creato e aggiornato l'arricchimento.
    • Visualizza hub di configurazione: apre la pagina Arricchimenti degli oggetti. Quando visualizzi un chip dalla tabella Oggetti del bucket, puoi anche fare clic su Filtra contesti per filtrare gli oggetti nel bucket in base a quel contesto.

API JSON

  1. Avere gcloud CLI installato e inizializzato, che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per inviare una richiesta Objects: get con il parametro di query projection=full all'API JSON:

    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?projection=full"

    Dove:

    • BUCKET_NAME è il nome del bucket contenente l'oggetto. Ad esempio, my-bucket.
    • OBJECT_NAME è il nome dell'oggetto codificato nell'URL. Ad esempio, image.jpg.

    La risposta restituisce la struttura 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"
      }
    }
  }
}

    Il campo value indica lo stato di esecuzione del modello per l'oggetto, ad esempio SUCCESS o FAILURE.

Recupera i dati estesi

Per recuperare i dati di arricchimento strutturati completi (come riquadri di delimitazione, poligoni di delimitazione, etichette o volti rilevati), chiama il metodo viewFullContext (anteprima) utilizzando l'API JSON.

  1. Avere gcloud CLI installato e inizializzato, che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per inviare una richiesta viewFullContext all'API JSON, specificando la chiave di contesto del modello che vuoi ispezionare:

    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"

    Dove:

    • BUCKET_NAME è il nome del bucket contenente l'oggetto. Ad esempio, my-bucket.
    • OBJECT_NAME è il nome dell'oggetto codificato come URL. Ad esempio, image.jpg.
    • CONTEXT_KEY è la chiave di contesto del modello. Ad esempio, google:annotation:label-detector-v1.

    La risposta contiene la struttura extendedData con il payload di arricchimento completo:

    {
  "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
        }
      ]
    }
  }
}

Per schemi e campi JSON dettagliati per ogni modello, consulta Modelli e schemi supportati.

Ignora gli enrichment degli oggetti

Se devi rispettare le policy sulla conservazione dei dati o non hai più bisogno dei metadati di arricchimento, puoi eliminarli dagli oggetti.

Poiché Google gestisce le chiavi di contesto che iniziano con il prefisso google:, non puoi modificarle o eliminarle utilizzando i metodi standard di aggiornamento dei metadati. Invece, vengono ignorati durante un'operazione di riscrittura, copia o composizione di un oggetto specificando il parametro dropContextGroups=custom, che ignora tutti i contesti dell'oggetto.

Per ignorare i contesti degli oggetti (inclusi gli arricchimenti degli oggetti) quando riscrivi un oggetto utilizzando l'API JSON, segui questi passaggi:

  1. Avere gcloud CLI installato e inizializzato, che ti consente di generare un token di accesso per l'intestazione Authorization.

  2. Utilizza cURL per chiamare l'API JSON con una richiesta di oggetto di riscrittura POST e il parametro di query 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"

    Dove:

    • SOURCE_BUCKET è il nome del bucket contenente l'oggetto di origine. Ad esempio, my-source-bucket.
    • SOURCE_OBJECT è il nome codificato come URL dell'oggetto di origine. Ad esempio, image.jpg.
    • DESTINATION_BUCKET è il nome del bucket di destinazione (può corrispondere al bucket di origine). Ad esempio, my-source-bucket.
    • DESTINATION_OBJECT è il nome codificato nell'URL dell'oggetto di destinazione (può corrispondere all'oggetto di origine). Ad esempio, image.jpg.

Per gestire ed eliminare i contesti di miliardi di oggetti, consulta Gestisci i contesti degli oggetti collettivamente.

Monitora le metriche degli enrichment degli oggetti

Puoi monitorare la velocità effettiva di elaborazione degli arricchimenti, gli oggetti in attesa e i conteggi di esecuzione dei modelli utilizzando Cloud Monitoring. Cloud Storage esporta le seguenti metriche nello spazio dei nomi storage.googleapis.com sulla risorsa monitorata gcs_bucket:

Tipo di metrica (con prefisso storage.googleapis.com/) Kind e Type Descrizione ed etichette
auto_annotate/operations/pending_objects GAUGE, INT64 Numero totale di oggetti in attesa di enrichment nel bucket. Campionamento eseguito ogni 300 secondi.
auto_annotate/operations/processed_object_count DELTA, INT64 Numero totale di oggetti elaborati dagli arricchimenti degli oggetti durante la finestra temporale. Campionamento eseguito ogni 300 secondi.
auto_annotate/operations/model_count DELTA, INT64 Numero totale di modelli eseguiti nel bucket durante la finestra temporale, raggruppati per model_name, model_version e status (ad esempio SUCCESS o FAILURE).
auto_annotate/operations/request_count DELTA, INT64 Numero totale di chiamate API effettuate durante l'intervallo di tempo, raggruppate per method e response_code.
auto_annotate/storage/annotated_objects GAUGE, INT64 Istantanea giornaliera del numero totale di oggetti nel bucket per i quali sono stati generati arricchimenti, raggruppati per type e data_locations.
auto_annotate/storage/model_outputs GAUGE, INT64 Istantanea giornaliera del numero totale di output del modello archiviati nel bucket, raggruppati per model_name, model_version, status, type e data_locations.

Per saperne di più su come eseguire query sulle metriche e configurare gli avvisi, consulta Metriche di Cloud Monitoring per Cloud Storage e Crea grafici con Esplora metriche.

Passaggi successivi