Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Objektkontext-Anreicherung verwalten

Nachdem Sie Objektkontext-Anreicherungen konfiguriert haben, wertet Cloud Storage geeignete Objekte asynchron aus und fügt den gespeicherten Objekten direkt Anreicherungsmetadaten hinzu.

Auf dieser Seite wird erklärt, wie Sie grundlegende Kontextmetadaten prüfen, erweiterte Daten-Nutzlasten abrufen, Anreicherungen aus Objekten entfernen und den Verarbeitungsfortschritt in Cloud Monitoring verfolgen.

Erforderliche Rollen abrufen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihren Bucket oder Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Aufrufen, Abrufen und Entfernen von Objektkontext-Anreicherungen benötigen:

Grundlegende Metadaten zu Objektkontext-Anreicherungen ansehen: Storage-Objekt-Betrachter (roles/storage.objectViewer)
Erweiterte Daten zu Objektkontext-Anreicherungen abrufen: Storage Object User (roles/storage.objectUser)
Objektkontext-Anreicherungen beim Umschreiben von Objekten entfernen: Storage-Objekt-Administrator (roles/storage.objectAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Aufrufen, Abrufen und Entfernen von Objektkontext-Anreicherungen erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen , um die notwendigen Berechtigungen anzuzeigen, die erforderlich sind:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Objektkontext-Anreicherungen aufzurufen, abzurufen und zu entfernen:

Grundlegende Kontextmetadaten zu Objektkontext-Anreicherungen ansehen: storage.objects.get
Erweiterte Daten zu Objektkontext-Anreicherungen abrufen: storage.objects.viewFullContext
Objektkontext-Anreicherungen beim Umschreiben von Objekten entfernen:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

Sie können diese Berechtigungen gegebenenfalls auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Objektkontext-Anreicherungen ansehen

Cloud Storage fügt Anreicherungsmetadaten direkt als von Google verwaltete Objektkontexte unter der contexts.custom Eigenschaft an Ihre Objekte an. Jedes Modell verwendet einen reservierten Schlüssel mit dem Präfix google:annotation: (z. B. google:annotation:label-detector-v1 oder google:annotation:face-detector-v1).

Cloud Storage organisiert Anreicherungsdaten in zwei Ebenen:

Kontextmetadaten: Enthält den Kontextschlüssel, den Status der Modellausführung (value), Zeitstempel und die URL des Protobuf-Typs. Diese Metadaten werden von den Standardvorgängen describe und get für Objekte zurückgegeben.
Erweiterte Daten (Vorschau): Enthält die vollständige strukturierte JSON-Anreicherungsnutzlast (bis zu 128 KiB). Diese Nutzlast enthält Details wie Koordinaten von Begrenzungspolygonen, Konfidenzwerte für die Klassifizierung, Gesichtsausdrücke und Sicherheitsbewertungen.

Grundlegende Kontextmetadaten ansehen

Wenn Sie prüfen möchten, welche Modelle ein Objekt verarbeitet haben, und grundlegende Kontext metadaten ansehen möchten, verwenden Sie die Google Cloud Console oder die JSON API:

Console

Wechseln Sie in der Google Cloud Console unter „Cloud Storage“ zur Seite Buckets.

Buckets aufrufen
Klicken Sie in der Liste der Buckets auf den Bucket, der das Objekt enthält, das Sie prüfen möchten.

In der Tabelle Objekte wird in der Spalte Benutzerdefinierte Kontexte ein Chip für jedes Modell angezeigt, das ein Objekt verarbeitet hat (Content Safety, Face Detector, Label Detector, Object Detector oder PDF Classification).
Wenn Sie ein einzelnes Objekt prüfen möchten, klicken Sie auf den Namen des Objekts.
Rufen Sie auf der Seite Objektdetails das Feld Benutzerdefinierte Kontexte auf. Wenn das Feld mehrere Chips enthält, klicken Sie auf (Maximieren), um die Zeile zu maximieren.
Bewegen Sie den Mauszeiger auf einen Modellchip oder klicken Sie darauf, um die grundlegenden Kontextmetadaten aufzurufen:
- Kontextschlüssel: Der reservierte Modellschlüssel, z. B. google:annotation:label-detector-v1.
- Kontextwert: Der Status der Modellausführung (SUCCESS oder FAILURE).
- Erstellungszeit und Zeit der letzten Änderung: Die Zeitstempel für die Erstellung und letzte Aktualisierung der Anreicherung durch Cloud Storage.
- Konfigurationshub ansehen: Öffnet die Seite Objektkontext-Anreicherungen. Wenn Sie einen Chip aus der Tabelle Objekte des Buckets aufrufen, können Sie auch auf Kontexte filtern klicken, um Objekte im Bucket nach diesem Kontext zu filtern.

JSON API

Installieren und initialisieren Sie die gcloud CLI installiert und initialisiert, um ein Zugriffstoken für den Authorization Header zu generieren.

Verwenden Sie cURL, um eine Objects: get Anfrage mit dem projection=full Suchparameter an die JSON-API zu senden:

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"

Wobei:

BUCKET_NAME ist der Name des Buckets, der das Objekt enthält. Beispiel: my-bucket.
OBJECT_NAME ist der URL-codierte Name des Objekts. Beispiel: image.jpg.

Die Antwort gibt die Struktur contexts.custom zurück:

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

Das Feld value gibt den Status der Modellausführung für das Objekt an, z. B. SUCCESS oder FAILURE.

Erweiterte Daten abrufen

Wenn Sie die vollständigen strukturierten Anreicherungsdaten (z. B. Begrenzungsrahmen, Begrenzungspolygone, Labels oder erkannte Gesichter) abrufen möchten, rufen Sie die viewFullContext Methode (Vorschau) über die JSON API auf.

Installieren und initialisieren Sie die gcloud CLI installiert und initialisiert, um ein Zugriffstoken für den Authorization Header zu generieren.

Verwenden Sie cURL, um eine viewFullContext Anfrage an die JSON API zu senden und den Kontextschlüssel des Modells anzugeben, das Sie prüfen möchten:

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"

Wobei:

BUCKET_NAME ist der Name des Buckets, der das Objekt enthält. Beispiel: my-bucket.
OBJECT_NAME ist der URL-codierte Name des Objekts. Beispiel: image.jpg.
CONTEXT_KEY ist der Kontextschlüssel des Modells. Beispiel: google:annotation:label-detector-v1.

Die Antwort enthält die Struktur extendedData mit der vollständigen Anreicherungsnutzlast:

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

Detaillierte JSON-Schemas und Felder für jedes Modell finden Sie unter Unterstützte Modelle und Schemas.

Objektkontext-Anreicherungen entfernen

Wenn Sie Richtlinien zur Datenaufbewahrung einhalten müssen oder Anreicherungsmetadaten nicht mehr benötigen, können Sie sie aus Ihren Objekten entfernen.

Da Google Kontextschlüssel mit dem Präfix google: verwaltet, können Sie sie nicht mit Standardmethoden zur Aktualisierung von Metadaten ändern oder löschen. Stattdessen entfernen Sie sie bei einem Vorgang zum Umschreiben, Kopieren oder Zusammensetzen von Objekten, indem Sie den Parameter dropContextGroups=custom angeben. Dadurch werden alle Objektkontexte für das Objekt entfernt.

So entfernen Sie Objektkontexte (einschließlich Objektkontext-Anreicherungen) wenn Sie ein Objekt mit der JSON API umschreiben:

Installieren und initialisieren Sie die gcloud CLI installiert und initialisiert, um ein Zugriffstoken für den Authorization Header zu generieren.
Verwenden Sie cURL, um die JSON-API mit einer POST Anfrage zum Umschreiben von Objekten und dem dropContextGroups=custom Suchparameter aufzurufen:
```
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"
```
Wobei:
- SOURCE_BUCKET ist der Name des Buckets, der das Quellobjekt enthält. Beispiel: my-source-bucket.
- SOURCE_OBJECT ist der URL-codierte Name des Quellobjekts. Beispiel: image.jpg.
- DESTINATION_BUCKET ist der Name des Zielbuckets (kann mit dem Quellbucket übereinstimmen). Beispiel: my-source-bucket.
- DESTINATION_OBJECT ist der URL-codierte Name des Zielobjekts (kann mit dem Quellobjekt übereinstimmen). Beispiel: image.jpg.

Informationen zum Verwalten und Entfernen von Kontexten für Milliarden von Objekten finden Sie unter Objektkontexte im Bulk verwalten.

Messwerte für Objektkontext-Anreicherungen beobachten

Mit Cloud Monitoring können Sie den Durchsatz der Anreicherungsverarbeitung, ausstehende Objekte und die Anzahl der Modell ausführungen verfolgen. Cloud Storage exportiert die folgenden Messwerte unter dem storage.googleapis.com Namespace für die gcs_bucket überwachte Ressource:

Messwerttyp (mit dem Präfix `storage.googleapis.com/`)	Art und Typ	Beschreibung und Labels
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	Gesamtzahl der Objekte im Bucket, für die noch eine Anreicherung aussteht. Alle 300 Sekunden wird eine Stichprobe erstellt.
`auto_annotate/operations/processed_object_count`	`DELTA`, `INT64`	Gesamtzahl der Objekte, die während des Zeitraums durch Objektkontext-Anreicherungen verarbeitet wurden. Alle 300 Sekunden wird eine Stichprobe erstellt.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	Gesamtzahl der Modelle, die während des Zeitraums im Bucket ausgeführt wurden, gruppiert nach `model_name`, `model_version` und `status` (z. B. `SUCCESS` oder `FAILURE`).
`auto_annotate/operations/request_count`	`DELTA`, `INT64`	Gesamtzahl der API-Aufrufe während des Zeitraums, gruppiert nach `method` und `response_code`.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	Tägliche Momentaufnahme der Gesamtzahl der Objekte im Bucket, für die Anreicherungen generiert wurden, gruppiert nach `type` und `data_locations`.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	Tägliche Momentaufnahme der Gesamtzahl der im Bucket gespeicherten Modellausgaben, gruppiert nach `model_name`, `model_version`, `status`, `type` und `data_locations`.

Weitere Informationen zum Abfragen von Messwerten und Einrichten von Benachrichtigungen finden Sie unter Cloud Monitoring-Messwerte für Cloud Storage und Diagramme mit dem Metrics Explorer erstellen.