Trang này được dịch bởi Cloud Translation API.

Sử dụng REST để gọi API

Tài liệu này mô tả cách sử dụng API Tìm kiếm tuỳ chỉnh JSON.

Tạo yêu cầu

REST hay Chuyển trạng thái đại diện trong API JSON cho Tìm kiếm tuỳ chỉnh có phần khác so với REST truyền thống. Thay vì cấp quyền truy cập vào tài nguyên, API sẽ cung cấp quyền truy cập vào một dịch vụ. Do đó, API cung cấp một URI duy nhất đóng vai trò là điểm cuối của dịch vụ.

Bạn có thể truy xuất kết quả cho một lượt tìm kiếm cụ thể bằng cách gửi yêu cầu HTTP GET đến URI của yêu cầu đó. Bạn chuyển thông tin chi tiết về yêu cầu tìm kiếm dưới dạng tham số truy vấn. Định dạng của URI API Tìm kiếm tuỳ chỉnh JSON là:

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

Cần có 3 truy vấn [parameters] cho mỗi yêu cầu tìm kiếm:

Khoá API – Sử dụng tham số truy vấn key để xác định ứng dụng của bạn.
Mã Công cụ tìm kiếm có thể lập trình – Hãy sử dụng cx để chỉ định Công cụ tìm kiếm có thể lập trình mà bạn muốn sử dụng để thực hiện lượt tìm kiếm này. Bạn phải tạo công cụ tìm kiếm bằng Bảng điều khiển Lưu ý: Mã công cụ tìm kiếm (cx) có thể ở định dạng khác (ví dụ: 8ac1ab64606d234f1)
Cụm từ tìm kiếm – Sử dụng tham số truy vấn q để chỉ định biểu thức tìm kiếm.

Tất cả các tham số truy vấn khác là không bắt buộc.

Sau đây là ví dụ về một yêu cầu tìm kiếm trên Công cụ tìm kiếm có thể lập trình cho bài giảng:

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

Tham số truy vấn

Có hai loại thông số mà bạn có thể truyền vào yêu cầu của mình:

Tham số riêng cho API – xác định các thuộc tính của tìm kiếm, như biểu thức tìm kiếm, số lượng kết quả, ngôn ngữ, v.v.
Tham số truy vấn chuẩn – xác định các khía cạnh kỹ thuật của yêu cầu, chẳng hạn như khoá API.

Tất cả các giá trị thông số cần phải được mã hoá URL.

Tham số truy vấn dành riêng cho API

Bạn có thể xem tóm tắt thông tin tóm tắt về các yêu cầu áp dụng riêng cho API JSON của Tìm kiếm tuỳ chỉnh và xác định yêu cầu tìm kiếm trong tài liệu tham khảo.

Tham số truy vấn chuẩn

Bạn có thể xem những tham số truy vấn áp dụng cho tất cả hoạt động của API Tìm kiếm tuỳ chỉnh JSON tại phần System Parameters (Tham số hệ thống).

Dữ liệu phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và dữ liệu phản hồi ở định dạng JSON. Bạn có thể tra cứu cấu trúc dữ liệu phản hồi trong tài liệu tham khảo.

Dữ liệu phản hồi là một đối tượng JSON bao gồm 3 loại thuộc tính:

Siêu dữ liệu mô tả nội dung tìm kiếm được yêu cầu (và có thể cả yêu cầu nội dung tìm kiếm có liên quan)
Siêu dữ liệu mô tả Công cụ tìm kiếm có thể lập trình
Kết quả tìm kiếm

Để biết nội dung mô tả chi tiết về từng thuộc tính, hãy xem tài liệu tham khảo.

Siêu dữ liệu của yêu cầu tìm kiếm

Siêu dữ liệu tìm kiếm bao gồm:

Thuộc tính url có thông tin về mẫu OpenSearch dùng cho các kết quả được trả về trong yêu cầu này.
Thuộc tính queries, là một mảng các đối tượng mô tả các đặc điểm của nội dung tìm kiếm khả thi. Tên của từng đối tượng trong mảng là tên của một vai trò truy vấn OpenSearch hoặc một trong hai vai trò tuỳ chỉnh do API này xác định: previousPage và nextPage. Các đối tượng có vai trò truy vấn có thể có bao gồm:
- request: Siêu dữ liệu mô tả truy vấn cho tập hợp kết quả hiện tại.
  - Vai trò này luôn xuất hiện trong câu trả lời.
  - Đó luôn là một mảng chỉ có một phần tử.
  - nextPage: Siêu dữ liệu mô tả truy vấn cần sử dụng cho trang kết quả tiếp theo.
    - Vai trò này không xuất hiện nếu kết quả hiện tại là trang cuối cùng. Lưu ý: API này chỉ trả về tối đa 100 kết quả đầu tiên.
    - Nếu có, thì giá trị đó luôn là một mảng chỉ có một phần tử.
- previousPage: Siêu dữ liệu mô tả truy vấn cần sử dụng cho trang kết quả trước.
  - Không hiển thị nếu kết quả hiện tại là trang đầu tiên.
  - Nếu có, thì giá trị đó luôn là một mảng chỉ có một phần tử.

Siêu dữ liệu của công cụ tìm kiếm

Thuộc tính context có siêu dữ liệu mô tả công cụ tìm kiếm đã thực hiện cụm từ tìm kiếm. Phương thức này bao gồm tên của công cụ tìm kiếm và mọi đối tượng thuộc tính mà công cụ này cung cấp để tinh chỉnh hoạt động tìm kiếm.

Kết quả tìm kiếm

Mảng items chứa các kết quả tìm kiếm thực tế. Kết quả tìm kiếm bao gồm URL, tiêu đề và đoạn trích văn bản mô tả kết quả đó. Ngoài ra, các thẻ này có thể chứa thông tin về đoạn mã chi tiết, nếu có.

Nếu kết quả tìm kiếm bao gồm một thuộc tính promotions, thì thuộc tính đó sẽ chứa một tập hợp chương trình khuyến mãi.

REST từ JavaScript

Bạn có thể gọi API JSON cho Tìm kiếm tuỳ chỉnh bằng REST từ JavaScript, bằng cách dùng tham số truy vấn callback và hàm callback. Điều này cho phép bạn viết các ứng dụng đa dạng thức hiển thị dữ liệu của Công cụ tìm kiếm có thể lập trình mà không cần viết bất kỳ mã phía máy chủ nào.

Ví dụ sau đây sử dụng phương pháp này để hiển thị trang đầu tiên của kết quả tìm kiếm cho cụm từ tìm kiếm ô tô:

<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>