安裝及使用 Google Ads API 開發人員助理

Google Ads API 開發人員助理會將 Google Ads API 領域的專業知識，直接帶入您的 AI 程式碼編寫環境。使用自然語言提示和內建斜線指令，建構查詢、生成用戶端程式庫程式碼、執行唯讀 API 呼叫、串流臨時報表，以及排解整合問題。

這款助理是專為 Google Antigravity 和 Claude Code 代理架構 (v4.0.0) 建構的模組化外掛程式。這項服務會使用AGENTS.md和CLAUDE.md合約、內建斜線指令和專業領域技能，維持持續性情境、健全的安全邊界和自動驗證管道。

必要條件

開始之前，請確認您具備以下項目：

  1. Google Ads API 存取權：

  2. 軟體：

開始使用

請按照下列步驟複製存放區、執行平台專屬的安裝指令碼、設定憑證，以及啟用外掛程式。

1. 複製存放區

將存放區複製到本機電腦，然後前往專案目錄：

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. 執行安裝指令碼

執行目標平台的安裝指令碼。根據預設，系統會納入 Python 用戶端程式庫。您可以視需要加入其他用戶端程式庫 (--php、--ruby、--java、--dotnet 或 --all)。

Antigravity

Linux / macOS：

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell)：

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS：

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell)：

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. 設定憑證

請務必將 API 設定檔 (例如 google-ads.yaml、google_ads_php.ini 或 google_ads_config.rb) 放在 $HOME 目錄中。

(選用) 如要設定預設客戶 ID，請直接在 config/customer_id.txt 中輸入客戶 ID 號碼 (例如 1234567890)。您也可以在 config/api_version.txt 中檢查或固定目前的 API 版本。

4. 啟用外掛程式

  • Antigravity：重新啟動 Antigravity / agy 主機工作階段，載入外掛程式。
  • Claude Code：在有效的 Claude Code 工作階段中，執行 /reload-plugins 或重新啟動 claude。

5. 與 Google 助理互動

您可以在終端機中，使用自然語言提示或專屬斜線指令與助理互動。

主要功能與特色

  • 自然語言問答和概念指引：詢問 Google Ads API 功能、架構規則、最佳做法或特定資源。Google 助理會根據官方 API 定義生成回覆，而不是只依賴一般 LLM 訓練。

    • 「有哪些廣告活動類型？」
    • 「如何在 GAQL 中依日期篩選？」
    • 「說明 click_view 和 impression_view 的差異。」
    • 「什麼是共用組合？如何使用？」
    • Claude Code 斜線指令： /explain、/step-by-step、/assistant-tutorial

  • 生成有根據的用戶端程式庫程式碼：使用官方 Google Ads 用戶端程式庫 (Python、Java、PHP、.NET 和 Ruby) 生成經過測試的慣用程式碼。

    • 「顯示過去 30 天內轉換次數最多的廣告活動。」
    • 「取得客戶 123-456-7890 所有已啟用的廣告群組名稱。」
    • 「編寫程式碼來建立最高成效廣告活動。」 產生的程式碼會儲存在 saved/code/ 目錄中。

  • 程式輔助 GAQL 查詢驗證：自動對 API 中繼資料、欄位相容性、零曝光規則和日期區隔執行模擬並驗證複雜查詢，然後再執行查詢。

    • Claude Code： /validate-gaql
    • 自然語言： validate: SELECT campaign.id FROM campaign

  • 物件和 Protobuf 結構定義檢查：動態檢查任何有效 API 版本的資源結構、巢狀欄位、資料類型和列舉值，不必負擔遠端中繼資料的額外費用。

    • Claude Code： /inspect-object <resource_or_enum>
    • 自然語言： 「檢查廣告活動資源」

  • 即時報表和 CSV 匯出：用簡單的英文詢問成效資料，Google 助理會直接針對您的帳戶建構、驗證及執行 GAQL 查詢，並將格式化表格即時串流至終端機。

    • 「顯示客戶 123-456-7890 上個月費用最高的前 5 個關鍵字。」
    • 「將結果儲存為 CSV 檔案。」(匯出至 saved/csv/)。

  • 直接執行 API 和變動安全性：直接在受管理虛擬環境中執行產生的唯讀指令碼。

    • 對 Google 助理說出「執行程式碼」或「執行指令碼」。
    • 變動安全性：為確保安全，系統會產生變動作業 (建立、更新、刪除) 至 saved/code/，但絕不會由助理直接執行。在助理之外手動查看及執行這些動作。

  • 進階診斷和轉換疑難排解：調查離線轉換上傳失敗的原因、預先驗證上傳檔案，以及產生詳細的診斷報表。

    • Claude Code： /troubleshoot-conversions
    • 自然語言： 「排解客戶 123-456-7890 的轉換問題。」 (報表會儲存到 saved/data/)。

  • 管理員帳戶階層對應：擷取子帳戶客戶 ID，並對應管理員帳戶下的帳戶階層。

    • Claude Code： /get-cids <manager_cid>
    • 自然語言： 「Get all client customer IDs under manager 123-456-7890」

  • 最高成效廣告活動商家資訊篩選器和排除條件：為素材資源群組產生產品分割樹狀結構和網頁網址排除條件。

    • Claude Code： /pmax-filter
    • 自然語言： 「為最高成效廣告活動建立網頁排除篩選器」

  • 其他程式碼集背景資訊：將應用程式邏輯和自訂架構註冊到助理的推論中。

    • Linux / macOS：

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell)：

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Claude Code 斜線指令參考資料

使用 Claude Code 時，可使用下列內建斜線指令。 在 Google Antigravity 中，您可以使用自然語言提示或技能工具名稱 (例如 validate_gaql 和 inspect_object)，叫用這些相同功能，詳情請參閱「主要功能」一節：

斜線指令 目的 範例
/validate-gaql 驗證 GAQL 語法、相容性和規則。 /validate-gaql
/inspect-object 檢查 Protobuf 欄位、類型和列舉。 /inspect-object Campaign
/get-cids 解析管理員帳戶階層和客戶客戶 ID。 /get-cids 1234567890
/troubleshoot-conversions 執行離線轉換上傳診斷。 /troubleshoot-conversions
/pmax-filter 產生最高成效廣告活動產品資訊篩選器和排除條件。 /pmax-filter
/explain 提供 4 個部分的結構化說明。 /explain shared set
/step-by-step 制定多階段工作執行計畫。 /step-by-step upload conversions
/assistant-tutorial 執行 11 個步驟的互動式逐步操作說明。 /assistant-tutorial

維護與更新

如要更新存放區、外掛程式安裝和用戶端程式庫，請按照下列步驟操作：

Antigravity

Linux / macOS：

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell)：

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS：

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell)：

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

解除安裝

如要解除安裝助理外掛程式，請按照下列步驟操作：

Antigravity

Linux / macOS：

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell)：

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

然後重新啟動 Antigravity 主機工作階段。

Claude Code

在有效的 Claude Code 工作階段中：

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

或從終端機執行：

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(選用) 移除當地市集登錄檔：

claude plugin marketplace remove google-ads-assistant-local

社群與支援

投稿指南

歡迎貢獻！如需相關指南，請參閱 GitHub 存放區中的 CONTRIBUTING.md 檔案。

上一頁
什麼是 Google Ads API 開發人員助理？