Giống như các API khác của Google, Google Ads API sử dụng giao thức OAuth 2.0 để xác thực và uỷ quyền. OAuth 2.0 cho phép ứng dụng Google Ads API của bạn truy cập vào tài khoản Google Ads của người dùng mà không cần xử lý hoặc lưu trữ thông tin đăng nhập của người dùng.
Hướng dẫn này trình bày cách định cấu hình thư viện ứng dụng Java để xác thực API Google Ads bằng 3 quy trình OAuth 2.0 phổ biến nhất, cùng với việc giải thích thông tin đăng nhập cần thiết.
Để tìm hiểu sâu hơn về mô hình truy cập API Google Ads, hãy đọc hướng dẫn về mô hình truy cập Google Ads.
Thông tin xác thực
Để truy cập vào Google Ads API, bạn cần có mã của nhà phát triển, thông tin đăng nhập OAuth 2.0 và trong một số trường hợp, bạn cần có mã khách hàng đăng nhập.
Mã của nhà phát triển
Mã thông báo của nhà phát triển được liên kết với một tài khoản người quản lý và có thể tìm thấy trong giao diện web của Google Ads.
Mặc dù mã thông báo của nhà phát triển được liên kết với một tài khoản người quản lý, nhưng mã thông báo này không cấp quyền truy cập vào tài khoản đó. Thay vào đó, mã thông báo của nhà phát triển cấp quyền truy cập vào API nói chung và quyền truy cập cấp tài khoản được định cấu hình thông qua OAuth 2.0.
Trong thư viện ứng dụng, mã thông báo nhà phát triển được chỉ định bằng khoá api.googleads.developerToken trong tệp ads.properties.
Thông tin đăng nhập OAuth 2.0
Để uỷ quyền với tư cách là người dùng Tài khoản Google có quyền truy cập vào tài khoản Google Ads, bạn phải cung cấp một bộ thông tin đăng nhập OAuth 2.0. Loại thông tin đăng nhập bắt buộc sẽ khác nhau tuỳ thuộc vào quy trình OAuth 2.0 đang được sử dụng.
Thư viện này hỗ trợ 3 quy trình:
- Luồng tài khoản dịch vụ
- Quy trình xác thực một người dùng
- Quy trình xác thực nhiều người dùng
Hãy tham khảo Tổng quan về OAuth để biết thông tin chi tiết về quy trình OAuth của Google Ads API, đồng thời làm theo hướng dẫn về quy trình phù hợp nhất với nhu cầu của bạn để lấy thông tin đăng nhập bắt buộc.
Mã khách hàng đăng nhập
Bạn có thể chỉ định mã khách hàng của một tài khoản người quản lý cấp quyền truy cập vào tài khoản phân phát. Bạn phải chỉ định thông tin này nếu truy cập vào tài khoản khách hàng thông qua tài khoản người quản lý. Bạn không cần chỉ định tất cả tài khoản người quản lý trên đường dẫn đến mã khách hàng, chỉ cần mã người quản lý trên cùng mà bạn đang sử dụng cho quyền truy cập. Để biết thêm thông tin chi tiết, hãy xem tài liệu liên quan.
Trong thư viện ứng dụng, mã khách hàng đăng nhập được chỉ định bằng khoá api.googleads.loginCustomerId trong tệp ads.properties.
Cấu hình
Bạn có thể định cấu hình thư viện ứng dụng bằng tệp ads.properties, biến môi trường hoặc theo phương thức lập trình. Hướng dẫn này tập trung vào việc sử dụng tệp ads.properties. Hãy xem Hướng dẫn về cấu hình để biết thông tin chi tiết về tất cả các lựa chọn.
Nếu bạn sử dụng tệp ads.properties, hãy đặt tệp đó vào thư mục gốc của bạn: ~/ads.properties.
Quy trình OAuth
Có 3 quy trình công việc thường dùng khi làm việc với Google Ads API.
Luồng tài khoản dịch vụ
Đây là quy trình được đề xuất nếu quy trình của bạn không yêu cầu bất kỳ hoạt động tương tác nào của con người. Quy trình này yêu cầu một bước thiết lập, trong đó người dùng thêm tài khoản dịch vụ vào tài khoản Google Ads của họ. Sau đó, ứng dụng có thể sử dụng thông tin đăng nhập của tài khoản dịch vụ để quản lý tài khoản Google Ads của người dùng.
Sau khi bạn có tệp JSON khoá riêng tư, hãy thêm nội dung sau vào tệp ads.properties:
api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE
Hãy tham khảo hướng dẫn về quy trình tài khoản dịch vụ để tìm hiểu thêm.
Quy trình xác thực một người dùng
Bạn có thể sử dụng quy trình này nếu không thể dùng tài khoản dịch vụ. Quy trình này yêu cầu 2 bước định cấu hình:
- Cấp cho một người dùng quyền truy cập vào tất cả các tài khoản cần quản lý bằng Google Ads API. Một phương pháp phổ biến là cấp cho người dùng quyền truy cập vào tài khoản người quản lý Google Ads API và liên kết tất cả tài khoản Google Ads trong tài khoản người quản lý đó.
- Người dùng chạy một công cụ dòng lệnh như gcloud hoặc ví dụ về mã
GenerateUserCredentialsđể uỷ quyền cho ứng dụng của bạn quản lý tất cả tài khoản Google Ads của họ thay cho họ.
Sau khi có thông tin đăng nhập này, hãy thêm nội dung sau vào tệp ads.properties của bạn:
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
Hãy tham khảo hướng dẫn về quy trình xác thực một người dùng để tìm hiểu thêm.
Quy trình xác thực nhiều người dùng
Đây là quy trình được đề xuất nếu ứng dụng của bạn cho phép người dùng đăng nhập và uỷ quyền cho ứng dụng của bạn quản lý tài khoản Google Ads thay cho họ. GenerateUserCredentials là một ví dụ về mã dòng lệnh minh hoạ cách lấy thông tin xác thực người dùng trong thời gian chạy để quản lý tài khoản Google Ads của họ thay cho họ. Bạn có thể sử dụng ví dụ về mã này làm tài liệu tham khảo để tạo các ứng dụng dành cho máy tính cần xác thực người dùng.
Thêm đoạn mã sau vào tệp ads.properties của bạn:
api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
Hãy tham khảo hướng dẫn về quy trình xác thực nhiều người dùng để tìm hiểu thêm.
Điều gì sẽ xảy ra nếu người dùng của tôi quản lý nhiều tài khoản?
Người dùng thường quản lý nhiều tài khoản Google Ads, thông qua quyền truy cập trực tiếp vào tài khoản hoặc thông qua tài khoản người quản lý Google Ads. Thư viện ứng dụng Java cung cấp các ví dụ về mã sau đây minh hoạ cách xử lý những trường hợp như vậy.
- Ví dụ về mã GetAccountHierarchy cho biết cách truy xuất danh sách tất cả tài khoản trong một tài khoản người quản lý Google Ads.
- Ví dụ về mã ListAccessibleCustomers cho biết cách truy xuất danh sách tất cả tài khoản mà người dùng có quyền truy cập trực tiếp.
Sau đó, bạn có thể dùng các tài khoản này làm giá trị hợp lệ cho chế độ cài đặt
LoginCustomerId.
Thông tin xác thực mặc định của ứng dụng
Thư viện ứng dụng Java cũng hỗ trợ xác thực bằng thông tin đăng nhập mặc định của ứng dụng.
Điều này đặc biệt hữu ích cho quá trình phát triển cục bộ hoặc phát triển dựa trên các API khác nhau của Google, vì bạn có thể sử dụng lại cùng một thông tin đăng nhập, miễn là thông tin đăng nhập đó có thể truy cập vào các phạm vi OAuth 2.0 chính xác.
Đối với API Google Ads, hãy đảm bảo thông tin đăng nhập mặc định của ứng dụng có thể truy cập vào phạm vi https://www.googleapis.com/auth/adwords OAuth 2.0.
Để sử dụng thông tin xác thực mặc định của ứng dụng, hãy đặt lựa chọn api.googleads.useApplicationDefaultCredentials thành true trong tệp ads.properties. Khi sử dụng thông tin đăng nhập mặc định của ứng dụng, bạn không nên đặt mã ứng dụng, khoá bí mật của ứng dụng và mã làm mới.