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

Google Ads API 新手上路指南

本指南詳細說明瞭新手上路、驗證及首次呼叫 Google Ads API 的完整流程。

1. 必要條件和帳戶階層

與 Google Ads API 互動前，請務必瞭解帳戶階層，並建立正確的頂層帳戶結構。

管理員帳戶 (MCC)：Google Ads 管理員帳戶 (前稱「我的客戶中心」) 是主要帳戶，可用於查看及管理多個客戶帳戶。您必須擁有管理員帳戶，才能申請 Google Ads API 開發人員權杖。
客戶帳戶：標準帳戶，用於建立廣告活動、廣告群組和廣告，以及設定帳單。

待辦事項：如果您沒有管理員帳戶，請前往 Google Ads 管理員帳戶建立帳戶。

2. 取得開發人員權杖

開發人員權杖可讓 Google Ads API 識別您的應用程式，並控管您的呼叫量存取層級。

申請步驟

登入 Google Ads 管理員帳戶。
依序前往「工具和設定」>「設定」>「API 中心」 (或「管理」>「API 中心」)。
填寫開發人員詳細資料表單，並同意《API 服務條款》。
提出申請。

存取層級

待核准：新建立的權杖會立即顯示「待處理」狀態。您可以使用待處理的權杖立即連結測試帳戶，但無法連結實際執行帳戶。
基本存取權：獲准後，每天最多可執行 15,000 項 API 作業。
標準存取權：對於符合基本必備功能 (RMF) 的應用程式，每日 API 作業數量不受限制。

3. 設定測試帳戶

在實際帳戶中開發及測試，可能會產生不必要的廣告支出和廣告活動修改。強烈建議您針對測試帳戶執行所有開發作業。

建立測試管理員帳戶

前往 Google Ads 測試管理員帳戶建立頁面。
使用尚未連結至正式版 Google Ads 管理員帳戶的 Google 帳戶登入。
輸入描述性帳戶名稱 (例如 MyCompany Test MCC)。
選取「管理其他人的帳戶」做為主要用途。
選擇帳單國家/地區、時區和貨幣。按一下「儲存並繼續」。

建立測試客戶帳戶

建立測試管理員帳戶後，您必須建立至少一個子項客戶帳戶，才能放送測試廣告活動。

登入新建立的測試管理員帳戶。
按一下左側導覽選單的「帳戶」，然後選取「子帳戶設定」(或「成效」)。
按一下藍色「+」按鈕，然後選取「建立新帳戶」。
選取 Google Ads 帳戶。
輸入帳戶名稱 (例如 Test Client Account A)。
選取時區和幣別，然後按一下「儲存並繼續」。
記下這個新客戶帳戶的 10 位數客戶 ID (例如 1234567890，不含連字號)。

測試帳戶的重要規則

開發人員權杖使用方式：請勿透過測試管理員帳戶申請開發人員權杖。請務必使用正式版管理員帳戶中待處理或已核准的開發人員權杖。
帳單：測試帳戶不會放送實際廣告，因此您不需要輸入真實的帳單資訊。

4. 設定 Google Cloud 專案

所有 API 要求都必須使用已啟用 Google Ads API 的 Google Cloud 專案進行驗證。

啟用 API 的步驟

前往 Google Cloud 控制台。
建立新專案或選取現有專案。
依序前往「APIs & Services」(API 和服務) >「Library」(程式庫)。
搜尋「Google Ads API」，然後點選「啟用」。

價格與計費

免付 API 費用：建立 Google Cloud 雲端專案、啟用 Google Ads API，以及產生 OAuth 2.0 憑證，完全免費。Google 不會針對呼叫或使用 Google Ads API 本身收取任何費用。
其他雲端資源：只有在您主動使用其他可計費的 Google Cloud 服務 (例如 Compute Engine、Cloud Run 或 BigQuery)，且用量超出免費方案限制時，才會產生 Google Cloud 費用，這些服務可用於代管應用程式或儲存廣告資料。

5. OAuth 2.0 驗證設定

Google Ads API 會使用 OAuth 2.0 驗證及授權要求。

電腦版應用程式流程的步驟

在 Google Cloud 雲端專案中，依序前往「APIs & Services」(API 和服務) >「OAuth consent screen」(OAuth 同意畫面)，然後設定同意畫面。應用程式處於「測試」狀態時，請將電子郵件地址新增至「測試使用者」部分，以免授權期間發生存取錯誤。
依序前往「APIs & Services」(API 和服務) >「Credentials」(憑證)。
按一下「建立憑證」>「OAuth 用戶端 ID」。
將應用程式類型設為「電腦應用程式」。
按一下「建立」，然後下載 OAuth 憑證檔案client_secret.json (或複製 Client ID 和 Client Secret)。

產生更新權杖

取得用戶端 ID 和用戶端密鑰後，您必須產生重新整理權杖。您可以使用 Google OAuth 2.0 Playground 或用戶端程式庫指令碼執行這項操作。

方法 A：使用 Google OAuth 2.0 Playground

前往 Google OAuth 2.0 Playground。
按一下右上角的齒輪圖示 (OAuth 2.0 設定)。
勾選「使用自己的 OAuth 憑證」方塊。
輸入 OAuth2 Client ID 和 Client Secret，然後按一下「關閉」。
在左側的「步驟 1 (選取及授權 API)」中，於「輸入您自己的範圍」欄位中輸入 Google Ads API 範圍： https://www.googleapis.com/auth/adwords
按一下「Authorize APIs」。當系統提示時，請使用有權存取 Google Ads 管理員帳戶 (或測試帳戶) 的 Google 帳戶登入。
在同意畫面中，按一下「繼續」。
在「Step 2 (Exchange authorization code for tokens)」中，按一下藍色的「Exchange authorization code for tokens」按鈕。
回應面板會顯示 Refresh token 和 Access token。複製並儲存 Refresh token。

方法 B：使用用戶端程式庫指令碼 (Python 範例)

官方 Python 用戶端程式庫提供內建輔助指令碼，可產生憑證。或者，您也可以從 Google Cloud 控制台下載 client_secret.json，然後執行下列獨立 Python 指令碼：

安裝必要的 OAuth 程式庫：

pip install google-auth-oauthlib

在 client_secret.json 所在的目錄中建立名為 generate_refresh_token.py 的指令碼，然後運作執行該指令碼：

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. 設定用戶端程式庫和憑證

Google 提供正式支援的用戶端程式庫，可處理驗證、序列化，以及與 gRPC 端點的通訊。

支援的語言

Python： pip install google-ads
Java：可透過 Maven 或 Gradle 取得
PHP： composer require googleads/google-ads-php
.NET： Install-Package Google.Ads.GoogleAds
Ruby： gem install google-ads-googleads
Perl： cpanm Google::Ads::GoogleAds::Client

設定檔 (`google-ads.yaml`)

建立包含憑證的設定檔。根據預設，用戶端程式庫的初始化方法 (例如 GoogleAdsClient.load_from_storage()) 會自動在下列兩個位置搜尋 google-ads.yaml：

指令碼執行的目前工作目錄。
使用者主目錄 (Linux/macOS 上的 ~ 或 Windows 上的 %HOMEPATH%)。

如果將檔案儲存在自訂位置，可以明確將路徑傳遞至初始化方法 (例如 load_from_storage("path/to/google-ads.yaml"))。

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. 進行第一次 API 呼叫

如要驗證新手上路設定，請執行快速入門指令碼，從測試帳戶擷取現有廣告活動。

Python 指令碼範例 (`quickstart.py`)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. 最佳做法與資源

記錄：在用戶端程式庫中啟用詳細記錄功能，擷取要求和回應 ID (request-id)，向 Google 尋求支援時，這些 ID 非常重要。
錯誤處理：針對 GoogleAdsException 導入完善的錯誤處理機制，特別是管理速率限制 (RESOURCE_TEMPORARILY_EXHAUSTED)。
官方說明文件： Google Ads API 開發人員說明文件
用戶端程式庫和程式碼範例： GitHub Google Ads 存放區

簡介

快速入門導覽課程

Google Ads API 新手上路指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。