دستیار توسعه‌دهنده API گوگل ادز را نصب و استفاده کنید

پیش‌نیازها

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

  1. دسترسی به API تبلیغات گوگل:

  2. نرم‌افزار:

    • پایتون ۳.۱۰ یا جدیدتر. پایتون زبان پیش‌فرض است، بنابراین باید آن را نصب کرده و در مسیر خود داشته باشید.
    • جمینی-کلی نصب شد.
    • jq (پردازنده JSON خط فرمان). در صورت عدم وجود، اسکریپت نصب سعی در نصب آن خواهد کرد.

  3. مخزن:

شروع کنید

  1. به دایرکتوری پروژه بروید:

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

  2. اسکریپت راه‌اندازی را اجرا کنید: این اسکریپت، gemini-cli را برای استفاده از فایل‌های زمینه GEMINI.md دستیار و ابزارهای لازم پیکربندی می‌کند.

    ./install.sh

    اگر از ویندوز استفاده می‌کنید، اسکریپت پاورشل setup.ps1 را اجرا کنید.

  3. اجرای gemini-cli:

    gemini

  4. تعامل با دستیار: اکنون می‌توانید با زبان طبیعی سؤال بپرسید یا دستور دهید.

ویژگی‌های کلیدی

  • پرسش و پاسخ به زبان طبیعی: در مورد ویژگی‌های API گوگل ادز، بهترین شیوه‌ها یا منابع خاص سوال بپرسید.

    • «انواع کمپین‌های موجود کدامند؟»
    • "چگونه می‌توانم در GAQL بر اساس تاریخ فیلتر کنم؟"
    • «تفاوت بین click_view و impression_view را توضیح دهید.»

  • تولید کد: کوئری‌های GAQL و قطعه کدهای پایتون قابل اجرا تولید کنید.

    • «کمپین‌هایی را که بیشترین تبدیل را در ۳۰ روز گذشته داشته‌اند، به من نشان بده.»
    • «نام همه گروه‌های تبلیغاتی فعال‌شده برای شناسه کمپین ۱۲۳۴۵ را دریافت کنید.»
    • «تبلیغات رد شده را در تمام کمپین‌ها پیدا کنید.» کد تولید شده در دایرکتوری saved_code/ ذخیره می‌شود.

  • اجرای مستقیم API: اسکریپت‌های پایتون فقط خواندنی تولید شده را مستقیماً از gemini-cli اجرا کنید و نتایج قالب‌بندی شده را در ترمینال خود مشاهده کنید. پس از اینکه دستیار کد را تولید کرد، یک اعلان روی صفحه دریافت خواهید کرد: 

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>

run وارد کنید، و اگر زبان پیش‌فرض شما پایتون، روبی یا PHP باشد، اسکریپت در محیط دستیار اجرا خواهد شد. زبان‌های کامپایل‌شده به دلیل سیاست‌های امنیتی اجرا نخواهند شد.

  • خروجی CSV: نتایج جدولی حاصل از فراخوانی‌های API را در یک فایل CSV ذخیره کنید.

    • «نتایج را در یک فایل CSV ذخیره کنید.» فایل‌ها در دایرکتوری saved_csv/ ذخیره می‌شوند.

  • کمک در عیب‌یابی: در مورد پیام‌های خطا یا رفتار غیرمنتظره API کمک بگیرید.

    • «من با خطای 'AuthenticationError.OAUTH_TOKEN_INVALID' مواجه شدم، چه کاری باید انجام دهم؟»
    • «چرا هیچ نتیجه‌ای برای درخواستم نمی‌بینم؟»

موارد استفاده مثال

  • گزارش‌دهی:
    • «۵ کلمه کلیدی برتر بر اساس هزینه برای ماه گذشته برای مشتری ۱۲۳۴۵۶۷۸ را به من بدهید.»
  • ساختار حساب:
    • «نام تمام کمپین‌ها و شناسه‌های آنها را فهرست کنید.»
  • عیب‌یابی:
    • «من ۱۰۰ تبدیل آپلود کردم، اما فقط ۷۸ تای آنها در رابط کاربری نمایش داده می‌شوند. چطور می‌توانم با استفاده از API این مشکل را برطرف کنم؟»
  • یادگیری:
    • «/توضیح دهید که یک مجموعه مشترک چیست»
  • تولید کد:
    • «کدی بنویسید که یک کمپین Performance Max برای company name ایجاد کند.»

جامعه و پشتیبانی

دستورالعمل‌های مشارکت

از مشارکت‌ها استقبال می‌شود! برای راهنمایی بیشتر به فایل CONTRIBUTING.md در مخزن گیت‌هاب مراجعه کنید.