תחילת העבודה

מומלץ להשתמש בספריית הלקוח באמצעות Apache Maven (או Gradle).

יצירת פרויקט Maven/Gradle חדש

יוצרים פרויקט חדש ב-Maven/Gradle בסביבת הפיתוח המשולבת (IDE) לבחירתכם. פריטי המידע שנוצרו בתהליך הפיתוח (Artifact) שלנו מתפרסמים במאגר המרכזי של Maven.

התלות של Maven היא:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>31.0.0</version>
</dependency>

התלות של Gradle היא:

implementation 'com.google.api-ads:google-ads:31.0.0'

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

קבלת פרטי כניסה לצורך אימות באמצעות ה-API

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

קוד מפתח (לגישה ל-API)

אסימון המפתח מקושר לחשבון ניהול וניתן למצוא אותו בממשק האינטרנט של Google Ads.

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

פרטי כניסה בפרוטוקול OAuth (לגישה לחשבונות Google Ads)

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

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

אם אישרתם שימוש בפרטי הכניסה שלכם (תהליך אפליקציה למחשב)
לעיון בתהליך של אפליקציות OAuth למחשב. זה כולל את כל הפרטים שאתם צריכים כדי לתת הרשאה באמצעות פרטי הכניסה שלכם.
אם אישרתם את השימוש שלכם כמשתמשי Google מצד שלישי (תהליך באתר)
לעיון בתהליך של אפליקציית אינטרנט ב-OAuth. זוהי דוגמה להגדרה של הרשאת OAuth למשתמשי צד שלישי שרירותיים.
אם ביצעת הרשאה כמשתמש בדומיין של Google Apps (תהליך חשבון שירות)
קוראים את תהליך העבודה בחשבון שירות OAuth. כאן מוצגת דוגמה להגדרת הרשאת OAuth למשתמשים בדומיין של Google Apps.

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

מספר לקוח להתחברות (לגישה לחשבונות Google Ads דרך חשבון ניהול)

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

הגדרת ספריית הלקוח באמצעות פרטי הכניסה

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

יוצרים קובץ ~/ads.properties עם התוכן הבא:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

מחליפים את ה-placeholders בפרטי הכניסה שקיבלתם בשלב הקודם.

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

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

אימות פרטי הכניסה

כדי לוודא שהכול מוגדר כמו שצריך, נציג את הדוגמה GetCampaigns.

קודם כול, נכנסים לספרייה google-ads-examples.

$ cd google-ads-examples

בדוגמה הזו נדרש פרמטר --customerId שבו הערך הוא מספר הלקוח בחשבון Google Ads, ללא מקפים.

כדי להשתמש ב-Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

דוגמאות נוספות

חבילת הדוגמאות ב-google-ads-examples כוללת כמה דוגמאות שימושיות. לרוב הדוגמאות נדרשים פרמטרים. אפשר להעביר את הפרמטרים כארגומנטים (מומלץ) או לערוך את ערכי INSERT_XXXXX_HERE בקוד המקור. כדי לראות דוגמה של הצהרת שימוש, צריך להעביר את --help כארגומנט היחיד.

עם גרדל:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

אפשר גם להשתמש במשימה listExamples ב-Gradle כדי להציג רשימה של כל הדוגמאות, הדוגמאות בספריית המשנה או דוגמאות שבהן התיאור כולל מונח חיפוש.

# List all examples:
$ ./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
$ ./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
$ ./gradlew -q listExamples --searchTerm='Performance Max'