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à có trong đường dẫn của mình.
    • Công cụ dòng lệnh Google Antigravity đã được 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 ứng dụng này nếu thiếu.

  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 Antigravity shell, 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 động môi trường phát triển và sao chép các thư viện ứng dụng Google Ads cần thiết (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 install.ps1 PowerShell.

  3. Định cấu hình thông tin đăng nhập: Đảm bảo rằng google-ads.yaml (hoặc ngôn ngữ tương đương) đượ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 các 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 quảng cáo bị từ chối trong 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 trực tiếp các tập lệnh Python chỉ có thể đọc đã tạo trong một môi trường ảo biệt lập (.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 đột biến (tạo, cập nhật, xoá) được tạo nhưng không bao giờ được thực thi.

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

    • "Lưu kết quả vào một tệp CSV." Các 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 cụm từ tìm kiếm 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 toàn bộ mã nguồn hoặc thư viện tuỳ chỉnh của riêng bạn để cung cấp bối cảnh.

    • Sử dụng tập lệnh update.sh với lựa chọn --context_path để đăng ký các tệp dự án: none ./update.sh --context_path /path/to/your/codebase
    • Nhờ đó, Trợ lý có thể đư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ữ mà bạn ưa dùng.

Ví dụ về các trường hợp sử dụng

  • 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 tập:
    • "/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 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ì?