Permintaan batch

Akibat penghentian endpoint HTTP batch global, permintaan HTTP batch yang hanya menargetkan BigQuery API akan berhenti berfungsi pada 1 Juni 2021. Jika aplikasi Anda mengirimkan permintaan HTTP batch, ganti permintaan HTTP batch dengan permintaan HTTP individual sebelum 1 Juni 2021.

Untuk mengetahui informasi tentang penghentian penggunaan tersebut, lihat bagian FAQ berikut. Untuk dokumentasi tentang cara mengelompokkan permintaan HTTP, lihat Permintaan batch.

FAQ penghentian penggunaan HTTP API batch BigQuery

Mengapa permintaan HTTP batch BigQuery tidak digunakan lagi?

Dukungan untuk endpoint batch HTTP global didasarkan pada arsitektur yang menggunakan satu proxy bersama untuk menerima permintaan bagi semua API. Karena Google beralih ke arsitektur berperforma tinggi yang lebih terdistribusi dengan permintaan langsung menuju ke server API yang sesuai, kami tidak lagi mendukung endpoint global ini.

Menghentikan penggunaan permintaan HTTP batch BigQuery adalah langkah berikutnya. Layanan BigQuery juga didistribusikan. Metode QPS tinggi ditangani oleh backend khusus. Semua region diisolasi, tetapi permintaan HTTP batch dapat menyebabkan fanout permintaan lintas region. Hal ini membuat pengelompokan menjadi tidak efisien dan dapat menghasilkan latensi pemrosesan yang lebih tinggi, yang bertentangan dengan sasaran asli dari dukungan permintaan HTTP batch.

Hal apa yang secara spesifik tidak digunakan lagi?

Metode permintaan batch berikut untuk berinteraksi dengan BigQuery API tidak akan berfungsi lagi:

Bagaimana cara melakukan migrasi?

Sebagian besar pengguna BigQuery tidak menggunakan permintaan HTTP batch. Jika Anda masih menggunakan permintaan batch, gunakan contoh berikut untuk mengganti permintaan HTTP batch dengan permintaan HTTP individual.

REST

Kirim setiap permintaan HTTP seperti yang didokumentasikan di bagian referensi BigQuery API. Jangan gabungkan permintaan Anda dalam batch menggunakan jalur /batch/v2/bigquery.

JavaScript

Jika menggunakan JavaScript, Anda harus memulai dengan blok kode yang terlihat seperti ini:

// Notice that the outer batch request contains inner API requests
// for two different APIs.

// Request to urlshortener API
request1 = gapi.client.urlshortener.url.get({"shortUrl":
"http://goo.gl/fbsS"});

// Request to zoo API
request2 = gapi.client.zoo.animals.list();

// Request to urlshortener API
request3 = gapi.client.urlshortener.url.get({"shortUrl":
"https://goo.gl/XYFuPH"});

// Request to zoo API
request4 = gapi.client.zoo.animal().get({"name": "giraffe"});

// Creating a batch request object
batchRequest = gapi.client.newBatch();
// adding the 4 batch requests
batchRequest.add(request1);
batchRequest.add(request2);
batchRequest.add(request3);
batchRequest.add(request4);
// print the batch request
batchRequest.then(x=>console.log(x))

Ganti blok kode sebelumnya dengan blok kode yang terlihat seperti berikut:

// Request to urlshortener API
request1 = gapi.client.urlshortener.url.get({"shortUrl": "http://goo.gl/fbsS"});

// Request to zoo API
request2 = gapi.client.zoo.animals.list();

// Request to urlshortener API
request3 = gapi.client.urlshortener.url.get({"shortUrl": "http://goo.gl/fbsS"})

// Request to zoo API
request4 = gapi.client.zoo.animals.list();

// print the 4 individual requests
Promise.all([request1, request2, request3, request4])
    .then(x=>console.log(x));

Python

Jika Anda menggunakan Python, mulailah dengan blok kode yang terlihat seperti ini:

from apiclient.http import BatchHttpRequest

def insert_animal(request_id, response, exception):
  if exception is not None: # Do something with the exception
    pass
  else: # Do something with the response
    pass

service = build('farm', 'v2')
batch = service.new_batch_http_request(callback=insert_animal)
batch.add(service.animals().insert(name="sheep"))
batch.add(service.animals().insert(name="pig"))
batch.add(service.animals().insert(name="llama"))
batch.execute(http=http)

Ganti blok kode sebelumnya dengan blok kode yang terlihat seperti berikut:

# import a new API to create a thread pool
from concurrent.futures import ThreadPoolExecutor as PoolExecutor

def run_it(request):
  print(request.execute())

service = build('farm', 'v2')
request1 = service.animals().insert(name="sheep")
request2 = service.animals().insert(name="pig")
request3 = service.animals().insert(name="llama")
with PoolExecutor(max_workers=4) as executor:
  for _ in executor.map(run_it,[request1, request2, request3]):
    pass

Bahasa Lain

Serupa dengan contoh sebelumnya, ganti panggilan BatchRequest dengan masing-masing permintaan.

Mendapatkan dukungan untuk migrasi

Untuk mendapatkan bantuan terkait migrasi, Anda dapat mengajukan pertanyaan di Stack Overflow. Engineer Google memantau dan menjawab pertanyaan dengan tag google-bigquery. Gunakan tag ini saat mengajukan pertanyaan. Kami berupaya menjawab semua pertanyaan dalam jangka waktu yang wajar.

Permintaan pembuatan batch

Dokumen ini menunjukkan cara mengelompokkan panggilan API sekaligus untuk mengurangi jumlah koneksi HTTP yang harus dibuat oleh klien Anda.

Dokumen ini secara khusus membahas pembuatan permintaan batch dengan mengirim permintaan HTTP. Jika Anda menggunakan library klien Google untuk membuat permintaan batch, lihat dokumentasi library klien.

Ringkasan

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

Contoh situasi saat Anda mungkin ingin menggunakan pengelompokan:

  • Anda baru saja mulai menggunakan API dan memiliki banyak data untuk diupload.
  • Seorang pengguna membuat perubahan pada data saat aplikasi Anda offline (terputus dari internet), sehingga aplikasi Anda perlu menyinkronkan data lokalnya dengan server dengan mengirimkan banyak update dan penghapusan.

Dalam setiap kasus, daripada mengirim setiap panggilan secara terpisah, Anda dapat mengelompokkannya ke dalam satu permintaan HTTP. Semua permintaan internal harus mengarah ke Google API yang sama.

Anda dibatasi hingga 1.000 panggilan dalam satu permintaan batch. Jika Anda harus melakukan lebih banyak panggilan dari itu, gunakan beberapa permintaan batch.

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

Detail batch

Permintaan batch terdiri dari beberapa panggilan API yang digabungkan menjadi satu permintaan HTTP, yang dapat dikirim ke batchPath yang ditentukan dalam dokumen discovery API. Jalur default-nya adalah /batch/api_name/api_version. Bagian ini menjelaskan sintaksis batch secara mendetail; kemudian, akan muncul contoh.

Catatan: Kumpulan permintaan n yang dikelompokkan bersama-sama dihitung dalam batas penggunaan Anda sebagai permintaan n, bukan sebagai satu permintaan. Permintaan batch dibagi menjadi serangkaian permintaan sebelum diproses.

Format permintaan batch

Permintaan batch adalah satu permintaan HTTP standar yang berisi beberapa panggilan BigQuery API, menggunakan jenis konten multipart/mixed. Dalam permintaan HTTP utama tersebut, masing-masing bagian berisi permintaan HTTP bertingkat.

Setiap bagian dimulai dengan header HTTP Content-Type: application/http-nya sendiri. Class ini juga dapat memiliki header Content-ID opsional. Namun, header bagian hanya ada untuk menandai awal bagian; terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch menjadi permintaan terpisah, header bagian akan diabaikan.

Isi setiap bagian merupakan permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isinya sendiri. Permintaan HTTP hanya boleh berisi bagian jalur URL; URL lengkap tidak diizinkan dalam permintaan batch.

Header HTTP untuk permintaan batch luar, kecuali untuk header Content- seperti Content-Type, berlaku ke setiap permintaan dalam batch. Jika Anda menentukan header HTTP tertentu dalam permintaan outer dan panggilan individual, nilai header panggilan individual akan menggantikan nilai header permintaan batch luar. Header untuk setiap satu panggilan hanya berlaku untuk panggilan tersebut.

Misalnya, jika Anda memberikan header Otorisasi untuk suatu panggilan, header tersebut hanya akan berlaku untuk panggilan tersebut. Jika Anda memberikan header Otorisasi untuk permintaan luar, header tersebut akan berlaku untuk semua panggilan individual kecuali jika header tersebut menggantinya dengan header Otorisasi sendiri.

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

Respons terhadap permintaan batch

Respons server adalah satu respons HTTP standar dengan jenis konten multipart/mixed; setiap bagian adalah respons terhadap salah satu permintaan dalam batch permintaan, dalam urutan yang sama dengan permintaan tersebut.

Seperti 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 oleh header Content-Type yang menandai awal bagian.

Jika bagian tertentu dari permintaan memiliki header Content-ID, maka bagian respons yang sesuai memiliki header Content-ID yang cocok, dengan nilai asli yang diawali dengan string response-, seperti yang ditunjukkan dalam contoh berikut singkat ini.

Catatan: Server dapat melaksanakan panggilan Anda dengan urutan apa pun. Jangan menganggap eksekusinya dilakukan sesuai urutan yang Anda tentukan. Jika Anda ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirimkannya dalam satu permintaan; sebagai gantinya, kirim pesan pertama saja, lalu tunggu respons terhadap pesan pertama sebelum mengirim yang kedua.

Contoh

Contoh berikut menunjukkan penggunaan batch dengan API demo umum (fiksi) yang disebut Farm API. Namun, konsep yang sama berlaku untuk BigQuery API.

Contoh permintaan batch

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

Contoh respons batch

Ini adalah respons terhadap contoh permintaan di bagian sebelumnya.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--