התקנה ושימוש ב-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?