Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan konteks objek

Halaman ini menjelaskan cara melampirkan dan mengelola konteks pada objek Cloud Storage dalam bentuk pasangan nilai kunci.

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan guna membuat dan mengelola konteks objek, minta administrator Anda untuk memberi Anda peran IAM berikut pada objek:

Membuat objek dengan konteks: Storage Object Creator (roles/storage.objectCreator)
Melampirkan, memperbarui, melihat, dan menghapus konteks dari objek: Storage Object User (roles/storage.objectUser)
Melihat kunci dan nilai konteks yang dilampirkan ke objek: Storage Object Viewer (roles/storage.objectViewer)

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, baca artikel Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk membuat dan mengelola konteks objek. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat dan mengelola konteks objek:

Buat objek dengan konteks objek:
- storage.objects.create
- storage.objects.createContext
Melampirkan, memperbarui, dan menghapus konteks objek:
- storage.objects.update
- storage.objects.createContext
- storage.objects.updateContext
- storage.objects.deleteContext
Melihat konteks objek:
- storage.objects.get
- storage.objects.list

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

Melampirkan konteks ke objek baru

Lampirkan konteks ke objek saat Anda mengupload objek baru ke bucket Cloud Storage. Setiap konteks terdiri dari kunci dan nilai.

Command line

Untuk melampirkan konteks saat Anda mengupload objek dengan perintah gcloud alpha storage cp, gunakan flag --custom-contexts:

gcloud alpha storage cp OBJECT_LOCATION gs://DESTINATION_BUCKET_NAME --custom-contexts=KEY=VALUE,...

Dengan:

OBJECT_LOCATION adalah jalur lokal ke objek Anda. Contohnya, Desktop/dog.png
DESTINATION_BUCKET_NAME adalah nama bucket tempat Anda mengupload objek. Contoh, my-bucket.
KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci yang dipisahkan dengan koma.
VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.

Atau, buat file JSON yang berisi konteks yang ingin Anda lampirkan ke objek, dan gunakan tanda --custom-contexts-file:

  {
    "KEY": {
      "value": "VALUE"
    },
    ...
  }

Dengan:

KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci.
VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.

Untuk melampirkan konteks saat Anda mengupload direktori dengan perintah gcloud alpha storage rsync, gunakan flag --custom-contexts atau flag --custom-contexts-file:

gcloud alpha storage rsync DIRECTORY_LOCATION gs://DESTINATION_BUCKET_NAME --recursive --custom-contexts=KEY=VALUE,...

Dengan:

DIRECTORY_LOCATION adalah jalur lokal ke direktori Anda. Contoh, ~/my_directory.
DESTINATION_BUCKET_NAME adalah nama bucket tempat Anda mengupload direktori. Contoh, my-bucket.
KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci yang dipisahkan dengan koma.
VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.

JSON API

Untuk melampirkan konteks ke objek saat Anda mengupload objek baru, gunakan salah satu metode berikut:

Sebagai bagian dari metadata objek dalam format JSON, sertakan kolom contexts:

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Dengan:

KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci dalam objek custom.
VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.

Melampirkan atau mengubah konteks ke objek yang ada

Anda dapat melampirkan konteks baru ke objek yang ada di bucket Cloud Storage.

Command line

Gunakan perintah gcloud alpha storage objects update:

gcloud alpha storage objects update gs://BUCKET_NAME/OBJECT_NAME CUSTOM_CONTEXTS_FLAG

Dengan:

BUCKET_NAME adalah nama bucket yang berisi objek yang konteksnya ingin Anda edit. Contoh, my-bucket.
OBJECT_NAME adalah nama objek. Contoh, pets/dog.png.
CUSTOM_CONTEXTS_FLAG adalah salah satu flag berikut:
- Untuk mengganti semua konteks yang ada, gunakan --custom-contexts=KEY=VALUE,... atau --custom-contexts-file=CUSTOM_CONTEXTS_FILE
  
  Dengan:
  - KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci yang dipisahkan dengan koma.
  - VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.
  - CUSTOM_CONTEXTS_FILE adalah jalur ke file JSON atau YAML yang berisi konteks yang ingin Anda lampirkan ke objek.
- Untuk menghapus semua konteks yang ada, gunakan --clear-custom-contexts.
- Untuk menambahkan, mengubah, atau menghapus konteks individual, gunakan kombinasi --update-custom-contexts=KEY=VALUE,... dan --remove-custom-contexts=KEY,...
  
  Dengan:
  - KEY adalah kunci konteks yang ingin Anda lampirkan ke atau hapus dari objek. Contoh, Department.
  - VALUE adalah nilai yang akan dikaitkan dengan kunci konteks yang ingin Anda lampirkan ke objek. Contoh, Human resources.

Jika berhasil, responsnya akan terlihat seperti contoh berikut:

Patching gs://my-bucket/pets/dog.png#1560574162144861...
  Completed 1

Library klien

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobId;
import com.google.cloud.storage.BlobInfo;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import com.google.common.collect.Maps;
import java.util.Map;

public class SetObjectContexts {
  public static void setObjectContexts(
      String projectId, String bucketName, String objectName, String key, String value)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    // The context key-value you want to add
    // String key = "your-context-key";
    // String value = "your-context-value";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {
      BlobId blobId = BlobId.of(bucketName, objectName);
      Blob blob = storage.get(blobId);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }

      // Recommended: Set a generation-match precondition to avoid potential race
      // conditions and data corruptions. The request to update returns a 412 error if
      // the object's generation number does not match your precondition.
      Storage.BlobTargetOption precondition = Storage.BlobTargetOption.generationMatch();

      // This section demonstrates how to upsert, delete all, and delete a specific context.

      // To upsert a context (if the key already exists, its value is replaced;
      // otherwise, a new key-value pair is added):
      ObjectCustomContextPayload payload =
          ObjectCustomContextPayload.newBuilder().setValue(value).build();
      Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
      custom.put(key, payload);
      ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();

      /*
       * To delete all existing contexts:
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(null).build();
       */

      /*
       * To delete a specific key from the context:
       * Map<String, ObjectCustomContextPayload> custom = Maps.newHashMap();
       * custom.put(key, null);
       * ObjectContexts contexts = ObjectContexts.newBuilder().setCustom(custom).build();
       */
      BlobInfo pendingUpdate = blob.toBuilder().setContexts(contexts).build();
      storage.update(pendingUpdate, precondition);

      System.out.println(
          "Updated custom contexts for object " + objectName + " in bucket " + bucketName);
    }
  }
}

JSON API

Instal dan lakukan inisialisasi gcloud CLI, yang memungkinkan Anda membuat token akses untuk header Authorization.

Buat file JSON yang berisi setelan untuk objek, yang harus menyertakan kolom konfigurasi contexts untuk objek.

Untuk menambahkan, mengubah, atau mengganti konteks yang ada, gunakan format berikut:

  {
    "contexts": {
      "custom": {
        "KEY": {
          "value": "VALUE"
        },
        ...
      }
    }
  }

Dengan:

KEY adalah kunci konteks yang akan dilampirkan ke objek. Contoh, Department. Anda dapat menentukan beberapa pasangan nilai kunci dalam objek custom.
VALUE adalah nilai yang akan dikaitkan dengan kunci konteks. Contoh, Human resources.

Untuk menghapus semua konteks yang ada, gunakan format berikut:

  {
    "contexts": {
      "custom": null
    }
  }

Untuk menghapus kunci tertentu dari konteks, gunakan format berikut:

  {
    "contexts": {
      "custom": {
        "KEY": null,
        ...
      }
    }
  }

Dengan:

KEY adalah kunci konteks yang ingin Anda hapus dari objek. Contoh, Department. Anda dapat menentukan beberapa kunci untuk dihapus dari objek custom.

Gunakan cURL untuk memanggil JSON API dengan permintaan PATCH Object:
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"
```
Dengan:
- JSON_FILE_NAME adalah jalur ke file yang menyertakan informasi konteks objek.
- BUCKET_NAME adalah nama bucket yang berisi objek yang konteksnya ingin Anda edit. Contoh, my-bucket.
- OBJECT_NAME adalah nama objek yang dienkode ke URL. Misalnya, pets/dog.png dienkode ke URL sebagai pets%2Fdog.png.

Atau, Anda dapat mengganti konteks objek dengan permintaan Objek PUT. Permintaan objek PUT juga menggantikan metadata objek lainnya. Oleh karena itu, sebaiknya jangan gunakan permintaan objek PUT.

Melihat konteks objek

Anda dapat melihat konteks objek dengan mencantumkan metadata objek atau mendeskripsikan objek tertentu.

Command line

Gunakan perintah gcloud alpha storage objects describe:

gcloud alpha storage objects describe gs://BUCKET_NAME/OBJECT_NAME

Dengan:

BUCKET_NAME adalah nama bucket yang berisi objek yang konteksnya ingin Anda lihat. Contoh, my-bucket.
OBJECT_NAME adalah nama objek yang konteksnya ingin Anda lihat. Misalnya, pets/dog.png

Jika berhasil, responsnya akan terlihat mirip dengan contoh berikut ini:

bucket: my-bucket
contexts:
  Department:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: HR
  DataClassification:
    createTime: '2023-01-01T00:00:00.000000+00:00'
    type: CUSTOM
    updateTime: '2023-01-01T00:00:00.000000+00:00'
    value: Confidential
name: employees.txt

Library klien

Java

Untuk mengetahui informasi selengkapnya, lihatDokumentasi referensi Cloud Storage Java API.

Untuk melakukan autentikasi ke Cloud Storage, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.


import com.google.cloud.storage.Blob;
import com.google.cloud.storage.BlobInfo.ObjectContexts;
import com.google.cloud.storage.BlobInfo.ObjectCustomContextPayload;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class GetObjectContexts {
  public static void getObjectContexts(String projectId, String bucketName, String objectName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID of your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The ID of your GCS object
    // String objectName = "your-object-name";

    try (Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).build().getService()) {

      Blob blob = storage.get(bucketName, objectName);
      if (blob == null) {
        System.out.println("The object " + objectName + " was not found in " + bucketName);
        return;
      }
      ObjectContexts objectContexts = blob.getContexts();

      if (objectContexts != null) {
        Map<String, ObjectCustomContextPayload> customContexts = objectContexts.getCustom();
        if (customContexts == null) {
          System.out.println("No custom contexts found for object: " + objectName);
          return;
        }
        // Print blob's object contexts
        System.out.println("\nCustom Contexts:");
        for (Map.Entry<String, ObjectCustomContextPayload> custom : customContexts.entrySet()) {
          System.out.println(custom.getKey() + "=" + custom.getValue());
        }
      }
    }
  }
}

JSON API

Instal dan lakukan inisialisasi gcloud CLI, yang memungkinkan Anda membuat token akses untuk header Authorization.

Gunakan cURL untuk memanggil JSON API dengan permintaan GET Object:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME"

Dengan:

BUCKET_NAME adalah nama bucket yang berisi objek yang konteksnya ingin Anda lihat. Contoh, my-bucket.
OBJECT_NAME adalah nama objek yang dienkode ke URL yang konteksnya ingin Anda lihat. Contoh, pets/dog.png, URL dienkode sebagai pets%2Fdog.png.

Jika berhasil, responsnya akan terlihat mirip dengan contoh berikut ini:

  {
    "kind": "storage#object",
    "name": "employees.txt",
    "bucket": "my-bucket",
    "contexts": {
      "custom": {
        "Department": {
          "value": "HR",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        },
        "DataClassification": {
          "value": "Confidential",
          "createTime": "2023-01-01T00:00:00.000Z",
          "updateTime": "2023-01-01T00:00:00.000Z"
        }
      }
    }
  }

Memfilter objek menurut konteks

Memfilter objek berdasarkan keberadaan kunci konteks objek atau nilai tertentunya. Memfilter objek berdasarkan konteks membantu menemukan dan mengelola grup objek tertentu secara efisien. Untuk mengetahui detailnya, lihat Memfilter objek menurut konteks.

Mengelola konteks objek selama operasi objek

Konteks objek dipertahankan secara default saat Anda menyalin, menulis ulang, menyusun, memindahkan, atau memulihkan objek. Anda juga dapat mengubah konteks selama operasi salin, tulis ulang, dan gabungkan.

Command line

Perintah gcloud alpha storage cp, gcloud alpha storage rsync, dan gcloud alpha storage mv mempertahankan konteks dari objek sumber secara default. Untuk mengubah konteks selama operasi ini, gunakan salah satu tanda berikut:

Flag --custom-contexts atau --custom-contexts-file untuk menetapkan konteks baru bagi objek tujuan.
Flag --clear-custom-contexts untuk mencegah konteks dari objek sumber dilampirkan ke objek tujuan.
Kombinasi flag --update-custom-contexts dan --remove-custom-contexts untuk mengubah setiap konteks dari objek sumber sebelum melampirkannya ke objek tujuan.

Perintah gcloud alpha storage objects compose menggabungkan konteks dari objek sumber dan melampirkannya ke objek tujuan secara default. Cloud Storage menyelesaikan konflik dengan memprioritaskan konteks dari objek sumber yang diproses nanti. Untuk mengetahui informasi selengkapnya tentang perilaku konteks objek selama operasi penyusunan, lihat Konteks objek komposit. Anda juga dapat menentukan konteks baru untuk objek tujuan menggunakan tanda --custom-contexts atau --custom-contexts-file.

JSON API

Untuk mengubah konteks selama operasi objek penyalinan atau penulisan ulang, sertakan properti contexts.custom dalam isi permintaan. Jika Anda tidak menyertakan properti ini, konteks dari objek sumber akan dipertahankan secara default.
Saat Anda menyusun objek, konteks dari objek sumber akan digabungkan ke dalam objek tujuan secara default. Cloud Storage menyelesaikan konflik dengan memprioritaskan konteks dari objek sumber yang diproses nanti. Untuk mengetahui informasi selengkapnya tentang perilaku konteks objek selama operasi compose, lihat Konteks objek komposit. Anda juga dapat menentukan konteks baru untuk objek tujuan dalam properti destination.contexts.custom.

Langkah berikutnya

Pelajari properti konteks objek di dokumentasi Cloud Storage API.

Menggunakan konteks objek Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Mendapatkan peran yang diperlukan

Izin yang diperlukan

Melampirkan konteks ke objek baru

Command line

JSON API

Melampirkan atau mengubah konteks ke objek yang ada

Command line

Library klien

Java

JSON API

Melihat konteks objek

Command line

Library klien

Java

JSON API

Memfilter objek menurut konteks

Mengelola konteks objek selama operasi objek

Command line

JSON API

Langkah berikutnya

Menggunakan konteks objek