Cài đặt và sử dụng Trợ lý nhà phát triển Google Ads API

Trợ lý nhà phát triển Google Ads API mang đến kiến thức chuyên môn sâu về Google Ads API ngay trong môi trường lập trình AI của bạn. Sử dụng câu lệnh bằng ngôn ngữ tự nhiên và các lệnh dấu gạch chéo tích hợp để tạo truy vấn, tạo mã thư viện ứng dụng, thực thi các lệnh gọi API chỉ đọc, truyền trực tuyến báo cáo đặc biệt và khắc phục sự cố tích hợp.

Trợ lý này được xây dựng cho các khung tác nhân Google Antigravity và Claude Code (phiên bản 4.0.0) dưới dạng một trình bổ trợ mô-đun. Ứng dụng này sử dụng các hợp đồng AGENTS.md và CLAUDE.md, các lệnh dấu gạch chéo tích hợp sẵn và các kỹ năng chuyên biệt theo miền để duy trì ngữ cảnh liên tục, ranh giới an toàn mạnh mẽ và các quy trình xác thực tự động.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo rằng bạn có:

  1. Quyền truy cập vào Google Ads API:

  2. Phần mềm:

Bắt đầu

Hãy làm theo các bước sau để sao chép kho lưu trữ, chạy tập lệnh cài đặt dành riêng cho nền tảng, định cấu hình thông tin đăng nhập và kích hoạt trình bổ trợ.

1. Sao chép kho lưu trữ

Sao chép kho lưu trữ vào máy cục bộ và chuyển đến thư mục dự án:

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

2. Chạy tập lệnh cài đặt

Chạy tập lệnh cài đặt cho nền tảng mục tiêu. Theo mặc định, thư viện ứng dụng Python sẽ được đưa vào. Bạn có thể tuỳ ý thêm các thư viện ứng dụng khác (--php, --ruby, --java, --dotnet hoặc --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. Định cấu hình thông tin đăng nhập

Đảm bảo rằng tệp cấu hình API (ví dụ: google-ads.yaml, google_ads_php.ini hoặc google_ads_config.rb) được đặt trong thư mục $HOME.

(Không bắt buộc) Để định cấu hình mã khách hàng mặc định, hãy nhập trực tiếp mã khách hàng của bạn vào config/customer_id.txt (ví dụ: 1234567890). Bạn cũng có thể kiểm tra hoặc ghim phiên bản API đang hoạt động trong config/api_version.txt.

4. Kích hoạt trình bổ trợ

  • Antigravity: Khởi động lại phiên lưu trữ Antigravity / agy để tải trình bổ trợ.
  • Claude Code: Trong một phiên Claude Code đang hoạt động, hãy chạy /reload-plugins hoặc khởi động lại claude.

5. Tương tác với Trợ lý

Bạn có thể tương tác với Trợ lý bằng câu lệnh ngôn ngữ tự nhiên hoặc các lệnh dấu gạch chéo chuyên dụng ngay trong dòng lệnh.

Các tính năng chính

  • Hỏi đáp bằng ngôn ngữ tự nhiên và hướng dẫn về khái niệm: Đặt câu hỏi về các tính năng, quy tắc kiến trúc, phương pháp hay nhất hoặc tài nguyên cụ thể của Google Ads API. Trợ lý đưa ra câu trả lời dựa trên các định nghĩa chính thức về API thay vì chỉ dựa vào quá trình huấn luyện LLM chung.

    • "Có những loại chiến dịch nào?"
    • "Làm cách nào để lọc theo ngày trong GAQL?"
    • "Giải thích sự khác biệt giữa click_view và impression_view."
    • "Tập hợp dùng chung là gì và cách sử dụng như thế nào?"
    • Lệnh dấu gạch chéo của Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Tạo mã thư viện ứng dụng có căn cứ: Tạo mã đã được kiểm thử, theo cách thức thông thường bằng thư viện ứng dụng chính thức của Google Ads (Python, Java, PHP, .NET và Ruby).

    • "Cho tôi xem những chiến dịch có nhiều lượt chuyển đổi nhất trong 30 ngày qua."
    • "Lấy tất cả tên nhóm quảng cáo đã bật cho khách hàng 123-456-7890."
    • "Viết mã để tạo chiến dịch Tối đa hoá hiệu suất". Mã được tạo sẽ được lưu trong thư mục saved/code/.

  • Xác thực truy vấn GAQL theo phương thức lập trình: Tự động chạy thử và xác thực các truy vấn phức tạp dựa trên siêu dữ liệu API, khả năng tương thích của trường, quy tắc không có lượt hiển thị và phân đoạn ngày trước khi thực thi.

    • Claude Code: /validate-gaql
    • Ngôn ngữ tự nhiên: validate: SELECT campaign.id FROM campaign

  • Kiểm tra giản đồ đối tượng và Protobuf: Kiểm tra linh động cấu trúc tài nguyên, trường lồng nhau, kiểu dữ liệu và giá trị enum cho mọi phiên bản API đang hoạt động mà không cần tốn tài nguyên cho siêu dữ liệu từ xa.

    • Claude Code: /inspect-object <resource_or_enum>
    • Ngôn ngữ tự nhiên: "Kiểm tra tài nguyên chiến dịch"

  • Báo cáo trực tiếp đặc biệt và xuất tệp CSV: Yêu cầu dữ liệu hiệu suất bằng tiếng Anh thông thường. Trợ lý sẽ tạo, xác thực và chạy các truy vấn GAQL trực tiếp trên tài khoản của bạn, truyền trực tuyến các bảng được định dạng trực tiếp vào thiết bị đầu cuối.

    • "Cho xem 5 từ khoá hàng đầu theo chi phí của tháng trước cho khách hàng 123-456-7890."
    • "Lưu kết quả dưới dạng tệp CSV". (Xuất sang saved/csv/).

  • Thực thi API trực tiếp và đảm bảo an toàn khi thay đổi: Thực thi các tập lệnh chỉ đọc được tạo ngay trong môi trường ảo được quản lý.

    • Nói với Trợ lý: "Chạy mã" hoặc "Thực thi tập lệnh".
    • Độ an toàn khi thay đổi: Để đảm bảo an toàn, các thao tác thay đổi (tạo, cập nhật, xoá) được tạo cho saved/code/ nhưng không bao giờ được trợ lý thực thi trực tiếp. Xem xét và thực hiện các thao tác đó theo cách thủ công bên ngoài trợ lý.

  • Chẩn đoán nâng cao và khắc phục sự cố về lượt chuyển đổi: Điều tra các lỗi tải lượt chuyển đổi ngoại tuyến lên, xác thực trước các tệp tải lên và tạo báo cáo chẩn đoán chi tiết.

    • Claude Code: /troubleshoot-conversions
    • Ngôn ngữ tự nhiên: "Khắc phục sự cố về lượt chuyển đổi cho khách hàng 123-456-7890." (Báo cáo được lưu vào saved/data/).

  • Ánh xạ hệ thống phân cấp tài khoản người quản lý: Truy xuất mã khách hàng của tài khoản phụ và ánh xạ hệ thống phân cấp tài khoản trong tài khoản người quản lý.

    • Claude Code: /get-cids <manager_cid>
    • Ngôn ngữ tự nhiên: "Lấy tất cả mã khách hàng của khách hàng thuộc người quản lý 123-456-7890"

  • Bộ lọc và tiêu chí loại trừ trang thông tin của chiến dịch Tối đa hoá hiệu suất: Tạo cây phân vùng sản phẩm và tiêu chí loại trừ URL trang web cho các nhóm thành phần.

    • Claude Code: /pmax-filter
    • Ngôn ngữ tự nhiên: "Tạo bộ lọc loại trừ trang web cho chiến dịch Tối đa hoá hiệu suất của tôi"

  • Bối cảnh bổ sung về toàn bộ mã nguồn: Đăng ký logic ứng dụng và cấu trúc tuỳ chỉnh vào quy trình suy luận của Trợ lý.

    • 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

Tài liệu tham khảo về lệnh dấu gạch chéo của Claude Code

Khi sử dụng Claude Code, bạn có thể dùng các lệnh dấu gạch chéo tích hợp sẵn sau đây. Trong Google Antigravity, hãy gọi những chức năng tương tự bằng cách sử dụng câu lệnh bằng ngôn ngữ tự nhiên hoặc tên công cụ kỹ năng như validate_gaql và inspect_object, như mô tả trong phần Các tính năng chính:

Lệnh dấu gạch chéo Mục đích Ví dụ
/validate-gaql Xác thực cú pháp, khả năng tương thích và quy tắc của GAQL. /validate-gaql
/inspect-object Kiểm tra các trường, loại và enum Protobuf. /inspect-object Campaign
/get-cids Giải quyết hệ thống phân cấp tài khoản người quản lý và mã khách hàng (CID) của khách hàng. /get-cids 1234567890
/troubleshoot-conversions Chạy quy trình chẩn đoán lượt tải lượt chuyển đổi ngoại tuyến lên. /troubleshoot-conversions
/pmax-filter Tạo bộ lọc trang thông tin và tiêu chí loại trừ cho chiến dịch Tối đa hoá hiệu suất. /pmax-filter
/explain Cung cấp lời giải thích có cấu trúc gồm 4 phần. /explain shared set
/step-by-step Xây dựng kế hoạch thực hiện nhiệm vụ gồm nhiều giai đoạn. /step-by-step upload conversions
/assistant-tutorial Chạy hướng dẫn từng bước tương tác gồm 11 bước. /assistant-tutorial

Bảo trì và cập nhật

Cách cập nhật kho lưu trữ, cài đặt trình bổ trợ và thư viện ứng dụng:

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

Gỡ cài đặt

Cách gỡ cài đặt trình bổ trợ trợ lý:

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"

Sau đó, hãy khởi động lại phiên lưu trữ Antigravity.

Claude Code

Trong một phiên Claude Code đang hoạt động:

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

Hoặc từ thiết bị đầu cuối:

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

(Không bắt buộc) Xoá sổ đăng ký thị trường địa phương:

claude plugin marketplace remove google-ads-assistant-local

Cộng đồng và hỗ trợ

Nguyên tắc đóng góp

Chúng tôi rất mong nhận được ý kiến đóng góp của bạn! Hãy xem tệp CONTRIBUTING.md trong kho lưu trữ GitHub để biết nguyên tắc.

Trước
Trợ lý nhà phát triển Google Ads API là gì?