Mengirim permintaan batch

Dokumen ini menunjukkan cara mengelompokkan panggilan JSON API sekaligus untuk mengurangi jumlah koneksi HTTP yang harus dibuat klien Anda saat mengakses Cloud Storage.

Ringkasan

Setiap koneksi HTTP yang dibuat klien Anda menghasilkan sejumlah overhead tertentu. Cloud Storage JSON API mendukung pengelompokan, sehingga klien Anda dapat menempatkan beberapa panggilan API ke dalam satu permintaan HTTP.

Contoh situasi saat Anda mungkin ingin menggunakan pengelompokan:

• Mengupdate metadata, seperti izin, di banyak objek.
• Menghapus banyak objek.

Dalam setiap kasus, daripada mengirim setiap panggilan secara terpisah, Anda dapat mengelompokkannya menjadi satu permintaan HTTP. Semua permintaan internal harus diarahkan ke Cloud Storage JSON API.

Anda tidak boleh menyertakan lebih dari 100 panggilan dalam satu permintaan batch. Jika Anda perlu melakukan lebih banyak panggilan dari itu, gunakan beberapa permintaan batch. Total payload permintaan batch harus kurang dari 10 MB.

Catatan: Sistem batch untuk Cloud Storage JSON API menggunakan sintaksis yang sama dengan sistem batch processing OData, tetapi semantiknya berbeda.

Catatan: Cloud Storage tidak mendukung operasi batch untuk mengupload atau mendownload.

Detail batch

Permintaan batch terdiri dari beberapa panggilan API yang digabungkan menjadi satu permintaan HTTP, yang dapat dikirim ke endpoint batch Cloud Storage, yaitu https://storage.googleapis.com/batch/storage/v1. Bagian ini menjelaskan sintaksis batch secara mendetail; kemudian, akan muncul contoh.

Catatan: Kumpulan permintaan n yang dikelompokkan bersama akan mengurangi batas penggunaan dan biaya operasi Anda sebagai permintaan n, bukan sebagai satu permintaan. Permintaan batch dibagi menjadi satu set permintaan n sebelum diproses.

Format permintaan batch

Permintaan batch adalah satu permintaan HTTP standar yang berisi beberapa panggilan Cloud Storage JSON API. Permintaan utama ini menggunakan jenis konten multipart/mixed. Dalam permintaan HTTP utama, ada beberapa bagian yang masing-masing berisi permintaan HTTP bertingkat.

Setiap bagian dimulai dengan header HTTP Content-Type: application/http-nya sendiri. Bagian tersebut juga dapat memiliki header Content-ID opsional. Header ini menandai awal bagian, tetapi terpisah dari permintaan HTTP bertingkat. Ini berarti bahwa setelah server membuka permintaan batch ke dalam permintaan terpisah, header bagian akan diabaikan.

Isi setiap bagian itu sendiri merupakan permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isinya sendiri. Permintaan HTTP ini hanya boleh berisi bagian jalur URL; URL lengkap dapat memiliki perilaku yang tidak ditentukan.

Header HTTP untuk permintaan batch luar, kecuali untuk header Content- seperti Content-Type, juga berlaku untuk setiap permintaan bertingkat. Namun, jika Anda menentukan header HTTP tertentu dalam permintaan outer dan permintaan bertingkat, nilai header permintaan bertingkat akan menggantikan nilai header permintaan batch luar untuk permintaan khusus tersebut.

Misalnya, jika Anda memberikan header Authorization untuk permintaan bertingkat tertentu, header tersebut hanya akan berlaku untuk permintaan yang menentukannya. Jika Anda menyediakan header Authorization untuk permintaan luar, header tersebut akan berlaku untuk semua permintaan bertingkat kecuali jika Anda menggantinya dengan header Authorization-nya sendiri.

Saat menerima permintaan batch, Cloud Storage akan menerapkan header dan parameter kueri permintaan luar (yang sesuai) ke setiap bagian, lalu memperlakukan setiap bagian seolah-olah merupakan permintaan HTTP terpisah.

Respons terhadap permintaan batch

Respons Cloud Storage adalah satu respons HTTP standar dengan jenis konten multipart/mixed; setiap bagian dari respons utama ini adalah respons terhadap salah satu permintaan dalam permintaan batch. Urutan respons sama dengan permintaan.

Seperti semua bagian dalam permintaan, setiap bagian respons berisi respons HTTP lengkap, termasuk kode status, header, dan isi. Dan seperti bagian dalam permintaan, setiap bagian respons didahului dengan header Content-Type yang menandai awal bagian tersebut. Untuk mengetahui informasi lebih lanjut tentang kode status, baca artikel Status HTTP dan kode error untuk Cloud Storage JSON API.

Jika bagian permintaan tertentu memiliki header Content-ID, bagian respons yang sesuai memiliki header Content-ID yang cocok. Header Content-ID respons dimulai dengan response-, diikuti dengan nilai Content-ID yang digunakan dalam permintaan, seperti yang ditunjukkan dalam contoh.

Perhatian: Server dapat menjalankan permintaan Anda dalam urutan apa pun. Jangan mengandalkan permintaan yang dieksekusi sesuai urutan yang Anda tentukan. Untuk memastikan bahwa dua panggilan terjadi dalam urutan tertentu, kirim panggilan pertama dengan sendirinya, lalu tunggu respons ke panggilan pertama sebelum mengirim panggilan kedua.

Contoh

Contoh batch berikut mengupdate metadata kustom untuk tiga objek di example-bucket.

Contoh permintaan HTTP batch

HTTP

POST /batch/storage/v1 HTTP/1.1
Host: storage.googleapis.com
Content-Length: 960
Content-Type: multipart/mixed; boundary="===============7330845974216740156=="
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+1>

PATCH /storage/v1/b/example-bucket/o/obj1 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 31

{"metadata": {"type": "tabby"}}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+2>

PATCH /storage/v1/b/example-bucket/o/obj2 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 32

{"metadata": {"type": "tuxedo"}}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: <b29c5de2-0db4-490b-b421-6a51b598bd22+3>

PATCH /storage/v1/b/example-bucket/o/obj3 HTTP/1.1
Content-Type: application/json
accept: application/json
content-length: 32

{"metadata": {"type": "calico"}}
--===============7330845974216740156==--

Library klien

C++

Library klien C++ tidak mendukung permintaan batch.

C#

Library klien C# tidak mendukung permintaan batch.

Go

Library klien Go tidak mendukung permintaan batch.

Java

Untuk informasi selengkapnya, lihat dokumentasi referensi Cloud Storage Java API.

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Blob;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageBatch;
import com.google.cloud.storage.StorageOptions;
import java.util.HashMap;
import java.util.Map;

public class BatchSetObjectMetadata {
  public static void batchSetObjectMetadata(
      String projectId, String bucketName, String directoryPrefix) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

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

    // The directory prefix. All objects in the bucket with this prefix will have their metadata
    // updated
    // String directoryPrefix = "yourDirectory/";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();
    Map<String, String> newMetadata = new HashMap<>();
    newMetadata.put("keyToAddOrUpdate", "value");
    Page<Blob> blobs =
        storage.list(
            bucketName,
            Storage.BlobListOption.prefix(directoryPrefix),
            Storage.BlobListOption.currentDirectory());
    StorageBatch batchRequest = storage.batch();

    // Add all blobs with the given prefix to the batch request
    for (Blob blob : blobs.iterateAll()) {
      batchRequest.update(blob.toBuilder().setMetadata(newMetadata).build());
    }

    // Execute the batch request
    batchRequest.submit();

    System.out.println(
        "All blobs in bucket "
            + bucketName
            + " with prefix '"
            + directoryPrefix
            + "' had their metadata updated.");
  }
}

Node.js

Library klien Node.js tidak mendukung permintaan batch.

PHP

Library klien PHP tidak mendukung permintaan batch.

Python

Untuk informasi selengkapnya, lihat dokumentasi referensi Cloud Storage Python API.

from google.cloud import storage


def batch_request(bucket_name, prefix=None):
    """
    Use a batch request to patch a list of objects with the given prefix in a bucket.

    Note that Cloud Storage does not support batch operations for uploading or downloading.
    Additionally, the current batch design does not support library methods whose return values
    depend on the response payload.
    See https://cloud.google.com/python/docs/reference/storage/latest/google.cloud.storage.batch
    """
    # The ID of your GCS bucket
    # bucket_name = "my-bucket"
    # The prefix of the object paths
    # prefix = "directory-prefix/"

    client = storage.Client()
    bucket = client.bucket(bucket_name)

    # Accumulate in a list the objects with a given prefix.
    blobs_to_patch = [blob for blob in bucket.list_blobs(prefix=prefix)]

    # Use a batch context manager to edit metadata in the list of blobs.
    # The batch request is sent out when the context manager closes.
    # No more than 100 calls should be included in a single batch request.
    with client.batch():
        for blob in blobs_to_patch:
            metadata = {"your-metadata-key": "your-metadata-value"}
            blob.metadata = metadata
            blob.patch()

    print(
        f"Batch request edited metadata for all objects with the given prefix in {bucket.name}."
    )

Ruby

Untuk mempelajari cara membuat permintaan batch menggunakan Ruby, lihat dokumentasi referensi Cloud Storage Ruby API.

Contoh respons HTTP batch

Ini adalah respons terhadap permintaan contoh HTTP di bagian sebelumnya.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 3767

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+1>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/V43j6azD55CPRGb9b6uytDYl61Y"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj1/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "tabby"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+2>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/91POdd-sxSAkJnS8Dm7wMxBSDKk"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj2/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "tuxedo"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: <response-b29c5de2-0db4-490b-b421-6a51b598bd22+3>

HTTP/1.1 200 OK
ETag: "lGaP-E0memYDumK16YuUDM_6Gf0/d2Z1F1_ZVbB1dC0YKM9rX5VAgIQ"
Content-Type: application/json; charset=UTF-8
Date: Mon, 22 Jan 2018 18:56:00 GMT
Expires: Mon, 22 Jan 2018 18:56:00 GMT
Cache-Control: private, max-age=0
Content-Length: 846

{
 "kind": "storage#object",
 "id": "example-bucket/obj3/1495822576643790",
 .
 .
 .
 "metadata": {
  "type": "calico"
  },
  .
  .
  .
}

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--

Jika keseluruhan permintaan tidak diformat dengan benar dan Cloud Storage tidak dapat mengurainya menjadi sub-permintaan, Anda akan menerima error 400. Jika tidak, Cloud Storage akan menampilkan kode status 200, meskipun beberapa atau semua sub-permintaan gagal.

Saat keseluruhan permintaan ditampilkan dengan kode status 200, respons akan berisi hasil untuk setiap sub-permintaan, termasuk kode status untuk setiap sub-permintaan, yang menunjukkan apakah sub-permintaan berhasil atau gagal. Misalnya, saat menghapus objek secara massal, setiap sub-permintaan yang berhasil akan berisi kode status 204 No Content.