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ài đặt gemini-cli.
    • 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

  2. Chạy tập lệnh thiết lập: Tập lệnh này định cấu hình gemini-cli để sử dụng các tệp ngữ cảnh GEMINI.md và các công cụ cần thiết của trợ lý.

    ./install.sh

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

  3. Khởi động gemini-cli:

    gemini

  4. Tương tác với Trợ lý: Giờ đây, bạn có thể đặt câu hỏi hoặc đưa ra lệnh bằng ngôn ngữ tự nhiên.

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ẽ được lưu trong thư mục saved_code/.

  • Thực thi API trực tiếp: Chạy các tập lệnh Python chỉ có thể đọc đã tạo trực tiếp từ gemini-cli và xem kết quả được định dạng trong thiết bị đầu cuối. Sau khi Trợ lý tạo mã, bạn sẽ nhận được lời nhắc trên màn hình:

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual
Google Ads customer ID and execute the following command in
your shell: <command>

Nhập run và tập lệnh sẽ thực thi trong ngữ cảnh Trợ lý nếu ngôn ngữ mặc định của bạn là Python, Ruby hoặc PHP. Các ngôn ngữ đã biên dịch sẽ không chạy do chính sách bảo mật.

  • 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/.

  • Hỗ trợ khắc phục sự cố: Nhận trợ giúp về các thông báo lỗi hoặc hành vi API không mong muốn.

    • "Tôi gặp lỗi "AuthenticationError.OAUTH_TOKEN_INVALID", tôi nên làm gì?"
    • "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?"

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.