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

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

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

  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: ```bash ./install.sh agy

או כוללים ספריות לקוח נוספות:

‪./install.sh agy --java --dotnet ```

‫Windows (PowerShell): ```powershell .\install.ps1 -Type agy

או כוללים ספריות לקוח נוספות:

‪.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

‫Linux / macOS: ```bash ./install.sh claude

או כוללים ספריות לקוח נוספות:

‪./install.sh claude --php --dotnet ```

‫Windows (PowerShell): ```powershell .\install.ps1 -Type claude

או כוללים ספריות לקוח נוספות:

‪.\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).

    • "תציג לי את הקמפיינים עם הכי הרבה המרות ב-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/).

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

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

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

    • Claude Code: /pmax-filter
    • שפה טבעית: "Create webpage exclusion filters for my PMax campaign"

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

    • ‫Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • ‫Windows (PowerShell): 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: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

‫Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

‫Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

‫Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

הסרה

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

Antigravity

‫Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

‫Windows (PowerShell): powershell Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

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

Claude Code

בסשן פעיל של Claude Code: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

או מהטרמינל: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(אופציונלי) מסירים את הרישום של השוק המקומי: bash claude plugin marketplace remove google-ads-assistant-local

תמיכה וקהילה

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

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

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