Menggunakan REST untuk Memanggil API

Dokumen ini menjelaskan cara menggunakan Custom Search JSON API.

Membuat permintaan

REST, atau Representational State Transfer, di Custom Search JSON API agak berbeda dengan REST tradisional. API memberikan akses ke layanan, bukan memberikan akses ke resource. Akibatnya, API menyediakan URI tunggal yang bertindak sebagai endpoint layanan.

Anda dapat mengambil hasil untuk penelusuran tertentu dengan mengirimkan GET HTTP ke URI-nya. Anda meneruskan detail permintaan penelusuran sebagai parameter kueri. Format URI Custom Search JSON API adalah:

https://www.googleapis.com/customsearch/v1?[parameters]

Tiga kueri [parameters] diperlukan untuk setiap permintaan penelusuran:

  • Kunci API - Gunakan parameter kueri key untuk mengidentifikasi aplikasi Anda.

  • Programmable Search Engine ID - Gunakan cx untuk menentukan Programmable Search Engine yang ingin Anda gunakan untuk melakukan penelusuran ini. Mesin telusur harus dibuat dengan Control Panel Catatan: ID Mesin Telusur (cx) dapat memiliki format yang berbeda (misalnya, 8ac1ab64606d234f1)

  • Kueri penelusuran - Gunakan parameter kueri q untuk menentukan ekspresi penelusuran Anda.

Semua parameter kueri lainnya bersifat opsional.

Berikut adalah contoh permintaan yang menelusuri uji Programmable Search Engine untuk ceramah:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Parameter kueri

Ada dua jenis parameter yang dapat Anda teruskan dalam permintaan Anda:

  • Parameter spesifik API - menentukan properti penelusuran Anda, seperti ekspresi penelusuran, jumlah hasil, bahasa, dll.
  • Parameter kueri standar - menentukan aspek teknis permintaan Anda, seperti Kunci API.

Semua nilai parameter harus dienkode ke URL.

Parameter kueri spesifik per API

Minta parameter yang berlaku khusus untuk JSON API Custom Search dan tentukan permintaan penelusuran dirangkum dalam referensi ini.

Parameter kueri standar

Parameter kueri yang berlaku untuk semua operasi JSON API Custom Search didokumentasikan di Parameter Sistem.

Data respons

Jika permintaan berhasil, server merespons dengan kode status HTTP 200 OK dan data respons dalam format JSON. Anda dapat melihat data respons dalam referensi.

Data respons adalah objek JSON yang mencakup tiga jenis properti:

  • Metadata yang menjelaskan penelusuran yang diminta (dan, mungkin, permintaan penelusuran terkait)
  • Metadata yang menjelaskan Programmable Search Engine
  • Hasil penelusuran

Untuk deskripsi mendetail tentang setiap properti, lihat referensi ini.

Telusuri metadata permintaan

Metadata penelusuran ini meliputi:

  • url, yang memiliki informasi tentang template OpenSearch digunakan untuk hasil yang ditampilkan dalam permintaan ini.
  • queries, yang merupakan array objek yang menggambarkan karakteristik kemungkinan penelusuran. Nama setiap objek dalam array bisa berupa nama objek Peran kueri OpenSearch atau salah satu dari dua peran khusus yang ditetapkan oleh API ini: previousPage dan nextPage. Kemungkinan objek peran kueri termasuk:
    • request: Metadata yang mendeskripsikan kueri untuk kumpulan data saat ini hasil pengujian tersebut.
      • Peran ini selalu ada dalam respons.
      • Elemen ini selalu berupa array yang hanya berisi satu elemen.
      • nextPage: Metadata yang mendeskripsikan kueri yang akan digunakan untuk kueri berikutnya laman hasil penelusuran.
        • Peran ini tidak ada jika hasil saat ini adalah halaman terakhir. Catatan: API ini hanya menampilkan 100 hasil pertama.
        • Jika ada, array selalu berisi hanya satu elemen.
    • previousPage: Metadata yang menjelaskan kueri yang akan digunakan untuk halaman hasil sebelumnya.
      • Tidak ada jika hasil saat ini adalah halaman pertama.
      • Jika ada, array selalu berisi hanya satu elemen.

Metadata mesin telusur

Properti context memiliki metadata yang menjelaskan mesin telusur yang menjalankan kueri penelusuran. Daftar ini mencantumkan nama mesin telusur, dan objek facet apa pun yang diberikannya menyaring penelusuran.

Hasil penelusuran

Array items berisi hasil penelusuran sebenarnya. Penelusuran hasil mencakup URL, judul, dan cuplikan teks yang menjelaskan hasil. Di beberapa Selain itu, aset tersebut dapat berisi cuplikan kaya tambahan, jika berlaku.

Jika hasil penelusuran menyertakan properti promotions, maka berisi sekumpulan promosi.

REST dari JavaScript

Anda dapat memanggil Custom Search JSON API menggunakan REST dari JavaScript, dengan Parameter kueri callback dan fungsi callback. Hal ini memungkinkan Anda untuk menulis aplikasi lengkap yang menampilkan data Programmable Search Engine tanpa menulis kode sisi server.

Contoh berikut menggunakan pendekatan ini untuk menampilkan halaman pertama penelusuran hasil untuk kueri cars:

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // Make sure HTML in item.htmlTitle is escaped.
        document.getElementById("content").append(
          document.createElement("br"),
          document.createTextNode(item.htmlTitle)
        );
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>