מדריך למשתמשים חדשים ב-Google Ads API

במדריך הזה מוסבר התהליך המלא של הצטרפות, אימות וביצוע הקריאה הראשונה ל-Google Ads API.

1. דרישות מוקדמות והיררכיית חשבונות

לפני שמתחילים אינטראקציה עם Google Ads API, חשוב להבין את ההיררכיה של החשבון ולוודא שמבנה החשבון ברמה העליונה תקין.

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

פעולה נדרשת: אם אין לכם חשבון ניהול, אתם צריכים ליצור אחד בכתובת חשבונות ניהול ב-Google Ads.

2. קבלת קוד מפתח

קוד המפתח מזהה באופן ייחודי את האפליקציה שלכם ב-Google Ads API, וקובע את רמת הגישה שלכם לנפח הקריאות.

השלבים להגשת בקשה

1. נכנסים לחשבון הניהול ב-Google Ads.
2. עוברים אל כלים והגדרות > הגדרה > מרכז API (או אל אדמין > מרכז API).
3. ממלאים את טופס פרטי המפתח ומאשרים את התנאים וההגבלות של ה-API.
4. שולחים את הבקשה.

רמות הגישה

• בהמתנה לאישור: טוקנים שנוצרו לאחרונה מקבלים מיד את הסטטוס 'בהמתנה'. אפשר להשתמש באסימון בהמתנה כדי להתחבר לחשבונות בדיקה באופן מיידי, אבל הוא לא יפעל בחשבונות ייצור.
• גישה בסיסית: מאפשרת עד 15,000 פעולות API ביום לאחר האישור.
• גישה רגילה: מספר בלתי מוגבל של פעולות API יומיות לאפליקציות שעומדות בפונקציונליות המינימלית הנדרשת (RMF).

3. הגדרת חשבונות בדיקה

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

יצירת חשבון ניהול לבדיקה

1. עוברים אל הדף ליצירת חשבון ניהול לבדיקה ב-Google Ads.
2. נכנסים באמצעות חשבון Google שעדיין לא מקושר לחשבון הניהול הפעיל ב-Google Ads.
3. מזינים שם תיאורי לחשבון (לדוגמה, MyCompany Test MCC).
4. בוחרים את השימוש העיקרי כניהול חשבונות של אנשים אחרים.
5. בוחרים את המדינה לצורכי חיוב, את אזור הזמן ואת המטבע. לוחצים על שמירה והמשך.

יצירת חשבון לקוח לבדיקה

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

1. נכנסים אל החשבון החדש ב-Test Manager.
2. בתפריט הניווט השמאלי, לוחצים על חשבונות ואז על הגדרות חשבון משנה (או על ביצועים).
3. לוחצים על לחצן הפלוס הכחול + ובוחרים באפשרות יצירת חשבון חדש.
4. בוחרים באפשרות חשבון Google Ads.
5. מזינים שם חשבון (למשל, Test Client Account A).
6. בוחרים אזור זמן ומטבע ולוחצים על שמירה והמשך.
7. רושמים את מספר הלקוח בן 10 הספרות (למשל, 1234567890 ללא מקפים) של חשבון הלקוח החדש.

כללים חשובים לגבי חשבונות בדיקה

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

4. הגדרת פרויקט Google Cloud

כל בקשות ה-API צריכות להיות מאומתות באמצעות פרויקט בענן של Google שבו מופעל Google Ads API.

שלבים להפעלת ה-API

1. נכנסים אל מסוף Google Cloud.
2. יוצרים פרויקט חדש או בוחרים פרויקט קיים.
3. עוברים אל APIs & Services > Library.
4. מחפשים את Google Ads API ולוחצים על הפעלה.

תמחור וחיוב

• ללא עמלות על API: יצירת פרויקט בענן ב-Google Cloud, הפעלת Google Ads API ויצירת פרטי כניסה ל-OAuth 2.0 הם ללא עלות. ‫Google לא גובה עמלות על קריאה ל-Google Ads API או על שימוש בו.
• משאבי Cloud אחרים: תחויבו על השימוש ב-Google Cloud רק אם תשתמשו באופן פעיל בשירותים אחרים של Google Cloud שניתנים בתשלום (כמו Compute Engine,‏ Cloud Run או BigQuery) מעבר למגבלות של התוכנית ללא תשלום, כדי לארח את האפליקציה או לאחסן את נתוני הפרסום.

5. הגדרת אימות OAuth 2.0

ממשק Google Ads API משתמש ב-OAuth 2.0 כדי לאמת ולאשר בקשות.

שלבים בתהליך של אפליקציה למחשב

1. בפרויקט שלכם ב-Google Cloud, עוברים אל APIs & Services > OAuth consent screen ומגדירים את מסך ההסכמה. כדי למנוע שגיאות גישה במהלך ההרשאה, צריך להוסיף את כתובת האימייל שלכם לקטע משתמשי בדיקה בזמן שהאפליקציה במצב 'בדיקה'.
2. עוברים אל APIs & Services > Credentials.
3. לוחצים על Create Credentials > OAuth client ID (יצירת פרטי כניסה > מזהה לקוח OAuth).
4. בוחרים באפשרות אפליקציה למחשב כסוג האפליקציה.
5. לוחצים על Create (יצירה) ומורידים את קובץ פרטי הכניסה של OAuth בתור client_secret.json (או מעתיקים את Client ID ואת Client Secret).

יצירת טוקן רענון

אחרי שמקבלים את מזהה הלקוח ואת הסוד של הלקוח, צריך ליצור אסימון רענון. אפשר לעשות את זה באמצעות Google OAuth 2.0 Playground או סקריפט של ספריית לקוח.

שיטה א': שימוש ב-Google OAuth 2.0 Playground

1. עוברים אל Google OAuth 2.0 Playground.
2. לוחצים על סמל גלגל השיניים (הגדרת OAuth 2.0) בפינה השמאלית העליונה.
3. מסמנים את התיבה לצד האפשרות Use your own OAuth credentials (שימוש בפרטי הכניסה שלכם ב-OAuth).
4. מזינים את נתוני OAuth2‏ Client ID ו-Client Secret ולוחצים על סגירה.
5. בשלב 1 (בחירה והרשאה של ממשקי API) בצד ימין, מזינים את היקף Google Ads API בשדה 'הזנת היקפים משלך': https://www.googleapis.com/auth/adwords
6. לוחצים על Authorize APIs. כשתוצג הבקשה, נכנסים באמצעות חשבון Google שיש לו גישה לחשבון הניהול ב-Google Ads (או לחשבון הבדיקה).
7. לוחצים על המשך במסך הסכמה.
8. בשלב 2 (קבלת אסימונים תמורת קוד הרשאה), לוחצים על הלחצן הכחול קבלת אסימונים תמורת קוד הרשאה.
9. התשובה תופיע בחלונית התגובה עם Refresh token וAccess token. מעתיקים ושומרים את Refresh token.

שיטה ב': שימוש בסקריפט של ספריית לקוח (דוגמה ב-Python)

ספריית הלקוח הרשמית של Python מספקת סקריפט עזר מובנה ליצירת פרטי כניסה. לחלופין, אפשר להוריד את client_secret.json ממסוף Google Cloud ולהריץ את סקריפט ה-Python העצמאי הבא:

1. מתקינים את ספריית OAuth הנדרשת:

pip install google-auth-oauthlib

1. יוצרים סקריפט בשם generate_refresh_token.py באותה ספרייה שבה נמצא client_secret.json ומפעילים פתרונות חכמים:

from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. הגדרה של ספריית לקוח ופרטי כניסה

‫Google מספקת ספריות לקוח עם תמיכה רשמית שמטפלות באימות, בסריאליזציה ובתקשורת עם נקודות הקצה של gRPC.

שפות נתמכות

• ‫Python: pip install google-ads
• ‫Java: זמין דרך Maven או Gradle
• ‫PHP: composer require googleads/google-ads-php
• ‫‎.NET: Install-Package Google.Ads.GoogleAds
• ‫Ruby: gem install google-ads-googleads
• ‫Perl: cpanm Google::Ads::GoogleAds::Client

קובץ תצורה (google-ads.yaml)

יוצרים קובץ הגדרות שכולל את פרטי הכניסה. כברירת מחדל, שיטת האתחול של ספריית הלקוח (למשל, GoogleAdsClient.load_from_storage()) תחפש באופן אוטומטי את google-ads.yaml בשני מיקומים:

1. ספריית העבודה הנוכחית שממנה מריצים את הסקריפט.
2. ספריית הבית של המשתמש (~ ב-Linux/macOS או %HOMEPATH% ב-Windows).

אם מאחסנים את הקובץ במיקום מותאם אישית, אפשר להעביר באופן מפורש את הנתיב לשיטת האתחול (למשל, load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. ביצוע הקריאה הראשונה ל-API

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

סקריפט Python לדוגמה (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. שיטות מומלצות ומקורות מידע

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