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 kiến thức chuyên sâu về miền Google Ads API trực tiếp vào 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 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ý được xây dựng cho các khung tác nhân Google Antigravity và Claude Code (v4.0.0) dưới dạng một trình bổ trợ theo mô-đun. Ứng dụng này sử dụng các hợp đồng AGENTS.md và CLAUDE.md, các lệnh 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

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ộ rồi 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 nhắm 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 bổ sung (--php, --ruby, --java, --dotnet hoặc --all).

Antigravity

Linux / macOS: ```bash ./install.sh agy

Hoặc thêm các thư viện ứng dụng khác:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Hoặc thêm các thư viện ứng dụng khác:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS: ```bash ./install.sh claude

Hoặc thêm các thư viện ứng dụng khác:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Hoặc thêm các thư viện ứng dụng khác:

.\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 số 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 của mình 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ách sử dụ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 Terminal.

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

  • Hỏi và đáp bằng ngôn ngữ tự nhiên và hướng dẫn theo khái niệm: Đặt câu hỏi về các tính năng, quy tắc kiến trúc 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 API chính thức thay vì chỉ dựa vào quá trình huấn luyện LLM chung.

    • "Những loại chiến dịch nào có sẵn?"
    • "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 được chia sẻ là gì và cách sử dụng tập hợp này?"
    • Lệnh dấu gạch chéo Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Tạo mã thư viện ứng dụng có cơ sở: Tạo mã đã kiểm thử, thành ngữ bằng cách sử dụ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 chương 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, các 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 đối tượng và giản đồ Protobuf: Kiểm tra linh hoạt các 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 đến chi phí 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 đơn giản. 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 tiếp các bảng được định dạng vào thiết bị đầu cuối.

    • "Cho tôi 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 trực tiếp trong một môi trường ảo được quản lý.

    • Chỉ cần nói với Trợ lý: "Chạy mã" hoặc "Thực thi tập lệnh".
    • Thay đổi tính an toàn: Để đả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 trợ lý không bao giờ thực hiện 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 MCC: 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 trong tài khoản 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 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 của bạn vào quá trình suy luận của Trợ lý.

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): powershell .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Thông tin 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 sau đây. Trong Google Antigravity, hãy gọi các 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à các 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 Phân giải hệ thống phân cấp MCC và CID của khách hàng. /get-cids 1234567890
/troubleshoot-conversions Chạy quy trình chẩn đoán lượt chuyển đổi ngoại tuyến được tải 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 Đưa ra 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 công việc gồm nhiều giai đoạn. /step-by-step upload conversions
/assistant-tutorial Chạy hướng dẫn 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ữ, quá trình cài đặt trình bổ trợ và thư viện ứng dụng:

Antigravity

Linux / macOS: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): 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: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): 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: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Hoặc từ thiết bị đầu cuối: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Không bắt buộc) Xoá sổ đăng ký trang web thương mại tại địa phương: bash 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 những đóng góp của bạn! Hãy xem tệp CONTRIBUTING.md trong kho lưu trữ GitHub để biết các nguyên tắc.

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