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

Google Ads API 開發人員助理會直接在 AI 程式碼編寫環境中，提供深入的 Google Ads API 領域專業知識。使用自然語言提示和內建斜線指令建構查詢、產生用戶端程式庫程式碼、執行唯讀 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 天內獲得最多轉換的廣告活動。」
    • 「Get all enabled ad group names for customer 123-456-7890.」(取得客戶 123-456-7890 的所有已啟用廣告群組名稱)。
    • 「Write code to create a Performance Max campaign.」(編寫程式碼來建立最高成效廣告活動。) 產生的程式碼會儲存在 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/)。

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

    • Claude Code： /get-cids <manager_cid>
    • 自然語言： 「Get all client customer IDs under manager 123-456-7890」(取得管理員 123-456-7890 底下的所有用戶端客戶 ID)

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

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

  • 其他程式碼集內容：將應用程式邏輯和自訂架構註冊到 Google 助理的推論程序中。

    • 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 解決 MCC 階層和客戶 CID。 /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 開發人員助理？