本指南包含直接呼叫 REST 端點的範例，不使用用戶端程式庫。
必要條件
這裡顯示的所有範例都可複製並貼到 bash shell 中，然後使用 curl 指令。
您也需要開發人員權杖 (測試帳戶存取權即可)，以及至少包含一個客戶帳戶的 Google Ads 管理員帳戶。
環境變數
如畫面所示輸入帳戶憑證和 ID，然後複製並貼到終端機，設定後續範例中使用的環境變數。如需產生 OAuth 2.0 存取權杖的操作說明，請參閱「授權」指南。
API_VERSION="20"
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否則，這兩個「突變 - 建立範例」會建立新的預算和廣告活動。
搜尋
查詢食譜指南包含許多報表範例，這些範例對應部分 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'
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'
突變
您可以在單一 JSON 要求內文中填入 operations 陣列，傳送多個變動作業 (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，只有當要求中的所有作業都有效時，這些作業才會全部成功。
下一個範例使用現有廣告活動；您可以從「建立」範例輸出內容複製並貼上。
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' } } } ] }"