หน้านี้ได้รับการแปลโดย Cloud Translation API

การใช้ REST เพื่อเรียก API

เอกสารนี้จะอธิบายวิธีใช้ Custom Search JSON API

การส่งคำขอ

REST หรือ การโอนสถานะตัวแทนใน Custom Search JSON API จะแตกต่างจาก REST แบบดั้งเดิมอยู่บ้าง แทนที่จะให้สิทธิ์เข้าถึงทรัพยากร แต่ API จะให้สิทธิ์เข้าถึงบริการ ดังนั้น API จึงมี URI เดียวที่ทําหน้าที่เป็นปลายทางบริการ

คุณเรียกดูผลการค้นหาของการค้นหาหนึ่งๆ ได้โดยส่งคำขอ HTTP GET ไปยัง URI ของการค้นหานั้น โดยส่งรายละเอียดของคำขอการค้นหาเป็นพารามิเตอร์การค้นหา รูปแบบสำหรับ URI ของ Custom Search JSON API คือ

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

ต้องระบุข้อความค้นหา [parameters] 3 รายการในคำขอค้นหาแต่ละรายการ ดังนี้

คีย์ API - ใช้พารามิเตอร์การค้นหา key เพื่อระบุแอปพลิเคชันของคุณ
รหัส Programmable Search Engine - ใช้ cx เพื่อระบุ Programmable Search Engine ที่ต้องการใช้เพื่อค้นหา เครื่องมือค้นหาจะต้องสร้างโดยใช้แผงควบคุม หมายเหตุ: รหัสเครื่องมือค้นหา (CX) อาจอยู่ในรูปแบบอื่น (เช่น 8ac1ab64606d234f1)
คำค้นหา - ใช้พารามิเตอร์การค้นหา q เพื่อระบุนิพจน์การค้นหา

พารามิเตอร์การค้นหาอื่นๆ ทั้งหมดเป็นตัวเลือกที่ไม่บังคับ

ต่อไปนี้คือตัวอย่างของคำขอที่ค้นหาการบรรยายในการทดสอบ Programmable Search Engine

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

พารามิเตอร์การค้นหา

พารามิเตอร์ที่ส่งไปในคำขอได้มี 2 ประเภท ได้แก่

พารามิเตอร์เฉพาะ API - กำหนดพร็อพเพอร์ตี้ของการค้นหา เช่น นิพจน์การค้นหา จำนวนผลลัพธ์ ภาษา ฯลฯ
พารามิเตอร์การค้นหามาตรฐาน - ระบุแง่มุมทางเทคนิคของคำขอ เช่น คีย์ API

ค่าพารามิเตอร์ทั้งหมดต้องเป็น URL ที่เข้ารหัส

พารามิเตอร์การค้นหาเฉพาะ API

พารามิเตอร์คำขอที่ใช้กับ Custom Search JSON API โดยเฉพาะและกําหนดคําขอค้นหาจะสรุปไว้ในข้อมูลอ้างอิง

พารามิเตอร์การค้นหามาตรฐาน

พารามิเตอร์การค้นหาที่ใช้กับการดำเนินการ Custom Search JSON API ทั้งหมดจะมีการบันทึกไว้ที่พารามิเตอร์ของระบบ

ข้อมูลการตอบกลับ

หากคำขอสำเร็จ เซิร์ฟเวอร์จะตอบกลับด้วยรหัสสถานะ HTTP 200 OK และข้อมูลการตอบกลับในรูปแบบ JSON คุณดูโครงสร้างข้อมูลการตอบกลับได้ในข้อมูลอ้างอิง

ข้อมูลการตอบกลับจะเป็นออบเจ็กต์ JSON ซึ่งมีพร็อพเพอร์ตี้ 3 ประเภทดังนี้

ข้อมูลเมตาที่อธิบายการค้นหาที่ขอ (และคำขอการค้นหาที่เกี่ยวข้อง)
ข้อมูลเมตาที่อธิบาย Programmable Search Engine
ผลการค้นหา

ดูคำอธิบายโดยละเอียดของแต่ละพร็อพเพอร์ตี้ได้ในข้อมูลอ้างอิง

ข้อมูลเมตาของคำขอค้นหา

ข้อมูลเมตาของการค้นหาประกอบด้วยข้อมูลต่อไปนี้

url ซึ่งมีข้อมูลเกี่ยวกับเทมเพลต OpenSearch ที่ใช้สำหรับผลการค้นหาที่แสดงในคำขอนี้
queries ซึ่งเป็นอาร์เรย์ของออบเจ็กต์ที่อธิบายลักษณะของการค้นหาที่เป็นไปได้ ชื่อของแต่ละออบเจ็กต์ในอาร์เรย์จะเป็นชื่อของ บทบาทคำค้นหา OpenSearch หรือ 1 ใน 2 บทบาทที่กำหนดเองที่ API นี้กำหนด ดังนี้ previousPage และ nextPage ออบเจ็กต์บทบาทการค้นหาที่เป็นไปได้มีดังนี้
- request: ข้อมูลเมตาที่อธิบายการค้นหาของชุดผลการค้นหาปัจจุบัน
  - บทบาทนี้จะปรากฏในคำตอบเสมอ
  - โดยเป็นอาร์เรย์ที่มีองค์ประกอบเพียงองค์ประกอบเดียวเสมอ
  - nextPage: ข้อมูลเมตาที่อธิบายการค้นหาที่ใช้สำหรับผลการค้นหาหน้าถัดไป
    - จะไม่มีบทบาทนี้หากผลลัพธ์ปัจจุบันเป็นหน้าสุดท้าย หมายเหตุ: API นี้จะแสดงผลลัพธ์สูงสุด 100 รายการแรกเท่านั้น
    - หากปรากฏ จะเป็นอาร์เรย์ที่มีองค์ประกอบเพียงองค์ประกอบเดียวเสมอ
- previousPage: ข้อมูลเมตาที่อธิบายคำค้นหาที่จะใช้สำหรับหน้าผลการค้นหาก่อนหน้า
  - ไม่แสดงหากผลลัพธ์ปัจจุบันเป็นหน้าแรก
  - หากปรากฏ จะเป็นอาร์เรย์ที่มีองค์ประกอบเพียงองค์ประกอบเดียวเสมอ

ข้อมูลเมตาของเครื่องมือค้นหา

พร็อพเพอร์ตี้ context มีข้อมูลเมตาที่อธิบายเครื่องมือค้นหาที่ใช้คำค้นหา ซึ่งจะรวมถึงชื่อของเครื่องมือค้นหาและออบเจ็กต์ Facet ใดๆ ที่มีเพื่อใช้ปรับแต่งการค้นหา

ผลการค้นหา

อาร์เรย์ items มีผลการค้นหาจริง ผลการค้นหาจะมี URL, ชื่อ และตัวอย่างข้อความที่อธิบายผลการค้นหา นอกจากนี้ ส่วนขยายยังมีข้อมูลตัวอย่างข้อมูลสื่อสมบูรณ์ได้ด้วย (หากมี)

หากผลการค้นหามีพร็อพเพอร์ตี้ promotions ผลการค้นหานั้นก็จะมีชุดโปรโมชัน

REST จาก JavaScript

คุณเรียกใช้ Custom Search JSON API ได้โดยใช้ REST จาก JavaScript โดยใช้พารามิเตอร์การค้นหา callback และฟังก์ชันเรียกกลับ ซึ่งช่วยให้คุณเขียนแอปพลิเคชันแบบสมบูรณ์ที่แสดงข้อมูล Programmable Search Engine ได้โดยไม่ต้องเขียนโค้ดฝั่งเซิร์ฟเวอร์ใดๆ

ตัวอย่างต่อไปนี้ใช้วิธีการนี้เพื่อแสดงผลการค้นหาหน้าแรกสําหรับคําค้นหา 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>