本頁面由 Cloud Translation API 翻譯而成。

範例

本指南包含直接呼叫 REST 端點的範例，不使用用戶端程式庫。

如需更詳細的程式碼範例，請參閱 REST 程式碼範例 GitHub 存放區。

如要查看各個 API 方法的要求和回應主體，請參閱特定服務端點的參考說明文件。

舉例來說，GoogleAdsService.Search 的參考頁面會顯示 Search 方法的要求和回應內文。

必要條件

這裡顯示的所有範例都可複製並貼到 bash shell 中，然後使用 curl 指令。

您也需要開發人員權杖，測試帳戶存取權即可，以及包含至少一個客戶帳戶的 Google Ads 管理員帳戶。

環境變數

如畫面所示輸入帳戶憑證和 ID，然後複製並貼到終端機，設定後續範例使用的環境變數。如需產生 OAuth 2.0 存取權杖的操作說明，請參閱「授權」指南。

API_VERSION="22"
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'

串流

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'

Mutates

如要透過單一 JSON 要求內文傳送多項變動作業 (create、update 或 remove)，請填入 operations 陣列。

建立

這個範例會在單一要求中建立兩個共用廣告活動預算。

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

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'
      }
    }
  }
]
}"

常見錯誤

試試看！

範例 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要條件

環境變數

其他選用物件 ID

搜尋

分為多頁

curl

GAQL

串流

curl

GAQL

Mutates

建立

更新

移除

部分失敗

分組作業

帳戶管理

建立帳戶

列出可存取的帳戶

上傳二進位資產

範例