Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Gestisci gli enrichment degli oggetti

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

Questa pagina spiega come ispezionare i metadati di contesto di base, recuperare i payload di dati estesi, eliminare gli enrichment dagli oggetti e monitorare l'avanzamento dell'elaborazione in Cloud Monitoring.

Ottenere i ruoli richiesti

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

Visualizzare i metadati di base degli enrichment degli oggetti: Storage Object Viewer (roles/storage.objectViewer)
Recuperare i dati estesi degli enrichment degli oggetti: Storage Object User (roles/storage.objectUser)
Eliminare 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 enrichment degli oggetti. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

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

Visualizzare i metadati di contesto di base degli enrichment degli oggetti: storage.objects.get
Recuperare i dati estesi degli enrichment degli oggetti: storage.objects.viewFullContext
Eliminare 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.

Visualizzare gli enrichment degli oggetti

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

Cloud Storage organizza i dati di enrichment in due livelli:

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

Visualizzare i metadati di contesto di base

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

Console

Nella Google Cloud console, vai alla pagina Bucket di Cloud Storage.

Vai a Bucket
Nell'elenco dei bucket, fai clic sul nome del bucket che contiene l'oggetto che vuoi ispezionare.

Nella tabella Oggetti , la colonna Contesti personalizzati mostra un chip per ogni modello che ha elaborato un oggetto (Content Safety, Face Detector, Label Detector, Object Detector o PDF Classification).
Per ispezionare un singolo oggetto, fai clic sul suo nome.
Nella pagina Dettagli oggetto, vai al campo Contesti personalizzati. Se il campo contiene più chip, fai clic su per espandere la riga.
Tieni il puntatore sopra o fai clic su un chip del modello per visualizzarne i metadati di contesto di base:
- Chiave di contesto: la chiave del modello riservata, ad esempio google:annotation:label-detector-v1.
- Valore di contesto: lo stato di esecuzione del modello (SUCCESS o FAILURE).
- Ora di creazione e Ora dell'ultima modifica: i timestamp relativi alla creazione e all'ultimo aggiornamento dell'enrichment da parte di Cloud Storage.
- Visualizza hub di configurazione: apre la pagina Enrichment 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

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

Utilizza cURL per inviare una richiesta Objects: get con il projection=full parametro di query all'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"

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.

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.

Recuperare i dati estesi

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

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

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.googleapis.com/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 enrichment 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.

Eliminare gli enrichment degli oggetti

Se devi rispettare le policy sulla conservazione dei dati o non hai più bisogno dei metadati di enrichment, 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 di aggiornamento dei metadati standard. In alternativa, puoi eliminarli durante un'operazione di riscrittura, copia o composizione di un oggetto specificando il parametro dropContextGroups=custom, che elimina tutti i contesti degli oggetti sull'oggetto.

Per eliminare i contesti degli oggetti (inclusi gli enrichment degli oggetti) durante la riscrittura di un oggetto utilizzando l'API JSON:

Assicurati di aver installato e inizializzato gcloud CLI, che ti consente di generare un token di accesso per l'intestazione Authorization.
Utilizza cURL per chiamare la API JSON con una POST richiesta di riscrittura dell'oggetto e il dropContextGroups=custom parametro di query:
```
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"
```
Dove:
- SOURCE_BUCKET è il nome del bucket contenente l'oggetto di origine. Ad esempio, my-source-bucket.
- SOURCE_OBJECT è il nome dell'oggetto di origine codificato come URL. 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 dell'oggetto di destinazione codificato come URL (può corrispondere all'oggetto di origine). Ad esempio, image.jpg.

Per gestire ed eliminare i contesti di miliardi di oggetti, consulta Gestire i contesti degli oggetti in blocco.

Monitorare le metriche degli enrichment degli oggetti

Puoi monitorare la velocità effettiva dell'elaborazione degli enrichment, 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 nella risorsa monitorata gcs_bucket:

Tipo di metrica (con prefisso `storage.googleapis.com/`)	Tipo	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 enrichment 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 la finestra temporale, raggruppate per `method` e `response_code`.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	Snapshot giornaliero del numero totale di oggetti nel bucket per cui sono stati generati enrichment, raggruppati per `type` e `data_locations`.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	Snapshot giornaliero del numero totale di output del modello archiviati nel bucket, raggruppati per `model_name`, `model_version`, `status`, `type` e `data_locations`.

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