התקנה ושימוש ב-Google Ads API Developer Assistant

דרישות מוקדמות

לפני שמתחילים, חשוב לוודא שהתנאים הבאים מתקיימים:

1. גישה אל Google Ads API:

   • קוד מפתח למפתחים ב-Google Ads API.
   • קובץ תצורה של Google Ads שמוגדר עם קוד המפתח, פרטי הכניסה של OAuth 2.0 ומספר הלקוח, שנמצא בתיקיית הבית. אפשר לעיין במדריך להגדרת ספריית הלקוח.
   • היכרות עם המושגים והאימות של Google Ads API.

2. תוכנה:

   • ‫Python בגרסה 3.10 ואילך. ‫Python היא שפת ברירת המחדל, ולכן היא צריכה להיות מותקנת ומוגדרת בנתיב.
   • כלי שורת הפקודה של Google Antigravity מותקן.
   • ‫jq (מעבד JSON בשורת הפקודה). אם הוא לא מותקן, סקריפט ההתקנה ינסה להתקין אותו.

3. מאגר:

   • עותק מקומי של המאגר google-ads-api-developer-assistant מ-GitHub.

שנתחיל?

1. עוברים לספריית הפרויקט:

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

   (הערה: אם הפעלתם שילוב של Antigravity shell, הכניסה לספרייה הזו תפעיל באופן אוטומטי את סשן העזרה).

2. מריצים את סקריפט ההתקנה: הסקריפט הזה מאתחל את סביבת הפיתוח ומשכפל את ספריות הלקוח הנדרשות של Google Ads (Python מותקן כברירת מחדל).

   ./install.sh
   

   אם אתם משתמשים ב-Windows, מריצים את install.ps1 סקריפט PowerShell.

3. הגדרת פרטי הכניסה: מוודאים שקובץ google-ads.yaml (או קובץ ששמו זהה בשפה אחרת) ממוקם בספריית הבית.

4. אינטראקציה עם Assistant: אחרי שהסשן פעיל, אפשר ליצור אינטראקציה עם Assistant באמצעות שפה טבעית ישירות במסוף.

תכונות עיקריות

• שאלות ותשובות בשפה טבעית: אפשר לשאול שאלות על תכונות של Google Ads API, על שיטות מומלצות או על משאבים ספציפיים.

  • "מהם סוגי הקמפיינים הזמינים?"
  • "איך מסננים לפי תאריך ב-GAQL?"
  • "תסביר את ההבדל בין click_view לבין impression_view".

• יצירת קוד: יצירת שאילתות GAQL וקטעי קוד Python שאפשר להריץ.

  • "תציג לי את הקמפיינים עם הכי הרבה המרות ב-30 הימים האחרונים".
  • "קבל את כל השמות של קבוצות המודעות שמופעלות עבור מזהה קמפיין 12345".
  • "איתור מודעות שנפסלו בכל הקמפיינים" הקוד שנוצר עובר בדיקה אוטומטית באמצעות ruff ונשמר בספרייה saved/code/.

• הרצה ישירה של API: הרצה ישירה של סקריפטים של Python שנוצרו לקריאה בלבד בתוך סביבה וירטואלית מבודדת (.venv) ותצוגה של תוצאות מעוצבות כטבלאות במסוף.

  • פשוט אומרים ל-Assistant: "הפעלת הקוד" או "הפעלת הסקריפט".
  • מטעמי בטיחות, פעולות שינוי (יצירה, עדכון, מחיקה) נוצרות אבל אף פעם לא מבוצעות.

• ייצוא CSV: שמירת תוצאות טבלאיות מקריאות API בקובץ CSV.

  • שומרים את התוצאות בקובץ CSV. הקבצים נשמרים בספרייה saved/csv/.

• אבחון מתקדם ופתרון בעיות: קבלת עזרה בנוגע להודעות שגיאה, להתנהגות לא צפויה של ה-API או לבעיות בהמרות אופליין.

  • "למה לא מוצגות תוצאות לשאילתה שלי?"
  • "פתרון בעיות שקשורות להמרות שלי עבור לקוח מספר 123-456-7890". (יוצר דוח אבחון מפורט ב-saved/data/).

• הקשר נוסף: אפשר להוסיף בסיס קוד משלכם או ספריות בהתאמה אישית כדי לספק הקשר.

  • משתמשים בסקריפט update.sh עם האפשרות --context_path כדי לרשום את קובצי הפרויקט: none ./update.sh --context_path /path/to/your/codebase
  • כך Assistant תוכל לכלול את הלוגיקה של האפליקציה בחשיבה הרציונלית שלה כשהיא יוצרת תשובות או קוד בשפה המועדפת עליכם.

תרחישים לדוגמה

• דיווח:
  • "תביא לי את 5 מילות המפתח המובילות לפי עלות לחודש שעבר עבור לקוח מספר 12345678".
• מבנה החשבון:
  • "תציג את כל שמות הקמפיינים ואת המזהים שלהם".
• פתרון בעיות:
  • "העליתי 100 המרות, אבל רק 78 מופיעות בממשק המשתמש. איך אפשר לנפות באגים באמצעות ה-API?"
• חינוך והשכלה:
  • ‫"/explain what a shared set is"
• יצירת קוד:
  • "כתוב קוד ליצירת קמפיין למיקסום הביצועים עבור company name".

תמיכה וקהילה

• בעיות ב-GitHub: אפשר לדווח על באגים, להציע תכונות או לבקש עזרה בכרטיסייה Issues במאגר.
• ‫Discord: אפשר להצטרף לדיון בערוץ #ads-api-ai-tools בשרת Discord של קהילת הפרסום והמדידה של Google.
• משוב: נשמח לקבל ממך משוב באמצעות טופס הסקר הזה.

הנחיות להוספת תוכן

נשמח לקבל תרומות! הנחיות זמינות בקובץ CONTRIBUTING.md במאגר GitHub.