Halaman ini diterjemahkan oleh Cloud Translation API.

Tips Performa

Dokumen ini membahas beberapa teknik yang dapat Anda gunakan untuk meningkatkan performa aplikasi. Dalam beberapa kasus, contoh dari API lain atau API generik digunakan untuk mengilustrasikan ide yang disajikan. Namun, konsep yang sama berlaku untuk Books API.

Kompresi menggunakan gzip

Cara 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, kompromi dengan biaya jaringan biasanya sangat bermanfaat.

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

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

Menggunakan resource parsial

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

Ada dua jenis permintaan parsial:

Respons sebagian: Permintaan yang menentukan kolom yang akan disertakan dalam respons (gunakan parameter permintaan fields).
Patch: Permintaan pembaruan tempat Anda hanya mengirim kolom yang ingin diubah (gunakan kata kerja HTTP PATCH).

Detail selengkapnya tentang membuat permintaan parsial diberikan di bagian berikut.

Respons sebagian

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

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.

Perlu diketahui bahwa parameter fields hanya memengaruhi data respons; parameter ini tidak memengaruhi data yang perlu Anda kirim, jika ada. Untuk mengurangi jumlah data yang Anda kirim saat mengubah resource, gunakan permintaan patch.

Contoh

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

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

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

Respons resource penuh: Data resource lengkap mencakup kolom berikut, bersama dengan banyak kolom lainnya yang telah dihilangkan agar lebih singkat.

{
  "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 untuk respons parsial: Permintaan untuk resource yang sama berikut 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 terhadap permintaan di atas, server akan mengirim kembali respons yang hanya berisi informasi jenis beserta array item sederhana yang hanya mencakup informasi karakteristik panjang dan judul HTML dalam setiap item.

200 OK

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

Perhatikan bahwa respons adalah objek JSON yang hanya menyertakan kolom yang dipilih dan objek induknya yang mencakupnya.

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

Ringkasan sintaksis parameter kolom

Format parameter value permintaan fields secara longgar berdasarkan sintaksis XPath. Sintaksis yang didukung diringkas di bawah, dan contoh tambahan diberikan di bagian berikut.

Gunakan daftar yang dipisahkan koma untuk memilih beberapa kolom.
Gunakan a/b untuk memilih kolom b yang bertingkat dalam kolom a; gunakan a/b/c untuk memilih kolom c bertingkat di dalam b.

Pengecualian: Untuk respons API yang menggunakan wrapper "data", dengan respons ditempatkan dalam objek data yang terlihat seperti data: { ... }, jangan sertakan "data" dalam spesifikasi fields. 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) yang setara dengan fields=items/id.
Gunakan karakter pengganti dalam pilihan kolom, jika diperlukan.
Misalnya: fields=items/pagemap/* memilih semua objek dalam peta halaman.

Contoh lain penggunaan parameter kolom

Contoh di bawah ini mencakup deskripsi tentang bagaimana nilai parameter fields memengaruhi respons.

Catatan: Seperti semua nilai parameter kueri, nilai parameter fields harus dienkode URL. Untuk keterbacaan yang lebih baik, contoh dalam dokumen ini menghapus encoding.

Identifikasi kolom yang ingin Anda kembalikan, atau buat pilihan kolom.

Nilai parameter permintaan fields adalah daftar kolom yang dipisahkan koma, dan setiap kolom ditentukan relatif terhadap root respons. Jadi, jika Anda menjalankan operasi daftar, responsnya adalah koleksi, dan umumnya mencakup array resource. Jika Anda melakukan operasi yang menampilkan satu resource, kolom akan ditetapkan secara relatif terhadap 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 koleksi:

Contoh	Efek
`items`	Menampilkan semua elemen dalam array item, termasuk semua kolom di setiap elemen, tetapi tidak dalam kolom lain.
`etag,items`	Menampilkan kolom `etag` dan semua elemen dalam array item.
`items/title`	Menampilkan kolom `title` saja untuk semua elemen dalam array item. Setiap kali kolom bertingkat ditampilkan, respons akan menyertakan objek induk yang mencakup. Kolom induk tidak menyertakan kolom turunan lain kecuali jika kolom tersebut juga dipilih secara eksplisit.
`context/facets/label`	Hanya menampilkan kolom `label` untuk semua anggota array `facets`, yang bertingkat di bawah 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` dari resource yang diminta.
`author/uri`	Menampilkan sub-kolom `uri` dari objek `author` di resource yang diminta.
`links/*/href`	Menampilkan kolom `href` dari semua objek yang merupakan turunan dari `links`.

Minta hanya bagian tertentu dari kolom menggunakan sub-pilihan.

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

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

Menangani respons parsial

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

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

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

Respons sebagiannya 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 parsial mungkin tidak akan terwujud.

Patch (pembaruan sebagian)

Anda juga dapat menghindari pengiriman data yang tidak perlu saat memodifikasi resource. Untuk mengirim data yang diperbarui hanya untuk kolom tertentu yang Anda ubah, gunakan kata kerja HTTP PATCH. Semantik patch yang dijelaskan dalam dokumen ini berbeda (dan lebih sederhana) dibandingkan dengan penerapan GData update parsial yang lebih lama.

Contoh singkat di bawah menunjukkan bagaimana penggunaan patch meminimalkan data yang perlu Anda kirim untuk membuat update kecil.

Contoh

Contoh ini menunjukkan permintaan patch sederhana untuk hanya memperbarui judul resource API "Demo" generik (fiksi). Resource ini juga memiliki komentar, serangkaian karakteristik, status, dan banyak kolom lainnya, tetapi permintaan ini hanya mengirim kolom title, karena itu adalah satu-satunya kolom yang diubah:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Respons:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Server menampilkan kode status 200 OK, beserta representasi lengkap dari resource yang diperbarui. Karena hanya kolom title yang disertakan dalam permintaan patch, itu adalah satu-satunya nilai yang berbeda dari sebelumnya.

Catatan: Jika Anda menggunakan parameter fields respons parsial yang dikombinasikan dengan patch, Anda dapat meningkatkan efisiensi permintaan pembaruan lebih lanjut. Permintaan patch hanya mengurangi ukuran permintaan. Respons parsial mengurangi ukuran respons. Jadi, untuk mengurangi jumlah data yang dikirim di kedua arah, gunakan permintaan patch dengan parameter fields.

Semantik permintaan patch

Isi permintaan patch hanya menyertakan kolom resource yang ingin diubah. Saat menentukan kolom, Anda harus menyertakan objek induk yang melipatnya, seperti induk yang disertakan yang ditampilkan dengan respons sebagian. Data yang diubah yang Anda kirim akan digabungkan ke dalam data untuk objek induk, jika ada.

Tambahkan: Untuk menambahkan kolom yang belum ada, tentukan kolom baru dan nilainya.
Mengubah: Untuk mengubah nilai kolom yang ada, tentukan kolom dan tetapkan ke nilai baru.
Hapus: Untuk menghapus kolom, tentukan kolom dan tetapkan ke null. Misalnya, "comment": null. Anda juga dapat menghapus seluruh objek (jika dapat diubah) dengan menyetelnya ke null. Jika Anda menggunakan Library Klien Java API, gunakan Data.NULL_STRING. Untuk detailnya, lihat JSON null.

Catatan tentang array: Permintaan patch yang berisi array menggantikan array yang ada dengan yang Anda berikan. Anda tidak dapat memodifikasi, menambahkan, atau menghapus item dalam array dengan cara sedikit demi sedikit.

Menggunakan patch dalam siklus baca-ubah-tulis

Ini dapat menjadi praktik yang berguna untuk memulai dengan mengambil respons parsial dengan data yang ingin Anda ubah. Hal ini sangat penting untuk resource yang menggunakan ETag, karena Anda harus memberikan nilai ETag saat ini dalam header HTTP If-Match agar berhasil memperbarui resource. Setelah mendapatkan data, Anda kemudian dapat mengubah nilai yang ingin diubah dan mengirim kembali representasi parsial yang dimodifikasi dengan permintaan patch. Berikut adalah contoh yang mengasumsikan resource Demo menggunakan ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Ini adalah respons sebagian:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Permintaan patch berikut didasarkan pada respons tersebut. Seperti yang ditunjukkan di bawah ini, parameter ini juga menggunakan parameter fields untuk membatasi data yang ditampilkan dalam respons patch:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Server merespons dengan kode status HTTP 200 OK, dan representasi parsial dari resource yang diperbarui:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Membuat permintaan patch secara langsung

Untuk beberapa permintaan patch, Anda harus mendasarkannya pada data yang sebelumnya Anda ambil. Misalnya, jika ingin menambahkan item ke array dan tidak ingin kehilangan elemen array yang ada, Anda harus mendapatkan data yang ada terlebih dahulu. Demikian pula, jika API menggunakan ETag, Anda perlu mengirim nilai ETag sebelumnya dengan permintaan agar berhasil memperbarui resource.

Catatan: Anda dapat menggunakan header HTTP "If-Match: *" untuk memaksa patch dijalankan saat ETag sedang digunakan. Jika Anda melakukannya, Anda tidak perlu melakukan operasi baca sebelum operasi tulis.

Namun, untuk situasi lain, Anda dapat membuat permintaan patch secara langsung, tanpa terlebih dahulu mengambil data yang ada. Misalnya, Anda dapat dengan mudah menyiapkan permintaan patch yang memperbarui kolom ke nilai baru atau menambahkan kolom baru. Berikut contohnya:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Dengan permintaan ini, jika kolom komentar memiliki nilai yang ada, nilai baru akan menimpanya; jika tidak, nilai baru akan ditetapkan ke nilai baru. Demikian pula, jika ada karakteristik volume, nilainya akan ditimpa; jika tidak, nilai akan dibuat. Kolom akurasi, jika ditetapkan, akan dihapus.

Menangani respons terhadap patch

Setelah memproses permintaan patch yang valid, API akan menampilkan kode respons HTTP 200 OK bersama dengan representasi lengkap dari resource yang dimodifikasi. Jika ETag digunakan oleh API, server akan memperbarui nilai ETag saat berhasil memproses permintaan patch, seperti yang dilakukan dengan PUT.

Permintaan patch menampilkan seluruh representasi resource kecuali jika Anda menggunakan parameter fields untuk mengurangi jumlah data yang ditampilkan.

Jika permintaan patch menghasilkan status resource baru yang secara sintaksis atau semantik tidak valid, server akan menampilkan kode status HTTP 400 Bad Request atau 422 Unprocessable Entity, dan status resource tidak akan berubah. Misalnya, jika Anda mencoba menghapus nilai untuk kolom yang wajib diisi, server akan menampilkan error.

Notasi alternatif saat kata kerja HTTP PATCH tidak didukung

Jika firewall Anda tidak mengizinkan permintaan HTTP PATCH, lakukan permintaan HTTP POST dan setel header penggantian ke PATCH, seperti yang ditunjukkan di bawah:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Perbedaan antara patch dan update

Dalam praktiknya, saat mengirim data untuk permintaan update yang menggunakan kata kerja PUT HTTP, Anda hanya perlu mengirim kolom yang wajib diisi atau opsional; jika Anda mengirim nilai untuk kolom yang ditetapkan oleh server, nilai tersebut akan diabaikan. Meskipun sepertinya ini adalah cara lain untuk melakukan update sebagian, pendekatan ini memiliki beberapa batasan. Dengan update yang menggunakan kata kerja PUT HTTP, permintaan akan gagal jika Anda tidak memberikan parameter yang diperlukan, dan tindakan ini akan menghapus data yang ditetapkan sebelumnya jika Anda tidak menyediakan parameter opsional.

Jauh lebih aman untuk menggunakan patch karena alasan ini. Anda hanya memberikan data untuk kolom yang ingin diubah; kolom yang Anda hapus tidak akan dihapus. Satu-satunya pengecualian untuk aturan ini terjadi pada elemen atau array berulang: Jika Anda menghapus semuanya, elemen tersebut akan tetap seperti itu; jika Anda memberikan salah satunya, seluruh set akan diganti dengan set yang Anda berikan.