Trong quá trình làm việc với API Google Ads, hiểu rõ về cấu trúc của lệnh gọi API là điều vô cùng quan trọng để đảm bảo rằng yêu cầu và phản hồi đều được xử lý chính xác. Dù bạn đang sử dụng thư viện ứng dụng để tương tác với API hoặc trực tiếp gửi các lệnh HTTP, nắm rõ cách thức hoạt động của gRPC và REST sẽ giúp bạn kiểm thử và gỡ lỗi hiệu quả hơn. Trong bài viết này, chúng tôi sẽ cung cấp cho bạn cái nhìn tổng quan về cách cấu trúc lệnh gọi API, tiêu đề yêu cầu, ID tài nguyên và cách sử dụng mã tổng hợp trong API Google Ads.
Hướng dẫn này mô tả cấu trúc chung của tất cả các lệnh gọi API trong Google Ads.
Nếu bạn đang sử dụng thư viện ứng dụng để tương tác với API, việc nắm rõ chi tiết của yêu cầu cơ bản có thể không quá cần thiết. Tuy nhiên, hiểu một chút về cách thức hoạt động của các lệnh này sẽ giúp ích trong việc kiểm thử và gỡ lỗi hiệu quả hơn.
API Google Ads sử dụng giao thức gRPC, đi kèm với các liên kết REST, nghĩa là có hai cách để thực hiện lệnh gọi API:
- Ưu tiên: Tạo nội dung yêu cầu dưới dạng bộ đệm giao thức (protocol buffer), gửi qua HTTP/2, giải mã phản hồi thông qua giao thức gRPC, sau đó diễn giải kết quả. Hầu hết tài liệu của chúng tôi đều mô tả quy trình này thông qua gRPC.
- Không bắt buộc: Tạo nội dung yêu cầu dưới dạng đối tượng JSON, gửi qua HTTP 1.1, giải mã phản hồi dưới dạng JSON và diễn giải kết quả. Để biết thêm chi tiết về cách sử dụng giao diện REST, bạn có thể tham khảo hướng dẫn về kiến trúc chuyển trạng thái đại diện (REST).
Tên tài nguyên
Hầu hết các đối tượng trong API được xác định bởi chuỗi tên tài nguyên của chúng. Những chuỗi này cũng đóng vai trò như URL khi sử dụng giao diện REST. Bạn có thể tham khảo tài liệu về REST để hiểu rõ cấu trúc của tên tài nguyên.
Lưu ý quan trọng: Đảm bảo tham khảo tài liệu để xem danh sách tất cả các tài nguyên được hỗ trợ và cách biểu diễn đường dẫn của chúng, hay còn gọi là resource_name. Các dịch vụ khác nhau trong API đều tuân theo định dạng này.
ID tổng hợp
Khi mã nhận dạng của một đối tượng không mang tính duy nhất trên toàn hệ thống, ID tổng hợp sẽ được tạo bằng cách ghép thêm tiền tố ID mẹ và dấu ngã (~) để đảm bảo tính duy nhất.
Ví dụ, mã quảng cáo trong một nhóm quảng cáo có thể không duy nhất trên toàn cầu. Do đó, để tạo ra ID tổng hợp duy nhất, chúng tôi sẽ thêm ID của nhóm quảng cáo vào mã quảng cáo:
AdGroupId là 123 + ~ + AdGroupAdId là 45678 = ID tổng hợp cho quảng cáo trong nhóm là 123~45678.
Tiêu đề của yêu cầu
Dưới đây là các tiêu đề HTTP (hoặc siêu dữ liệu gRPC) cần đi kèm với nội dung trong yêu cầu API:
Ủy quyền (Authorization)
Bạn cần cung cấp mã truy cập OAuth2 dưới dạng Authorization: Bearer YOUR_ACCESS_TOKEN. Mã này xác định tài khoản người quản lý đang hành động trực tiếp thay mặt cho khách hàng hoặc nhà quảng cáo quản lý tài khoản của chính mình. Tham khảo hướng dẫn OAuth2 để biết cách truy xuất mã truy cập. Mã truy cập có hiệu lực trong vòng một giờ và khi hết hạn, bạn cần làm mới mã này để nhận mã mới. Lưu ý, thư viện ứng dụng sẽ tự động làm mới các mã truy cập hết hạn.
Mã nhà phát triển (developer-token)
Mã nhà phát triển là chuỗi gồm 22 ký tự xác định duy nhất một nhà phát triển API Google Ads. Ví dụ: ABcdeFGH93KL-NOPQ_STUv. Mã này phải được đặt trong tiêu đề với cú pháp developer-token: ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
Đây là mã khách hàng của tài khoản được ủy quyền trong yêu cầu, không chứa dấu gạch nối (-). Nếu bạn truy cập tài khoản khách hàng qua tài khoản người quản lý, tiêu đề này là bắt buộc và phải được đặt thành mã khách hàng của tài khoản người quản lý.
Từ khoá quan trọng:
“Khách hàng hoạt động” là mã khách hàng xuất hiện trong tải trọng yêu cầu. Ví dụ: trong yêu cầu tới CampaignBudgetService, khách hàng hoạt động có mã là 1234567890:
https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate
Việc đặt login-customer-id tương tự như khi bạn chọn một tài khoản trong giao diện Google Ads sau khi đăng nhập. Nếu không bao gồm tiêu đề này, mặc định tài khoản khách hàng đang hoạt động sẽ được sử dụng.
Lưu ý:
Bạn có thể truy xuất danh sách các tài khoản mà bạn có quyền truy cập bằng cách sử dụng CustomerService.ListAccessibleCustomers. Tiêu đề login-customer-id không bắt buộc đối với loại yêu cầu này và không ảnh hưởng đến danh sách khách hàng trả về.
linked-customer-id
Tiêu đề này được sử dụng bởi các nhà cung cấp phân tích ứng dụng bên thứ ba khi tải dữ liệu chuyển đổi lên tài khoản Google Ads đã liên kết với tài khoản khác.
Ví dụ, nếu người dùng trên tài khoản A cấp quyền truy cập đọc và chỉnh sửa cho tài khoản B thông qua ThirdPartyAppAnalyticsLink, tài khoản B sẽ có thể thực hiện các lệnh gọi API tới tài khoản A, dựa trên các quyền được cấp qua liên kết này. Trong trường hợp này, lệnh gọi API được thực hiện cho tài khoản A sẽ dựa trên mối liên kết của bên thứ ba với tài khoản B, thay vì dựa trên mối quan hệ giữa các tài khoản người quản lý.
Nhà cung cấp phân tích ứng dụng bên thứ ba thực hiện lệnh gọi API theo cách sau:
- linked-customer-id: Tài khoản của bên thứ ba đã tải dữ liệu (tài khoản B).
- customer-id: Tài khoản Google Ads mà dữ liệu đã được tải lên (tài khoản A).
- login-customer-id và Authorization: Tổ hợp các giá trị để xác định người dùng có quyền truy cập vào tài khoản B.
Tiêu đề phản hồi
Các tiêu đề sau (hoặc siêu dữ liệu gRPC) sẽ được trả về kèm theo nội dung phản hồi. Bạn nên ghi lại để hỗ trợ việc gỡ lỗi:
Mã yêu cầu
- request-id: Đây là chuỗi mã định danh duy nhất cho yêu cầu API này.
Việc hiểu rõ cấu trúc lệnh gọi API trong Google Ads sẽ giúp bạn tối ưu hóa quá trình tương tác với hệ thống, từ việc quản lý tài nguyên, sử dụng các mã tổng hợp đến việc xử lý các yêu cầu thông qua gRPC và REST. Điều này không chỉ cải thiện hiệu suất làm việc mà còn giúp bạn tránh được các lỗi phổ biến trong quá trình tương tác với API. Hãy chắc chắn rằng bạn nắm vững các tiêu đề và cấu trúc lệnh gọi để quản lý chiến dịch Google Ads của mình một cách chuyên nghiệp và hiệu quả.
