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 Tìm kiếm tuỳ chỉnh JSON có hơi 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 cấp quyền truy cập vào một dịch vụ. Do đó, API này cung cấp một URI đó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 tìm kiếm cụ thể bằng cách gửi HTTP GET đến URI của nó. Bạn chuyển thông tin chi tiết của yêu cầu tìm kiếm dưới dạng tham số truy vấn. Định dạng của URI JSON API Tìm kiếm tuỳ chỉnh là:

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

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

Khoá API – 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 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ể có đị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 kiểm tra Công cụ tìm kiếm có thể lập trình cho các 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ể chuyển vào yêu cầu của mình:

Tham số cụ thể theo API – xác định các thuộc tính tìm kiếm của bạn, như cụm từ 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, 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 theo API cụ thể

Yêu cầu các tham số áp dụng riêng cho API Tìm kiếm tuỳ chỉnh JSON và xác định được tóm tắt trong tài liệu tham khảo.

Tham số truy vấn chuẩn

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 được ghi lại tại 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 dữ liệu phản hồi cấu trúc trong tệp tham chiếu.

Dữ liệu phản hồi là đố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 theo yêu cầu (và có thể cả những yêu cầu 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

Để có 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 được dùng cho các kết quả được trả về trong yêu cầu này.
queries, là một mảng các đối tượng mô tả đặc điểm của các nội dung tìm kiếm có thể có. Tên của từng loại đối tượng trong mảng là tên của một Vai trò đối với cụm từ tìm kiếm OpenSearch hoặc một trong hai vai trò tuỳ chỉnh do API này xác định: previousPage và nextPage. Đối tượng vai trò truy vấn có thể có bao gồm:
- request: Siêu dữ liệu mô tả truy vấn dành cho nhóm hiện tại kết quả.
  - Vai trò này luôn xuất hiện trong câu trả lời.
  - Nó 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ả.
    - 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ó, đối tượng này 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ó, đối tượng này 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

Tài sản context có siêu dữ liệu mô tả công cụ tìm kiếm đã thực hiện truy vấn tìm kiếm. Tên 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à nó cung cấp tinh chỉnh 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ế. Tìm kiếm kết quả bao gồm URL, tiêu đề và đoạn văn bản mô tả kết quả. Trong chúng có thể chứa đoạn mã chi tiết thông tin, nếu có.

Nếu kết quả tìm kiếm bao gồm một tài sản promotions thì tài sản đó sẽ chứa một nhóm chương trình khuyến mãi.

Kiến trúc chuyển trạng thái đại diện (REST) từ JavaScript

Bạn có thể gọi API Tìm kiếm tuỳ chỉnh JSON bằng REST từ JavaScript, bằng cách sử 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 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 ghi mã phía máy chủ.

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 các kết quả 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>