תחילת העבודה

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

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

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

תלות Maven:

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

יחסי התלות ב-Gradle הם:

implementation 'com.google.api-ads:google-ads:36.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, ואילו אפליקציות אינטרנט יכולות להפנות אוטומטית לדפדפן צד שלישי שרירותי כדי להשלים את ההרשאה ולשלוח את פרטי הכניסה בחזרה לשרת שלכם. הספרייה תומכת גם בתהליך פחות נפוץ של חשבון שירות.

אם נותנים הרשאה באמצעות פרטי הכניסה שלכם (תהליך באפליקציה למחשב)

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

אם נותנים הרשאה כמשתמש 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

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

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

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"

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

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

באמצעות Gradle:

$ ./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'