Đưa ra yêu cầu trực tiếp

Bạn nên sử dụng thư viện ứng dụng và mẫu để triển khai. Tuy nhiên, nếu việc tích hợp với API có nhu cầu đặc biệt, chẳng hạn như sử dụng ngôn ngữ không được hỗ trợ, thì bạn có thể đưa ra yêu cầu trực tiếp như mô tả bên dưới.

Kiểu gọi

REST là một kiểu cấu trúc phần mềm cung cấp phương pháp thuận tiện và nhất quán trong việc yêu cầu và sửa đổi dữ liệu.

Thuật ngữ REST là viết tắt của "Dịch vụ chuyển trạng thái đại diện". Trong ngữ cảnh của Google API, API này đề cập đến việc sử dụng các động từ HTTP để truy xuất và sửa đổi các cách trình bày dữ liệu do Google lưu trữ.

Trong hệ thống RESTful, các tài nguyên được lưu trữ trong kho dữ liệu; ứng dụng gửi yêu cầu để máy chủ thực hiện một hành động cụ thể (chẳng hạn như tạo, truy xuất, cập nhật hoặc xoá tài nguyên), sau đó máy chủ thực hiện hành động đó và gửi phản hồi, thường ở dạng đại diện cho tài nguyên đã chỉ định.

Trong các API RESTful của Google, ứng dụng chỉ định một thao tác bằng động từ HTTP như POST, GET, PUT hoặc DELETE. Phương thức này chỉ định tài nguyên bằng một URI duy nhất trên toàn cầu có dạng sau:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Vì tất cả các tài nguyên API đều có các URI duy nhất có thể truy cập HTTP, nên REST cho phép lưu dữ liệu vào bộ nhớ đệm và được tối ưu hoá để hoạt động với cơ sở hạ tầng phân phối của web.

Bạn có thể thấy định nghĩa về phương thức trong tài liệu về các tiêu chuẩn HTTP 1.1 hữu ích; các định nghĩa này bao gồm thông số kỹ thuật cho GET, POST, PUT và DELETE.

REST trong API Quản lý AdSense

Các thao tác được hỗ trợ ánh xạ trực tiếp đến các động từ HTTP REST, như mô tả trong Các thao tác của API Quản lý AdSense.

Định dạng cụ thể của URI API Quản lý AdSense là:

https://adsense.googleapis.com/v2/resourceID?parameters

trong đó resourceID là giá trị nhận dạng cho ứng dụng quảng cáo, đơn vị quảng cáo, kênh url, kênh tuỳ chỉnh hoặc tập hợp báo cáo, và parameters là bất kỳ thông số nào áp dụng cho truy vấn.

Định dạng của phần mở rộng đường dẫn resourceID cho phép bạn xác định tài nguyên mà bạn đang vận hành, ví dụ:

https://adsense.googleapis.com/v2/accounts/account_id/adclients
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/adunits/adUnitId
https://adsense.googleapis.com/v2/accounts/account_id/adclients/adClientId/urlchannels
...

Bạn có thể tóm tắt toàn bộ URI được sử dụng cho từng thao tác được hỗ trợ trong API trong tài liệu Tài liệu tham khảo về API Quản lý AdSense.

Dưới đây là một vài ví dụ về cách hoạt động của tính năng này trong AdSense Management API.

Liệt kê ứng dụng quảng cáo:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/

Liệt kê đơn vị quảng cáo trong ứng dụng quảng cáo ca-pub-1234567890123456:

GET https://adsense.googleapis.com/v2/accounts/account_id/adclients/ca-pub-1234567890123456/adunits

Định dạng dữ liệu

JSON (Ký hiệu đối tượng JavaScript) là một định dạng dữ liệu phổ biến, độc lập về ngôn ngữ, cung cấp bản trình bày văn bản đơn giản của các cấu trúc dữ liệu tuỳ ý. Để biết thêm thông tin, hãy xem json.org.

Ủy quyền yêu cầu

Xin lưu ý rằng AdSense không hỗ trợ Tài khoản dịch vụ. Thay vào đó, bạn phải sử dụng quy trình Ứng dụng đã cài đặt.

Mọi yêu cầu mà ứng dụng của bạn gửi tới API Quản lý AdSense phải bao gồm một mã thông báo uỷ quyền. Mã này cũng giúp Google xác định ứng dụng của bạn.

Giới thiệu về giao thức cấp phép

Ứng dụng của bạn phải sử dụng OAuth 2.0 để cấp phép các yêu cầu. Chúng tôi không hỗ trợ giao thức cấp phép nào khác. Nếu ứng dụng của bạn sử dụng chức năng Đăng nhập bằng Google, thì Google sẽ giúp bạn xử lý một số bước trong quá trình cấp phép.

Cấp phép cho các yêu cầu bằng OAuth 2.0

Tất cả các yêu cầu đối với API Quản lý AdSense phải do một người dùng đã xác thực thực hiện.

Quá trình này được hỗ trợ bằng mã ứng dụng khách OAuth.

Nhận mã ứng dụng khách OAuth

Hoặc tạo một mã trong trang Thông tin xác thực.

Các chi tiết của quy trình cấp phép đối với OAuth 2.0 sẽ khác nhau đôi chút tuỳ thuộc vào loại ứng dụng bạn đang viết. Quy trình chung sau đây áp dụng cho tất cả các loại ứng dụng:

  1. Khi cần quyền truy cập vào dữ liệu người dùng, ứng dụng sẽ yêu cầu Google cung cấp phạm vi truy cập cụ thể.
  2. Google hiển thị màn hình yêu cầu sự đồng ý cho người dùng để hỏi xem họ có cho phép ứng dụng của bạn yêu cầu một số dữ liệu của họ hay không.
  3. Nếu người dùng đồng ý, thì Google sẽ cấp cho ứng dụng của bạn một mã truy cập ngắn hạn.
  4. Sau đó, ứng dụng yêu cầu dữ liệu người dùng và đính kèm mã truy cập trong yêu cầu.
  5. Nếu xác định rằng yêu cầu của bạn và mã này là hợp lệ, Google sẽ trả về dữ liệu mà ứng dụng yêu cầu.

Một số quy trình cấp phép có các bước bổ sung khác, chẳng hạn như sử dụng mã làm mới để lấy mã truy cập mới. Để biết thông tin chi tiết về quy trình cho các loại ứng dụng khác nhau, hãy xem tài liệu về OAuth 2.0 của Google.

Dưới đây là thông tin về phạm vi truy cập OAuth 2.0 cho AdSense Management API:

Phạm vi Ý nghĩa
https://www.googleapis.com/auth/adsense Quyền truy cập đọc/ghi đối với dữ liệu AdSense.
https://www.googleapis.com/auth/adsense.readonly Quyền chỉ có thể đọc đối với dữ liệu AdSense.

Để yêu cầu quyền truy cập bằng OAuth 2.0, ứng dụng của bạn cần thông tin về mức truy cập, cũng như thông tin mà Google cung cấp khi bạn đăng ký ứng dụng của mình (chẳng hạn như mã ứng dụng khách và mật khẩu ứng dụng khách).

Mẹo: Thư viện ứng dụng API Google có thể xử lý một số bước trong quy trình cấp phép cho bạn. Thư viện này được cung cấp bằng nhiều ngôn ngữ lập trình. Hãy xem trang về các thư viện và mẫu để biết thêm chi tiết.

Gửi yêu cầu

Bước cuối cùng là tạo yêu cầu API. Hãy xem tài liệu tham khảo để biết thông tin cụ thể.