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

Đ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:

    • Python 3.10 trở lên. Python là ngôn ngữ mặc định, vì vậy bạn phải cài đặt ngôn ngữ này và đưa vào đường dẫn của mình.
    • Công cụ dòng lệnh Google Antigravity đã cài đặt.
    • jq (trình xử lý JSON dòng lệnh). Tập lệnh cài đặt sẽ cố gắng cài đặt công cụ này nếu bạn chưa cài đặt.

  3. Kho lưu trữ:

Bắt đầu

  1. Chuyển đến thư mục dự án:

    cd <full path>/google-ads-api-developer-assistant

    (Lưu ý: Nếu bạn đã bật tính năng tích hợp shell Antigravity, thì việc nhập thư mục này sẽ tự động khởi chạy phiên trợ lý).

  2. Chạy tập lệnh cài đặt: Tập lệnh này sẽ khởi chạy môi trường phát triển và sao chép các thư viện ứng dụng Google Ads bắt buộc (Python được cài đặt theo mặc định).

    ./install.sh

    Nếu bạn đang dùng Windows, hãy chạy tập lệnh PowerShell install.ps1.

  3. Định cấu hình thông tin đăng nhập: Đảm bảo rằng tệp google-ads.yaml (hoặc tệp tương đương bằng ngôn ngữ khác) được đặt trong thư mục chính của bạn.

  4. Tương tác với Trợ lý: Sau khi phiên hoạt động, bạn có thể tương tác với Trợ lý bằng ngôn ngữ tự nhiên ngay trong thiết bị đầu cuối.

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

  • Hỏi và đáp bằng ngôn ngữ tự nhiên: Đặt câu hỏi về các tính năng, phương pháp hay nhất hoặc tài nguyên cụ thể của Google Ads API.

    • "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ạo mã: Tạo truy vấn GAQL và đoạn mã Python có thể thực thi.

    • "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 mã chiến dịch 12345."
    • "Tìm những quảng cáo bị từ chối trên tất cả chiến dịch." Mã được tạo sẽ tự động được kiểm tra bằng ruff và lưu trong thư mục saved/code/.

  • Thực thi API trực tiếp: Chạy tập lệnh Python chỉ đọc được tạo trực tiếp trong một môi trường ảo riêng biệt (.venv) và xem kết quả được định dạng dưới dạng bảng trong thiết bị đầu cuối.

    • Chỉ cần nói với Trợ lý: "Chạy mã" hoặc "Thực thi tập lệnh".
    • Để đảm bảo an toàn, các thao tác thay đổi (tạo, cập nhật, xoá) sẽ được tạo nhưng không bao giờ thực thi.

  • Xuất sang CSV: Lưu kết quả dạng bảng từ các lệnh gọi API vào tệp CSV.

    • "Lưu kết quả vào tệp CSV." Tệp được lưu trong thư mục saved/csv/.

  • Chẩn đoán và khắc phục sự cố nâng cao: Nhận trợ giúp về thông báo lỗi, hành vi không mong muốn của API hoặc các vấn đề về lượt chuyển đổi ngoại tuyến.

    • "Tại sao tôi không thấy kết quả nào cho truy vấn của mình?"
    • "Khắc phục sự cố về lượt chuyển đổi cho khách hàng 123-456-7890." (Tạo báo cáo chẩn đoán chi tiết trong saved/data/).

  • Bối cảnh bổ sung: Thêm cơ sở mã hoặc thư viện tuỳ chỉnh của riêng bạn để làm bối cảnh.

    • Sử dụng tập lệnh update.sh với tuỳ chọn --context_path để đăng ký tệp dự án: none ./update.sh --context_path /path/to/your/codebase
    • Điều này cho phép Trợ lý đưa logic ứng dụng của bạn vào quá trình suy luận khi tạo câu trả lời hoặc tạo mã bằng ngôn ngữ bạn ưu tiên.

Trường hợp sử dụng minh hoạ

  • Báo cáo:
    • "Lấy cho tôi 5 từ khoá hàng đầu theo chi phí của tháng trước cho khách hàng 12345678."
  • Cấu trúc tài khoản:
    • "Liệt kê tất cả tên chiến dịch và mã chiến dịch."
  • Khắc phục sự cố:
    • "Tôi đã tải 100 lượt chuyển đổi lên, nhưng chỉ có 78 lượt xuất hiện trong giao diện người dùng. Làm cách nào để gỡ lỗi này bằng API?"
  • Học:
    • "/explain what a shared set is"
  • Tạo mã:
    • "Viết mã để tạo chiến dịch Tối đa hoá hiệu suất cho company name."

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

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

Chúng tôi rất hoan nghênh các đóng góp! Hãy xem tệp CONTRIBUTING.md trong kho lưu trữ GitHub để biết nguyên tắc.