תחילת העבודה

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

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

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

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

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

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

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

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

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

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

קוד מפתח (לגישה ל-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'