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

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

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

ส่งคำขอ

REST หรือ Representational State Transfer ใน Custom Search JSON API นั้นแตกต่างจาก RESTful API ทั่วไป API ให้สิทธิ์เข้าถึงบริการแทนการให้สิทธิ์เข้าถึงทรัพยากร ด้วยเหตุนี้ API จึงมี URI รายการเดียวที่ทำหน้าที่เป็นปลายทางของบริการ

คุณสามารถดึงข้อมูลผลการค้นหาที่เฉพาะเจาะจงได้โดยส่งGETคำขอ HTTP ไปยัง 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 มีข้อมูลเมตาที่อธิบายเครื่องมือค้นหาที่ทำการค้นหา ซึ่งรวมถึงชื่อเครื่องมือค้นหาและออบเจ็กต์ฟาซิตที่เครื่องมือค้นหามีไว้เพื่อปรับแต่งการค้นหา

ผลการค้นหา

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

หากผลการค้นหามีพร็อพเพอร์ตี้ promotions แสดงว่ามีชุดโปรโมชัน

REST จาก JavaScript

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

ตัวอย่างต่อไปนี้ใช้แนวทางนี้เพื่อแสดงหน้าแรกของผลการค้นหาสําหรับคําค้นหา lecture

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; 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=lecture&callback=hndlr">
    </script>
  </body>
</html>