Meningkatkan performa

Kompresi menggunakan gzip

Cara yang mudah dan nyaman untuk mengurangi bandwidth yang diperlukan untuk setiap permintaan adalah dengan mengaktifkan kompresi gzip. Meskipun memerlukan waktu CPU tambahan untuk membatalkan kompresi hasil, keuntungannya dalam hal biaya jaringan biasanya sangat sepadan.

Untuk menerima respons yang dienkode dengan gzip, Anda harus melakukan dua hal: Menetapkan header Accept-Encoding dan memodifikasi agen pengguna agar berisi string gzip. Berikut adalah contoh header HTTP yang diformat dengan benar untuk mengaktifkan kompresi gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Menggunakan resource sebagian

Cara lain untuk meningkatkan performa panggilan API adalah dengan hanya meminta sebagian data yang Anda inginkan. Hal ini memungkinkan aplikasi Anda menghindari transfer, penguraian, dan penyimpanan kolom yang tidak dibutuhkan, sehingga dapat menggunakan resource, termasuk jaringan, CPU, dan memori, secara lebih efisien.

Respons sebagian

Secara default, server mengirimkan kembali representasi penuh resource setelah memproses permintaan. Untuk mendapatkan performa yang lebih baik, Anda dapat meminta server untuk hanya mengirim kolom yang benar-benar diperlukan dan mendapatkan respons sebagian.

Untuk meminta respons sebagian, gunakan parameter permintaan fields untuk menentukan kolom yang ingin ditampilkan. Anda dapat menggunakan parameter ini dengan permintaan apa pun yang menampilkan data respons.

Contoh

Contoh berikut menunjukkan penggunaan parameter fields dengan API "Demo" generik (fiktif).

Permintaan sederhana: Permintaan HTTP GET ini menghilangkan parameter fields dan menampilkan resource lengkap.

https://www.googleapis.com/demo/v1

Respons resource lengkap: Data resource lengkap mencakup kolom berikut, beserta banyak kolom lainnya yang tidak dicantumkan agar lebih ringkas.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Permintaan respons sebagian: Permintaan berikut untuk resource yang sama ini menggunakan parameter fields untuk mengurangi jumlah data yang ditampilkan secara signifikan.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Respons sebagian: Sebagai respons atas permintaan di atas, server mengirim kembali respons yang hanya berisi informasi jenis, beserta array item standar yang hanya menyertakan informasi karakteristik ukuran dan judul HTML di setiap item.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Perhatikan bahwa responsnya adalah objek JSON yang hanya menyertakan kolom yang dipilih dan objek induk yang mencakupnya.

Detail tentang cara memformat parameter fields akan dibahas di bagian berikutnya, diikuti dengan detail selengkapnya tentang hal-hal yang sebenarnya ditampilkan dalam respons.

Ringkasan sintaksis parameter fields

Format parameter value permintaan fields hanya didasarkan pada sintaksis XPath. Sintaksis yang didukung dirangkum di bawah ini, dan contoh lebih lanjut diberikan di bagian berikutnya.

• Gunakan comma separated list untuk memilih beberapa kolom.
• Gunakan a/b untuk memilih kolom b yang ditempatkan dalam kolom a; gunakan a/b/c untuk memilih kolom c yang ditempatkan di kolom b.
  

  Pengecualian: Jangan sertakan "data" di spesifikasi fields untuk respons API yang menggunakan wrapper "data", tempat respons disusun bertingkat dalam objek data yang terlihat seperti data: { ... }. Menyertakan objek data dengan spesifikasi kolom seperti data/a/b akan menyebabkan error. Sebagai gantinya, cukup gunakan spesifikasi fields seperti a/b.

• Gunakan sub-pemilih untuk meminta kumpulan sub-kolom tertentu dari array atau objek dengan menempatkan ekspresi dalam tanda kurung "( )".

  Misalnya: fields=items(id,author/email) hanya menampilkan ID item dan email penulis untuk setiap elemen dalam array item. Anda juga dapat menentukan satu sub-kolom, dengan fields=items(id) setara dengan fields=items/id.

• Gunakan karakter pengganti dalam pemilihan kolom, jika diperlukan.

  Misalnya: fields=items/pagemap/* memilih semua objek di pagemap.

Contoh lainnya terkait penggunaan parameter fields

Contoh di bawah menyertakan deskripsi tentang pengaruh parameter value fields terhadap respons.

Catatan: Seperti semua parameter value kueri, parameter value fields harus berenkode URL. Agar lebih mudah dibaca, contoh dalam dokumen ini tidak mencantumkan encoding.

Mengidentifikasi kolom yang ingin Anda tampilkan, atau membuat pilihan kolom.

Parameter value permintaan fields adalah comma separated list berisi kolom, dan setiap kolom ditentukan berdasarkan root responsnya. Jadi, jika Anda menjalankan operasi daftar, responsnya akan berupa kumpulan, dan biasanya mencakup array resource. Jika Anda melakukan operasi yang menampilkan satu resource, kolom akan ditetapkan berdasarkan resource tersebut. Jika kolom yang Anda pilih adalah (atau merupakan bagian dari) array, server akan menampilkan bagian yang dipilih dari semua elemen dalam array.

Berikut beberapa contoh tingkat kumpulan:

Contoh	Efek
items	Menampilkan semua elemen dalam array item, termasuk semua kolom di setiap elemen, tetapi tidak ada kolom lainnya.
etag,items	Menampilkan kolom etag dan semua elemen dalam array item.
items/title	Hanya menampilkan kolom title untuk semua elemen dalam array item. Setiap kali kolom yang disusun bertingkat ditampilkan, responsnya akan menyertakan objek induk yang mencakupnya. Kolom induk tidak menyertakan kolom turunan lainnya, kecuali jika kolom tersebut juga dipilih secara eksplisit.
context/facets/label	Hanya menampilkan kolom label untuk semua anggota array facets, yang ditempatkan dalam objek context.
items/pagemap/*/title	Untuk setiap elemen dalam array item, hanya menampilkan kolom title (jika ada) dari semua objek yang merupakan turunan dari pagemap.

Berikut beberapa contoh tingkat resource:

Contoh	Efek
title	Menampilkan kolom title untuk resource yang diminta.
author/uri	Menampilkan sub-kolom uri dari objek author dalam resource yang diminta.
links/*/href	Menampilkan kolom href dari semua objek yang merupakan turunan dari links.

Hanya meminta bagian kolom tertentu menggunakan sub-pilihan.

Secara default, jika permintaan Anda menentukan kolom tertentu, server akan menampilkan elemen array atau objek secara keseluruhan. Anda dapat menentukan respons yang hanya menyertakan sub-kolom tertentu. Caranya adalah menggunakan sintaksis sub-pilihan "( )", seperti pada contoh di bawah.

Contoh	Efek
items(title,author/uri)	Hanya menampilkan nilai title dan uri penulis untuk setiap elemen dalam array item.

Menangani respons sebagian

Setelah server memproses permintaan valid yang menyertakan parameter kueri fields, server akan mengirimkan kembali kode status HTTP 200 OK, bersama dengan data yang diminta. Jika parameter kueri fields mengalami error atau tidak valid, server akan menampilkan kode status HTTP 400 Bad Request bersama dengan pesan error yang memberi tahu pengguna tentang masalahnya dengan pemilihan kolom (misalnya, "Invalid field selection a/b").

Berikut adalah contoh respons sebagian yang ditampilkan di bagian pengantar di atas. Permintaan menggunakan parameter fields untuk menentukan kolom yang akan ditampilkan.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Respons sebagian akan terlihat seperti ini:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Catatan: Untuk API yang mendukung parameter kueri untuk penomoran halaman data (misalnya, maxResults dan nextPageToken), gunakan parameter tersebut untuk mengurangi hasil setiap kueri ke ukuran yang dapat dikelola. Jika tidak, peningkatan performa yang mungkin terjadi dengan respons sebagian mungkin tidak akan terlihat.