תחילת העבודה

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

יצירת פרויקט חדש ב-Maven או ב-Gradle

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

התלות ב-Maven היא:

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

התלות ב-Gradle היא:

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

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

אם אתם יוצרים גרסת build ממקור, אתם צריכים לוודא שהפעלתם את עיבוד ההערות בסביבת הפיתוח המשולבת (IDE).

קבלת פרטי כניסה לאימות באמצעות ה-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"

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

חבילת 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'