תחילת העבודה

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

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

יוצרים פרויקט Maven/Gradle חדש בסביבת הפיתוח המשולבת (IDE) לפי בחירתכם. ארטיפקטים שלנו מפורסמים במאגר המרכזי של 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"

עוד דוגמאות

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