Meningkatkan Performa

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

Kompresi menggunakan gzip

Cara mudah dan nyaman untuk mengurangi bandwidth yang diperlukan untuk setiap permintaan adalah dengan mengaktifkan kompresi gzip. Meskipun hal ini memerlukan waktu CPU tambahan untuk membuka hasil, kompromi dengan biaya jaringan biasanya membuatnya sangat bermanfaat.

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

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

Bekerja dengan resource parsial

Cara lain untuk meningkatkan performa panggilan API Anda adalah dengan meminta hanya bagian 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.

Respons sebagian

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

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

Contoh

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

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

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

Respons resource penuh: Data resource lengkap mencakup kolom berikut, beserta 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 parsial: Sebagai respons terhadap permintaan di atas, server mengirimkan kembali respons yang hanya berisi informasi jenis beserta array item sederhana yang hanya menyertakan informasi judul dan karakteristik panjang 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 nilai parameter permintaan fields secara longgar berdasarkan sintaksis XPath. Sintaksis yang didukung dirangkum 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 di dalam kolom a; gunakan a/b/c untuk memilih kolom c yang disarangkan di dalam b.

    Pengecualian: Untuk respons API yang menggunakan wrapper data "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 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 menjelaskan deskripsi tentang bagaimana nilai parameter fields memengaruhi respons.

Catatan: Seperti semua nilai parameter kueri, nilai parameter fields harus dienkode ke URL. Agar lebih mudah dibaca, contoh dalam dokumen ini menghilangkan 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 secara 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 ditentukan 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, kecuali kolom lainnya.
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 mencakupnya. 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) untuk 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 tertentu 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. Anda melakukannya menggunakan "( )" sintaksis sub-pilihan, seperti dalam contoh di bawah.
Contoh Efek
items(title,author/uri) Hanya menampilkan nilai title dan uri penulis untuk setiap elemen dalam array item.

Menangani respons parsial

Setelah 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 HTTP 400 Bad Request, 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 ditampilkan di bagian pengantar di atas. Permintaan menggunakan parameter fields untuk menentukan kolom mana yang akan ditampilkan.

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

Respons sebagian 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.