本指南包含直接呼叫 REST 端點的範例,不使用用戶端程式庫。
先備知識
下列所有範例都必須使用 curl 指令複製並貼進 bash 殼層。
您也需要開發人員權杖,可以提供測試帳戶存取權,以及包含至少一個客戶帳戶的 Google Ads 管理員帳戶。
環境變數
請在下方輸入帳戶憑證和 ID,然後複製貼上至終端機,設定後續範例中使用的環境變數。授權指南提供產生 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"
其他選用物件 ID
以下範例適用於現有的預算或廣告活動。如果您具有現有物件的 ID 可與範例搭配使用,請在下方輸入。
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
否則,這兩個 Mutates - Creates Example 的新建預算和廣告活動。
搜尋
查詢教戰手冊指南包含許多報表範例,這些範例與本指南中的部分預設 Google Ads 畫面相對應,以及與本指南中使用的環境變數相同。如果您要以互動方式建構自訂查詢,我們的互動式查詢建構工具也是絕佳的資源。
分為多頁
search
方法會使用分頁功能,其中固定頁面大小為 10,000 個項目,並在 query
旁邊指定 page_token
。
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}" }'
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'
串流裝置
searchStream
方法會以單一回應串流所有結果,因此不支援 pageSize
欄位。
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' " }'
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'
更改
藉由填入 operations
陣列,您可以在單一 JSON 要求主體中傳送多個 change 作業 (create
、update
或 remove
)。
建立
本例會在單次請求中建立兩筆共用預算。
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, } } ] }"
下一個範例使用現有廣告活動預算的 BUDGET_ID
;您可以複製及貼上上一個步驟的輸出內容。
BUDGET_ID=BUDGET_ID
參照其他資源的資源會使用資源名稱來執行這項作業。下方建立的廣告活動透過字串值資源名稱參照 campaignBudget
。
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': {} } } ] }"
更新
使用 update
作業更新現有物件的屬性。下一個範例使用現有的廣告活動;您可以複製及貼上前個步驟的輸出內容。
CAMPAIGN_ID=CAMPAIGN_ID
所有更新都需要 updateMask
欄位,這是一份以半形逗號分隔的清單,當中列出應在要求中納入哪些 JSON 屬性,且應做為更新套用。系統會針對物件清除 updateMask
中已列出但未在要求主體中的屬性。系統會忽略要求主體中未列於 updateMask
但要求主體的屬性。
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' } ], }"
移除
如要移除物件,請將物件的資源名稱指定為 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}' } ], }"
部分失敗
如果單一要求中有多項作業,可選擇指定 partialFailure
。如為 true
,則會執行成功的作業,並傳回無效作業的傳回錯誤。如果是 false
,則要求中的所有作業只有在所有作業都是有效狀態時才會成功。
下一個範例使用現有的廣告活動;您可以複製及貼上「Creates」(建立) 範例輸出內容。
CAMPAIGN_ID=CAMPAIGN_ID
以下要求包含兩項作業。先嘗試變更指定廣告活動的出價策略,之後再嘗試移除 ID 無效的廣告活動。由於第二次作業會導致錯誤 (廣告活動 ID 無效),且由於 partialFailure
設為 false
,因此第一項作業也會失敗,且現有廣告活動的出價策略不會更新。
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' } ] }"
分組作業
googleAds:mutate
方法支援傳送含有多種資源類型的作業群組。您可以傳送多種不同類型的作業,將一系列應以群組的形式執行的作業鏈結在一起。如果沒有任何一項作業失敗或全部失敗,則一組作業會成功。
這個範例說明如何將廣告活動預算、廣告活動、廣告群組和廣告視為一組動作。每項連續作業皆取決於先前的作業。如果其中一個作業失敗,整個群組的作業都會失敗。
負整數 (-1
、-2
、-3
) 會用做資源名稱的預留位置,並在執行階段動態填入作業序列的結果。
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'] } } } } ] }"
帳戶管理
建立帳戶
使用 createCustomerClient
方法建立新帳戶。請注意,此網址需要有管理員帳戶 ID,而非客戶帳戶 ID。系統會在管理員帳戶下建立新的客戶帳戶。
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' } }"
列出可存取的帳戶
對 listAccessibleCustomers
方法使用簡單的 GET
要求,取得可透過指定 OAuth 2.0 存取權杖存取的 Google Ads 帳戶清單。這個請求中不得使用管理員帳戶或客戶帳戶 ID。
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}" \
上傳二進位資產
assets:mutate
方法用於上傳及管理資產。二進位資料 (例如圖片) 使用含邊框間距的標準 Base64 編碼來編碼為字串。系統接受含邊框間距的標準或網址安全 Base64 編碼。
這個範例會編碼 1 像素的 GIF 圖片,讓範例保持精簡。實際上,data
酬載更大。
使用 base64
指令列公用程式 (GNU 核心公用程式的一部分) 將 1 像素 GIF 圖片編碼。
base64 1pixel.gif
Base64 編碼值會在 API 要求中指定為 data
屬性。
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' } } } ] }"