Hướng dẫn này chứa các ví dụ về cách gọi trực tiếp điểm cuối REST mà không cần sử dụng thư viện ứng dụng.
Điều kiện tiên quyết
Tất cả các mẫu dưới đây được sao chép và dán vào shell shell bằng lệnh curl.
Bạn cũng cần có mã của nhà phát triển, quyền truy cập vào tài khoản thử nghiệm và một tài khoản người quản lý Google Ads có chứa ít nhất một tài khoản khách hàng.
Biến môi trường
Nhập thông tin đăng nhập và mã tài khoản ở bên dưới, sau đó sao chép và dán vào thiết bị đầu cuối của bạn để định cấu hình các biến môi trường được sử dụng trong các ví dụ tiếp theo. Hướng dẫn Uỷ quyền cung cấp hướng dẫn cách tạo mã truy cập OAuth 2.0.
API_VERSION="17"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"
Mã đối tượng không bắt buộc khác
Một số ví dụ sau đây áp dụng với ngân sách hoặc chiến dịch có sẵn. Nếu bạn có mã nhận dạng của các đối tượng hiện có để sử dụng với những ví dụ này, hãy nhập mã vào bên dưới.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Nếu không, hai ví dụ về Mutates – Creates (Tạo – Tạo) sẽ tạo ngân sách và chiến dịch mới.
Tìm kiếm
Hướng dẫn Cẩm nang về truy vấn chứa nhiều mẫu báo cáo tương ứng với một số màn hình mặc định của Google Ads và hoạt động với cùng các biến môi trường được dùng trong hướng dẫn này. Công cụ trình tạo truy vấn tương tác của chúng tôi cũng là một tài nguyên tuyệt vời để tạo các truy vấn tuỳ chỉnh có tính tương tác.
Được phân trang
Phương thức search
sử dụng tính năng phân trang, với kích thước trang cố định gồm 10.000 mục và page_token
được chỉ định cùng với query
.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
Google Analytics 4 (GAQL)
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Phát trực tiếp
Phương thức searchStream
truyền trực tuyến tất cả kết quả trong một phản hồi duy nhất, do đó trường pageSize
không được hỗ trợ.
cURL
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
Google Analytics 4 (GAQL)
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
Thay đổi
Bạn có thể gửi nhiều thao tác thay đổi (create
, update
hoặc remove
) trong một nội dung yêu cầu JSON duy nhất bằng cách điền sẵn mảng operations
.
Sáng tạo
Ví dụ này tạo hai ngân sách chiến dịch dùng chung trong một yêu cầu duy nhất.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
Ví dụ tiếp theo sử dụng BUDGET_ID
của ngân sách chiến dịch hiện tại; bạn có thể
sao chép và dán từ kết quả của bước trước.
BUDGET_ID=BUDGET_ID
Các tài nguyên tham chiếu đến các tài nguyên khác thông qua tên tài nguyên. Chiến dịch được tạo bên dưới
tham chiếu đến campaignBudget
theo tên tài nguyên có giá trị chuỗi.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
Bản cập nhật
Cập nhật thuộc tính của đối tượng hiện có bằng các toán tử update
. Ví dụ tiếp theo
sử dụng chiến dịch hiện tại; bạn có thể sao chép và dán từ kết quả của bước trước.
CAMPAIGN_ID=CAMPAIGN_ID
Tất cả các bản cập nhật đều phải có trường updateMask
. Đây là danh sách được phân tách bằng dấu phẩy liệt kê các thuộc tính JSON nên có trong yêu cầu và nên được áp dụng dưới dạng một bản cập nhật. Các thuộc tính được liệt kê trong updateMask
nhưng không có trong nội dung yêu cầu sẽ bị xoá trên một đối tượng. Các thuộc tính không được liệt kê trong updateMask
nhưng có trong nội dung yêu cầu sẽ bị bỏ qua.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
Xóa
Các đối tượng sẽ bị xoá bằng cách chỉ định tên tài nguyên là một toán tử remove
.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
Lỗi một phần
Khi nhiều thao tác nằm trong một yêu cầu, hãy chỉ định partialFailure
(không bắt buộc). Nếu true
, thao tác thành công sẽ được thực hiện và thao tác không hợp lệ sẽ trả về lỗi. Nếu là false
, tất cả thao tác trong yêu cầu sẽ thành công khi và chỉ khi tất cả các thao tác đó đều hợp lệ.
Ví dụ tiếp theo sử dụng một chiến dịch hiện có; bạn có thể sao chép và dán từ kết quả ví dụ về Tạo.
CAMPAIGN_ID=CAMPAIGN_ID
Yêu cầu sau đây chứa hai thao tác. Lần đầu tiên cố gắng thay đổi chiến lược giá thầu của chiến dịch đã cung cấp. Lần tiếp theo là thử xoá một chiến dịch có mã nhận dạng không hợp lệ. Vì thao tác thứ hai dẫn đến lỗi (mã chiến dịch không hợp lệ) và vì partialFailure
được đặt thành false
, nên thao tác đầu tiên cũng không thành công và chiến lược giá thầu của chiến dịch hiện tại không được cập nhật.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
Hoạt động được phân theo nhóm
Phương thức googleAds:mutate
hỗ trợ gửi các nhóm thao tác bằng nhiều loại tài nguyên. Bạn có thể gửi nhiều thao tác thuộc nhiều kiểu khác nhau để liên kết với nhau một trình tự các thao tác nên được thực hiện dưới dạng một nhóm.
Tập hợp thao tác này sẽ thành công nếu không có thao tác nào không thành công hoặc đều không thành công nếu có bất kỳ thao tác nào không thành công.
Ví dụ này minh hoạ việc tạo ngân sách chiến dịch, chiến dịch, nhóm quảng cáo và quảng cáo dưới dạng một tập hợp hành động duy nhất. Mỗi thao tác kế tiếp phụ thuộc vào thao tác trước đó. Nếu một thao tác không thành công thì toàn bộ nhóm thao tác sẽ không thành công.
Số nguyên âm (-1
, -2
, -3
) được dùng làm phần giữ chỗ trong tên tài nguyên và được điền tự động trong thời gian chạy bằng kết quả từ chuỗi thao tác.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
Quản lý tài khoản
Tạo tài khoản
Tạo tài khoản mới bằng phương thức createCustomerClient
. Xin lưu ý rằng URL này yêu cầu mã tài khoản người quản lý thay vì mã tài khoản khách hàng. Tài khoản khách hàng mới
sẽ được tạo trong tài khoản người quản lý.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
Liệt kê các tài khoản có thể truy cập
Sử dụng một yêu cầu GET
đơn giản đối với phương thức listAccessibleCustomers
để nhận danh sách
các tài khoản Google Ads có thể truy cập bằng mã truy cập OAuth 2.0 đã cho. Không được dùng mã tài khoản người quản lý hoặc mã tài khoản khách hàng trong yêu cầu này.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
Tải tài sản nhị phân lên
Phương thức assets:mutate
được dùng để tải lên và quản lý Thành phần. Dữ liệu nhị phân, chẳng hạn như hình ảnh, được mã hoá dưới dạng chuỗi bằng phương thức mã hoá base64 tiêu chuẩn có khoảng đệm. Chấp nhận phương thức mã hoá base64 chuẩn hoặc an toàn với URL có hoặc không có khoảng đệm.
Ví dụ này mã hoá ảnh GIF 1 pixel để mẫu ngắn gọn. Trên thực tế, các tải trọng data
lớn hơn nhiều.
Sử dụng tiện ích dòng lệnh base64
(một phần trong các tiện ích cốt lõi GNU) để mã hoá hình ảnh GIF 1 pixel.
base64 1pixel.gif
Giá trị được mã hoá base64 được chỉ định làm thuộc tính data
trong một yêu cầu API.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"