התקנה ושימוש ב-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, בפקודות דרך שורת הפקודות מובנות ובכישורים מיוחדים בתחום כדי לשמור על הקשר מתמשך, על גבולות בטיחות חזקים ועל צינורות אימות אוטומטיים.

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

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

  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 כדי לטעון את התוסף.
  • ‫Claude Code: בסשן פעיל של Claude Code, מריצים את /reload-plugins או מפעילים מחדש את claude.

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

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

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

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

    • "אילו סוגי קמפיינים זמינים?"
    • "איך מסננים לפי תאריך ב-GAQL?"
    • "תסביר את ההבדל בין click_view לבין 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>
    • שפה טבעית: "בדיקת משאב קמפיין"

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

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

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

    • אומרים ל-Assistant: "הפעלת הקוד" או "הפעלת הסקריפט".
    • בטיחות בפעולות שינוי: מטעמי בטיחות, פעולות שינוי (יצירה, עדכון, מחיקה) נוצרות ב-saved/code/ אבל אף פעם לא מבוצעות ישירות על ידי 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
    • שפה טבעית: "צור מסנני החרגה של דפי אינטרנט בקמפיין למיקסום הביצועים"

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

    • 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 בודק שדות, סוגים וספירות (enums) של 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

הסרת ההתקנה

כדי להסיר את תוסף העוזר הדיגיטלי:

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?