Tài liệu này sẽ giúp bạn làm quen với API Tìm kiếm tuỳ chỉnh JSON và cách sử dụng nó.
Trước khi bắt đầu
Tạo Công cụ tìm kiếm có thể lập trình
Khi gọi API, người dùng sẽ đưa ra yêu cầu đối với một thực thể 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 API trong Bảng điều khiển. Làm theo hướng dẫn để tìm hiểu thêm về các tuỳ chọn cấu hình khác nhau.
Sau khi tạo mã này, bạn có thể tìm thấy Mã công cụ tìm kiếm trong phần Tổng quan của trang Cơ bản. Đây là tham số cx mà API sử dụng.
Xác định ứng dụng của bạn cho Google bằng khoá API
API Tìm kiếm tuỳ chỉnh JSON yêu cầu bạn phải sử dụng khoá API. Khoá API là một cách để Google xác định khách hàng của bạn.
- Người dùng Công cụ tìm kiếm có thể lập trình (phiên bản miễn phí): Nhận khóa
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 có thể an toàn để nhúng trong URL mà không cần phương thức mã hoá.
Tổng quan về API
Toán tử API
Chỉ có một phương thức để gọi trong API Tìm kiếm tuỳ chỉnh JSON:
| Hoạt động | Nội dung mô tả | Ánh xạ HTTP REST |
|---|---|---|
| list | Trả về kết quả tìm kiếm được yêu cầu từ mộ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 đối với API Tìm kiếm tuỳ chỉnh JSON là đố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 mà bạn yêu cầu (và có thể cả 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
Hãy xem mục Dữ liệu phản hồi trong bài viết Sử dụng REST để biết thêm chi tiết.
Mô hình dữ liệu này dựa trên Quy cách của OpenSearch 1.1. Ngoài các thuộc tính OpenSearch chuẩn, API JSON của Tìm kiếm tuỳ chỉnh xác định hai thuộc tính tuỳ chỉnh và hai vai trò của 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ả mức độ an toàn của tính năng tìm kiếm để lọc kết quả trả về.
- Vai trò truy vấn tuỳ chỉnh
nextPage: Vai trò cho biết truy vấn có thể dùng để truy cập vào trang kết quả logic tiếp theo (nếu có).previousPage: Có vai trò cho biết truy vấn có thể dùng để truy cập vào trang kết quả logic trước đó (nếu có).
Thử ngay
Để khám phá và xem API có thể làm gì mà không cần viết bất kỳ mã nào, hãy truy cập công cụ"Dùng thử API này".
Để biết 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 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 chuyển sang phần Sử dụng REST.