API JSON cho Tìm kiếm tuỳ chỉnh: Giới thiệu

Tài liệu này sẽ giúp bạn làm quen với Custom Search JSON API và cách sử dụng API này.

Trước khi bắt đầu

Tạo Công cụ tìm kiếm có thể lập trình

Bằng cách gọi API, người dùng sẽ đưa ra yêu cầu đối với một phiên bản hiện có của Công cụ tìm kiếm có thể lập trình. Do đó, trước khi sử dụng API, bạn cần tạo một tài khoản trong Bảng điều khiển. Hãy làm theo hướng dẫn để tìm hiểu thêm về các lựa chọn cấu hình khác nhau. Sau khi tạo, bạn có thể tìm thấy Mã nhận dạng công cụ tìm kiếm trong phần Cơ bản của trang Tổng quan. Đây là tham số cx mà API sử dụng.

Xác định ứng dụng của bạn với Google bằng khoá API

Custom Search JSON API yêu cầu sử dụng khoá API. Khoá API là một cách để xác định ứng dụng của bạn với Google.

Sau khi có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả URL yêu cầu. Khoá API an toàn để nhúng vào URL, không cần mã hoá.

Tổng quan về API

Thao tác API

Chỉ có một phương thức để gọi trong Custom Search JSON API:

Hoạt động Mô tả Ánh xạ HTTP REST
list Trả về kết quả tìm kiếm được yêu cầu từ Công cụ tìm kiếm có thể lập trình. GET

Mô hình dữ liệu API

Kết quả của một cụm từ tìm kiếm gửi đến Custom Search JSON API là một đối tượng JSON bao gồm ba loại dữ liệu:

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

Hãy xem phần Dữ liệu phản hồi của bài viết Sử dụng REST để biết thêm thông tin.

Mô hình dữ liệu dựa trên Quy cách OpenSearch 1.1. Ngoài các thuộc tính OpenSearch tiêu chuẩn, Custom Search JSON API còn xác định hai thuộc tính tuỳ chỉnh và hai vai trò truy vấn tuỳ chỉnh:

  • Thuộc tính tuỳ chỉnh
    • cx: Giá trị nhận dạng của Công cụ tìm kiếm có thể lập trình.
    • safe: Nội dung mô tả về cấp độ tìm kiếm an toàn để lọc kết quả được trả về.
  • Vai trò truy vấn tuỳ chỉnh
    • nextPage: Một vai trò cho biết cụm từ tìm kiếm có thể được dùng để truy cập vào trang kết quả logic tiếp theo (nếu có).
    • previousPage: Một vai trò cho biết truy vấn có thể được dùng để truy cập vào trang kết quả logic trước đó (nếu có).

Dùng thử

Để khám phá và xem những việc API có thể làm mà không cần viết mã, hãy truy cập vào công cụ "Dùng thử API này".

Để xem nội dung mô tả đầy đủ về các tham số, hãy truy cập vào tài liệu tham khảo về cse.list.

Để tìm hiểu cách sử dụng API thông qua các yêu cầu HTTP, hãy tiếp tục xem phần Sử dụng REST.