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

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

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

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

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

  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 host כדי לטעון את הפלאגין.
  • ‫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 הימים האחרונים?)
    • "קבלת כל השמות של קבוצות המודעות שמופעלות עבור לקוח מספר 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/ אבל אף פעם לא מבוצעות ישירות על ידי העוזר. צריך לבדוק אותן ולהפעיל אותן באופן ידני מחוץ לעוזר הדיגיטלי.

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

    • ‫Claude Code: /troubleshoot-conversions
    • שפה טבעית: "פתרון בעיות שקשורות להמרות עבור לקוח מספר 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

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

claude plugin marketplace remove google-ads-assistant-local

תמיכה וקהילה

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

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

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