Objektkontext-Anreicherung verwalten

Nachdem Sie die Objektkontext-Anreicherung konfiguriert haben, wertet Cloud Storage die infrage kommenden Objekte asynchron aus und hängt die Anreicherungsmetadaten direkt an Ihre gespeicherten Objekte an.

Auf dieser Seite wird erläutert, wie Sie grundlegende Kontextmetadaten prüfen, Nutzlasten mit erweiterten Daten abrufen, Anreicherungen aus Objekten verwerfen und den Verarbeitungsfortschritt in Cloud Monitoring überwachen.

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 Verwerfen von Objektkontext-Anreicherungen benötigen:

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 Verwerfen von Objektkontext-Anreicherungen erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

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

  • Grundlegende Kontextmetadaten für Objektkontext-Anreicherungen ansehen: storage.objects.get
  • Erweiterte Daten zu Objektkontext-Anreicherungen abrufen: storage.objects.viewFullContext
  • Objektkontext-Anreicherungen beim Umschreiben von Objekten verwerfen:
    • storage.objects.get
    • storage.objects.create
    • storage.objects.delete
    • storage.objects.update

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

Objektkontext-Anreicherungen ansehen

Cloud Storage hängt Anreicherungsmetadaten direkt als von Google verwaltete Objektkontexte unter dem Attribut contexts.custom 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 Protobuf-Typ-URL. Standardobjektvorgänge describe und get geben diese Metadaten zurück.
  • Erweiterte Daten (Vorabversion): 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 Kontextmetadaten aufrufen möchten, verwenden Sie die Cloud de Confiance Console oder die JSON API:

Console

  1. Wechseln Sie in der Cloud de Confiance Console unter „Cloud Storage“ zur Seite Buckets.

    Buckets aufrufen

  2. Klicken Sie in der Liste der Buckets auf den Namen des Buckets, 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 (Inhaltssicherheit, Gesichtserkennung, Label-Erkennung, Objekterkennung oder PDF-Klassifizierung).

  3. Klicken Sie auf den Namen des Objekts, um es zu prüfen.

  4. Rufen Sie auf der Seite Objektdetails das Feld Benutzerdefinierte Kontexte auf. Wenn das Feld mehrere Chips enthält, klicken Sie auf , um die Zeile zu maximieren.

  5. Bewegen Sie den Mauszeiger auf einen Modell-Chip 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 Zeitpunkt der letzten Änderung: Die Zeitstempel, die angeben, wann Cloud Storage die Anreicherung erstellt und zuletzt aktualisiert hat.
    • Konfigurationshub ansehen: Öffnet die Seite Objektkontext-Anreicherung. Wenn Sie einen Chip in 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

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

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

    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"

    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 Methode viewFullContext (Vorabversion) über die JSON API auf.

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

  2. Verwenden Sie cURL, um eine viewFullContext-Anfrage an die JSON API zu senden. Geben Sie dabei den Kontextschlüssel des Modells an, das Sie prüfen möchten:

    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"

    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 Modellkontextschlüssel. 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 verwerfen

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

Da Google Kontextschlüssel mit dem Präfix google: verwaltet, können Sie sie nicht mit Standardmethoden zur Metadatenaktualisierung ändern oder löschen. Stattdessen verwerfen Sie sie während eines Umschreib-, Kopier- oder Erstellungsvorgangs für Objekte, indem Sie den Parameter dropContextGroups=custom angeben, der alle Objektkontexte für das Objekt verwirft.

So verwerfen Sie Objektkontexte (einschließlich Objektkontext-Anreicherungen) beim Neuschreiben eines Objekts mit der JSON API:

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

  2. Verwenden Sie cURL, um die JSON-API mit einer POST-Objektumschreibungsanfrage und dem Suchparameter dropContextGroups=custom aufzurufen:

    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"

    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 Ziel-Buckets (kann mit dem Quell-Bucket ü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 Verwerfen von Kontexten für Milliarden von Objekten finden Sie unter Objektkontexte im Bulk verwalten.

Messwerte für Objektkontext-Anreicherung überwachen

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

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, die noch angereichert werden müssen. Alle 300 Sekunden wird eine Stichprobe erstellt.
auto_annotate/operations/processed_object_count DELTA, INT64 Gesamtzahl der Objekte, die im Zeitfenster durch Objektkontext-Anreicherung verarbeitet wurden. Alle 300 Sekunden wird eine Stichprobe erstellt.
auto_annotate/operations/model_count DELTA, INT64 Gesamtzahl der Modelle, die im Bucket während des Zeitfensters 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 im Zeitfenster, 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äglicher Snapshot 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 zum Einrichten von Benachrichtigungen finden Sie unter Cloud Monitoring-Messwerte für Cloud Storage und Diagramme mit dem Metrics Explorer erstellen.

Nächste Schritte