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

‫Google Ads API Developer Assistant הוא כלי שמאפשר לכם להשתמש במומחיות של Google Ads API ישירות בסביבת ה-AI שבה אתם כותבים קוד. אתם יכולים להשתמש בהנחיות בשפה טבעית ובפקודות מובנות דרך שורת הפקודות כדי ליצור שאילתות, ליצור קוד של ספריית לקוח, להריץ קריאות ל-API לקריאה בלבד, להעביר דוחות אד-הוק ולפתור בעיות בשילובים.

ה-Assistant מבוסס על מסגרות הסוכנים Google Antigravity ו-Claude Code (גרסה 4.0.0) כפלאגין מודולרי. הוא משתמש בחוזים של AGENTS.md ו-CLAUDE.md, בפקודות דרך שורת הפקודות מובנות ובמיומנויות דומיין מיוחדות כדי לשמור על הקשר עקבי, גבולות בטיחות חזקים וצינורות עיבוד נתונים אוטומטיים לאימות. במאמר מהו Google Ads API Developer Assistant? מופיעה סקירה כללית על הארכיטקטורה והעיצוב שלו.

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

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

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

  2. תוכנה:

שנתחיל?

כדי לשכפל את המאגר, להריץ את סקריפט ההתקנה הספציפי לפלטפורמה, להגדיר את פרטי הכניסה ולהפעיל את הפלאגין, פועלים לפי השלבים הבאים.

1. שכפול המאגר

משכפלים את המאגר למכונה המקומית ועוברים לספריית הפרויקט:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. מריצים את סקריפט ההתקנה

מריצים את סקריפט ההתקנה של פלטפורמת היעד. כברירת מחדל, ספריית הלקוח של Python כלולה. אפשר גם לכלול ספריות לקוח נוספות (--php,‏ --ruby,‏ --java,‏ --dotnet או --all).

Antigravity

Linux / macOS:

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell):

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS:

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell):

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. הגדרת פרטי כניסה

מוודאים שקובץ התצורה של ה-API (לדוגמה, google-ads.yaml,‏ google_ads_php.ini או google_ads_config.rb) נמצא בספרייה $HOME.

(אופציונלי) כדי להגדיר מספר לקוח כברירת מחדל, מזינים את מספר הלקוח ישירות ב-config/customer_id.txt (לדוגמה, 1234567890). אפשר גם לבדוק או להצמיד את גרסת ה-API הפעילה ב-config/api_version.txt.

4. מפעילים את הפלאגין.

  • ‫Antigravity: מפעילים מחדש את הסשן המארח של Antigravity או של agy כדי לטעון את הפלאגין.
  • thought ‫Claude Code: בסשן פעיל של Claude Code, מריצים את /reload-plugins או מפעילים מחדש את claude.

5. אינטראקציה עם Assistant

אתם יכולים לתקשר עם Assistant באמצעות הנחיות בשפה טבעית או פקודות ייעודיות דרך שורת הפקודות ישירות בטרמינל.

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

  • שאלות ותשובות בשפה טבעית והנחיות קונספטואליות: אתם יכולים לשאול שאלות על התכונות של Google Ads API, כללי הארכיטקטורה, השיטות המומלצות או משאבים ספציפיים. ה-Assistant מבסס את התשובות שלו על הגדרות API רשמיות, ולא מסתמך רק על אימון כללי של מודל שפה גדול (LLM).

    • "אילו סוגי קמפיינים זמינים?"
    • "איך מסננים לפי תאריך ב-GAQL?"
    • "Explain the difference between click_view and impression_view."‎
    • "מהי קבוצה משותפת ואיך משתמשים בה?"
    • פקודות דרך שורת הפקודות ב-Claude Code: /explain, /step-by-step, /assistant-tutorial

  • יצירת קוד מבוסס-קרקע לספריית לקוח: יצירת קוד נבדק ואידיומטי באמצעות ספריות לקוח רשמיות של Google Ads (‏Python,‏ Java,‏ PHP,‏ NET. ו-Ruby).

    • "Show me campaigns with the most conversions in the last 30 days" (אני רוצה לראות את הקמפיינים עם הכי הרבה המרות ב-30 הימים האחרונים).
    • "Get all enabled ad group names for customer 123-456-7890."
    • "כתוב קוד ליצירת קמפיין למיקסום ביצועים."‎ הקוד שנוצר נשמר בספרייה saved/code/.

  • אימות פרוגרמטי של שאילתות GAQL: הרצה יבשה ואימות אוטומטיים של שאילתות מורכבות לפי המטא-נתונים של ה-API, תאימות השדות, כללי אפס חשיפות ופילוח לפי תאריכים לפני ההרצה.

    • ‫Claude Code: /validate-gaql
    • שפה טבעית: validate: SELECT campaign.id FROM campaign

  • בדיקת סכימות של אובייקטים ו-Protobuf: בדיקה דינמית של מבני משאבים, שדות בתצוגת עץ, סוגי נתונים וערכי enum לכל גרסת API פעילה, בלי תקורה של מטא-נתונים מרחוק.

    • ‫Claude Code: /inspect-object <resource_or_enum>
    • שפה טבעית: "Inspect campaign resource"

  • דיווח אד-הוק בזמן אמת וייצוא לקובץ CSV: אתם יכולים לבקש נתוני ביצועים בשפה פשוטה. ה-Assistant יוצר, מאמת ומריץ שאילתות GAQL ישירות בחשבון, ומציג טבלאות בפורמט חי בטרמינל.

    • "הצג את 5 מילות המפתח המובילות לפי עלות בחודש שעבר ללקוח 123-456-7890"
    • "שמור את התוצאות כקובץ CSV" (ייצוא אל saved/csv/).

  • הפעלה ישירה של API ואבטחת שינויים: הפעלה של סקריפטים לקריאה בלבד שנוצרו ישירות בסביבה וירטואלית מנוהלת.

    • אומרים ל-Assistant: "Run the code" או "Execute the script".
    • בטיחות בפעולות שינוי: מטעמי בטיחות, פעולות שינוי (יצירה, עדכון, מחיקה) נוצרות ב-saved/code/ אבל אף פעם לא מבוצעות ישירות על ידי Assistant. צריך לבדוק אותן ולבצע אותן באופן ידני מחוץ ל-Assistant.

  • אבחון מתקדם ופתרון בעיות בהמרות: חקירת כשלים בהעלאת המרות אופליין, אימות מראש של קובצי העלאה ויצירת דוחות אבחון מפורטים.

    • ‫Claude Code: /troubleshoot-conversions
    • שפה טבעית: "Troubleshoot conversions for customer 123-456-7890" (הדוחות נשמרים ב-saved/data/).

  • מיפוי היררכיית חשבונות ניהול: אחזור מספרי לקוחות של חשבונות משנה ומיפוי היררכיות של חשבונות בחשבון ניהול.

    • ‫Claude Code: /get-cids <manager_cid>
    • שפה טבעית: "קבל את כל מספרי הלקוח של הלקוחות המשלמים ולקוחות הקצה תחת מנהל 123-456-7890"

  • מסננים והחרגות של כרטיסי מוצר בקמפיינים למיקסום הביצועים: יוצרים עצי קטגוריות מוצרים והחרגות של כתובות URL של דפי אינטרנט לקבוצות נכסים.

    • ‫Claude Code: /pmax-filter
    • שפה טבעית: "צור מסנני החרגה של דפי אינטרנט בקמפיין למיקסום הביצועים"

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

    • Linux / macOS:

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell):

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

מדריך לפקודות דרך שורת הפקודות ב-Claude Code

כשמשתמשים ב-Claude Code, אפשר להשתמש בפקודות המובנות הבאות דרך שורת הפקודות. ב-Google Antigravity, אתם יכולים להפעיל את אותן יכולות באמצעות הנחיות בשפה טבעית או שמות של כלי מיומנות כמו validate_gaql ו-inspect_object, כפי שמתואר בקטע תכונות עיקריות:

פקודה דרך שורת הפקודות מטרה דוגמה
/validate-gaql מאמת את התחביר, התאימות והכללים של GAQL. /validate-gaql
/inspect-object בדיקת שדות, סוגים וערכי enum של Protobuf. /inspect-object Campaign
/get-cids מזהה את ההיררכיות של חשבונות הניהול ואת מספרי הלקוח של חשבונות הלקוח. /get-cids 1234567890
/troubleshoot-conversions מפעיל אבחון של העלאת המרות אופליין. /troubleshoot-conversions
/pmax-filter יצירת מסננים והחרגות של כרטיסי מוצר בקמפיינים למיקסום הביצועים. /pmax-filter
/explain מספק הסבר מובנה בן 4 חלקים. /explain shared set
/step-by-step מגבש תוכנית לביצוע משימות בכמה שלבים. /step-by-step upload conversions
/assistant-tutorial הפעלת הדרכה אינטראקטיבית בת 11 שלבים. /assistant-tutorial

תחזוקה ועדכונים

כדי לעדכן את המאגר, את התקנת הפלאגין ואת ספריות הלקוח:

Antigravity

Linux / macOS:

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS:

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

הסרת ההתקנה

כדי להסיר את הפלאגין של Assistant:

Antigravity

Linux / macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell):

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

לאחר מכן, מפעילים מחדש את הסשן של מארח Antigravity.

Claude Code

בסשן פעיל של Claude Code:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

או מהטרמינל:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

‫(אופציונלי) מסירים את המרשם המקומי של Marketplace:

claude plugin marketplace remove google-ads-assistant-local

תמיכה וקהילה

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

נשמח לקבל תרומות. הנחיות מפורטות בקובץ CONTRIBUTING.md במאגר ב-GitHub.

השלבים הבאים

הקודם
מהו Google Ads API Developer Assistant?