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 Custom Search JSON API có phần khác với các API RESTful thông thường. Thay vì cung cấp quyền truy cập vào tài nguyên, API 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 nội dung tìm kiếm cụ thể bằng cách gửi yêu cầu GET HTTP đến URI của nội dung đó. Bạn truyề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 URI của Custom Search JSON API là:

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

Mỗi yêu cầu tìm kiếm bắt buộc phải có 3 [parameters] truy vấn:

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 – 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ể có định dạng khác nhau (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ả tham số truy vấn khác đều là không bắt buộc.

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

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 tham số mà bạn có thể truyền trong yêu cầu:

Tham số dành riêng cho API – xác định các thuộc tính của nội dung tìm kiếm, chẳng hạn 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ả giá trị tham số đều phải được mã hoá URL.

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

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

Tham số truy vấn tiêu chuẩn

Các tham số truy vấn áp dụng cho tất cả các thao tác của API Tìm kiếm tuỳ chỉnh JSON được ghi lại tại 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 ba 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ể là các 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

Để 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 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 kết quả 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 các nội dung tìm kiếm có thể có. Tên của mỗi đố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 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 có trong phản hồi.
  - Luôn là một mảng chỉ có một phần tử.
  - nextPage: Siêu dữ liệu mô tả cụm từ tìm kiếm sẽ sử dụng cho trang kết quả tiếp theo.
    - Vai trò này sẽ 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.
    - Khi có, thuộc tính này luôn là một mảng chỉ có một phần tử.
- previousPage: Siêu dữ liệu mô tả cụm từ tìm kiếm sẽ sử dụng cho trang kết quả trước đó.
  - Không xuất hiện nếu kết quả hiện tại là trang đầu tiên.
  - Khi có, thuộc tính 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

Thuộc tính 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ệp này bao gồm tên của công cụ tìm kiếm và mọi đối tượng phân tích mà công cụ tìm kiếm cung cấp để tinh chỉnh nội dung tìm kiếm.

Kết quả tìm kiếm

Mảng items chứa 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 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 trích chi tiết, nếu có.

Nếu kết quả tìm kiếm có một tài sản promotions, thì kết quả đó 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 Tìm kiếm tuỳ chỉnh JSON bằng REST từ JavaScript, sử dụng tham số truy vấn callback và hàm gọi lại. Đ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ã nào ở 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 cho cụm từ tìm kiếm lecture (bài giảng):

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