本指南提供直接呼叫 REST 端點的範例，不使用用戶端程式庫。
必要條件
下列所有範例都應使用 curl 指令複製貼上至 bash 殼層中。
您也需要開發人員權杖 (測試帳戶存取權即可)，以及至少包含一個客戶帳戶的 Google Ads 管理員帳戶。
環境變數
請在下方輸入帳戶憑證和 ID，然後複製並貼到終端機中，以便設定後續範例中使用的環境變數。授權指南提供產生 OAuth 2.0 存取權杖的操作說明。
API_VERSION="19"
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 examples 會建立新的預算和廣告活動。
搜尋
「查詢食譜」指南包含許多報表範例，這些範例對應至部分預設 Google Ads 畫面，並使用本指南中使用的相同環境變數。我們的互動式查詢建構工具也是互動式建立自訂查詢的絕佳資源。
分為多頁
search 方法會使用分頁，固定頁面大小為 10,000 個項目，並在 query 旁邊指定 page_token。
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}" }'
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 -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' " }'
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 要求主體中傳送多個變異操作 (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' } }"
列出可存取的帳戶
使用簡單的 GET 要求，向 listAccessibleCustomers 方法取得可透過指定 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
在 API 要求中，base64 編碼的值會指定為 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' } } } ] }"