Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

範例

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

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

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

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

必要條件

這裡顯示的所有範例都應使用 curl 指令複製並貼到 bash 殼層中。

您也需要 Google Cloud 專案 (可使用測試帳戶存取權)，以及至少包含一個客戶帳戶的 Google Ads 管理員帳戶。

環境變數

輸入帳戶憑證和 ID (如圖所示)，然後複製並貼到終端機，設定後續範例中使用的環境變數。授權指南提供產生 OAuth 2.0 存取權杖的操作說明。

API_VERSION="26"
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 範例會建立新的預算和廣告活動。

搜尋

查詢錦囊妙計指南包含許多報表範例，這些範例對應到部分預設 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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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 "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

更改

建立

更新

移除

部分失敗

分組作業

帳戶管理

建立帳戶

列出可存取的帳戶

上傳二進位素材資源

範例