Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengelola pengayaan objek

Setelah Anda mengonfigurasi pengayaan objek, Cloud Storage akan mengevaluasi objek yang memenuhi syarat secara asinkron dan melampirkan metadata pengayaan langsung ke objek yang Anda simpan.

Halaman ini menjelaskan cara memeriksa metadata konteks dasar, mengambil payload data yang diperluas, menghapus pengayaan dari objek, dan memantau progres pemrosesan di Cloud Monitoring.

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk melihat, mengambil, dan menghapus pengayaan objek, minta administrator untuk memberi Anda peran IAM berikut pada bucket atau project Anda:

Melihat metadata pengayaan objek dasar: Storage Object Viewer (roles/storage.objectViewer)
Mengambil data yang diperluas dari pengayaan objek: Storage Object User (roles/storage.objectUser)
Menghapus pengayaan objek selama penulisan ulang objek: Storage Object Admin (roles/storage.objectAdmin)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk melihat, mengambil, dan menghapus pengayaan objek. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk melihat, mengambil, dan menghapus pengayaan objek:

Melihat metadata konteks pengayaan objek dasar: storage.objects.get
Mengambil data yang diperluas dari pengayaan objek: storage.objects.viewFullContext
Menghapus pengayaan objek selama penulisan ulang objek:
- storage.objects.get
- storage.objects.create
- storage.objects.delete
- storage.objects.update

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Melihat pengayaan objek

Cloud Storage melampirkan metadata pengayaan langsung ke objek Anda sebagai konteks objek yang dikelola Google di bagian properti contexts.custom. Setiap model menggunakan kunci yang dicadangkan dengan awalan google:annotation: (misalnya, google:annotation:label-detector-v1 atau google:annotation:face-detector-v1).

Cloud Storage mengatur data pengayaan menjadi dua tingkat:

Metadata konteks: Berisi kunci konteks, status eksekusi model (value), stempel waktu, dan URL jenis protobuf. Operasi describe dan get objek standar menampilkan metadata ini.
Data yang diperluas (Pratinjau): Berisi payload pengayaan JSON terstruktur lengkap (hingga 128 KiB). Payload ini mencakup detail seperti koordinat poligon pembatas, skor keyakinan klasifikasi, ekspresi wajah, dan rating keamanan.

Melihat metadata konteks dasar

Untuk memeriksa model mana yang telah memproses objek dan melihat metadata konteks dasar, gunakan konsol Google Cloud atau JSON API:

Konsol

Di konsol Google Cloud , buka halaman Buckets Cloud Storage.

Buka Buckets
Dalam daftar bucket, klik nama bucket yang berisi objek yang ingin Anda periksa.

Dalam tabel Objek, kolom Konteks kustom menampilkan chip untuk setiap model yang telah memproses objek (Content Safety, Face Detector, Label Detector, Object Detector, atau PDF Classification).
Untuk memeriksa setiap objek, klik nama objek.
Di halaman Object details, buka kolom Custom contexts. Jika kolom memiliki beberapa chip, klik untuk meluaskan baris.
Tahan kursor di atas atau klik chip model untuk melihat metadata konteks dasar:
- Kunci konteks: Kunci model yang dicadangkan, seperti google:annotation:label-detector-v1.
- Nilai konteks: Status eksekusi model (SUCCESS atau FAILURE).
- Waktu pembuatan dan Waktu terakhir diubah: Stempel waktu saat Cloud Storage membuat dan terakhir memperbarui pengayaan.
- View configuration hub: Membuka halaman Object enrichments. Saat melihat chip dari tabel Objek bucket, Anda juga dapat mengklik Filter konteks untuk memfilter objek dalam bucket berdasarkan konteks tersebut.

JSON API

Menginstal dan melakukan inisialisasi gcloud CLI, yang memungkinkan Anda membuat token akses untuk header Authorization.

Gunakan cURL untuk mengirim permintaan Objects: get dengan parameter kueri projection=full ke JSON API:

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"

Dengan:

BUCKET_NAME adalah nama bucket yang berisi objek. Contoh, my-bucket.
OBJECT_NAME adalah nama objek yang dienkode ke URL. Contoh, image.jpg.

Respons menampilkan struktur 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"
      }
    }
  }
}

Kolom value menunjukkan status eksekusi model untuk objek, seperti SUCCESS atau FAILURE.

Mengambil data yang diperluas

Untuk mengambil data lengkap pengayaan terstruktur (seperti kotak pembatas, poligon pembatas, label, atau wajah yang terdeteksi), panggil metode viewFullContext (Pratinjau) menggunakan JSON API.

Menginstal dan melakukan inisialisasi gcloud CLI, yang memungkinkan Anda membuat token akses untuk header Authorization.

Gunakan cURL untuk mengirim permintaan viewFullContext ke JSON API, dengan menentukan kunci konteks model yang ingin Anda periksa:

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"

Dengan:

BUCKET_NAME adalah nama bucket yang berisi objek. Contoh, my-bucket.
OBJECT_NAME adalah nama objek yang dienkode ke URL. Contoh, image.jpg.
CONTEXT_KEY adalah kunci konteks model. Contoh, google:annotation:label-detector-v1.

Respons berisi struktur extendedData dengan payload pengayaan lengkap:

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

Untuk mengetahui skema dan kolom JSON mendetail untuk setiap model, lihat Model dan skema yang didukung.

Hapus pengayaan objek

Jika Anda harus mematuhi kebijakan retensi data atau tidak lagi memerlukan metadata pengayaan, Anda dapat menghapusnya dari objek.

Karena Google mengelola kunci konteks yang diawali dengan awalan google:, Anda tidak dapat mengubah atau menghapusnya menggunakan metode update metadata standar. Sebagai gantinya, Anda menghapusnya selama operasi penulisan ulang, penyalinan, atau penyusunan objek dengan menentukan parameter dropContextGroups=custom, yang menghapus semua konteks objek pada objek.

Untuk menghapus konteks objek (termasuk pengayaan objek) saat menulis ulang objek menggunakan JSON API, lakukan hal berikut:

Menginstal dan melakukan inisialisasi gcloud CLI, yang memungkinkan Anda membuat token akses untuk header Authorization.
Gunakan cURL untuk memanggil JSON API dengan permintaan POST rewrite Object dan parameter kueri dropContextGroups=custom:
```
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"
```
Dengan:
- SOURCE_BUCKET adalah nama bucket yang berisi objek sumber. Contoh, my-source-bucket.
- SOURCE_OBJECT adalah nama objek sumber yang dienkode ke URL. Contoh, image.jpg.
- DESTINATION_BUCKET adalah nama bucket tujuan (dapat sama dengan bucket sumber). Contoh, my-source-bucket.
- DESTINATION_OBJECT adalah nama objek tujuan yang dienkode ke URL (dapat cocok dengan objek sumber). Contoh, image.jpg.

Untuk mengelola dan menghapus konteks di miliaran objek, lihat Mengelola konteks objek secara massal.

Memantau metrik pengayaan objek

Anda dapat melacak throughput pemrosesan pengayaan, objek yang tertunda, dan jumlah eksekusi model menggunakan Cloud Monitoring. Cloud Storage mengekspor metrik berikut di namespace storage.googleapis.com pada gcs_bucket resource yang dimonitor:

Jenis metrik (diawali dengan `storage.googleapis.com/`)	Jenis dan tipe	Deskripsi dan label
`auto_annotate/operations/pending_objects`	`GAUGE`, `INT64`	Jumlah total objek yang menunggu pengayaan dalam bucket. Dibuat sampelnya setiap 300 detik.
`auto_annotate/operations/processed_object_count`	`DELTA`, `INT64`	Jumlah total objek yang diproses oleh pengayaan objek selama jangka waktu tertentu. Sampelnya dibuat setiap 300 detik.
`auto_annotate/operations/model_count`	`DELTA`, `INT64`	Total jumlah model yang dieksekusi dalam bucket selama periode waktu, dikelompokkan menurut `model_name`, `model_version`, dan `status` (seperti `SUCCESS` atau `FAILURE`).
`auto_annotate/operations/request_count`	`DELTA`, `INT64`	Jumlah total panggilan API yang dilakukan selama periode waktu, yang dikelompokkan menurut `method` dan `response_code`.
`auto_annotate/storage/annotated_objects`	`GAUGE`, `INT64`	Snapshot harian jumlah total objek dalam bucket yang memiliki pengayaan yang dibuat untuk objek tersebut, yang dikelompokkan menurut `type` dan `data_locations`.
`auto_annotate/storage/model_outputs`	`GAUGE`, `INT64`	Snapshot harian dari jumlah total output model yang disimpan di bucket, yang dikelompokkan menurut `model_name`, `model_version`, `status`, `type`, dan `data_locations`.

Untuk mengetahui informasi selengkapnya tentang cara membuat kueri metrik dan menyiapkan pemberitahuan, lihat Metrik Cloud Monitoring untuk Cloud Storage dan Membuat diagram dengan Metrics Explorer.