תחילת העבודה

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

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

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

מומלץ להשתמש ברשימת החומרים (BOM) של Google Ads API כדי לנהל גרסאות של תלות. זו הדרך הטובה ביותר להימנע מסכסוכי תלות עם ספריות כמו Guava ו-GAX שמשמשות גם מסגרות אחרות. ה-BOM מבטיח שתשתמשו בגרסאות המדויקות של התלויות האלה שנבדקו עם ספריית הלקוח של Google Ads.

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

<!-- Import the Bill of Materials (BOM) to ensure you're using compatible
     versions of all google-ads libraries. -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>google-ads-bom</artifactId>
      <version>40.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- Add the google-ads dependency, without a version. The version is
     managed by the BOM. -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
</dependency>

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

// Import the Bill of Materials (BOM).
implementation platform('com.google.api-ads:google-ads-bom:40.0.0')

// Add the google-ads dependency, without a version.
implementation 'com.google.api-ads:google-ads'

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

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

הצהרה על יחסי תלות שכלולים ב-BOM

רשימת החומרים (BOM) של Google Ads API כוללת ניהול גרסאות של כמה ספריות נפוצות, כמו Guava,‏ Protobuf,‏ GAX ו-gRPC. כדי למנוע התנגשויות פוטנציאליות בין יחסי תלות, אסור לציין גרסה כשמצהירים על יחסי תלות שרשימת החומרים מכסה. ה-BOM מנהל באופן אוטומטי את הגרסאות של הספריות האלה, כדי להבטיח תאימות.

לדוגמה, כדי להצהיר על התלות ב-Guava ב-Maven, משתמשים בקוד הבא:

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- NO VERSION SPECIFIED -->
</dependency>

וב-Gradle:

implementation 'com.google.guava:guava' // NO VERSION SPECIFIED

אם לא מציינים את הגרסה, ה-BOM מנהל אותה, וכך אפשר למנוע בעיות שנגרמות בגלל גרסאות תלות לא תואמות. אינדיקטורים נפוצים של קונפליקטים של תלות כוללים NoSuchMethodError או ClassNotFoundException, שאפשר לפתור אותם בדרך כלל על ידי וידוא שלכל התלויות שמנוהלות על ידי BOM לא צוינה גרסה.

קבלת פרטי כניסה לאימות באמצעות ה-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 דרך חשבון ניהול)

הערה: למשתמש ב-Google יכולה להיות גישה למספר חשבונות Google Ads.

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

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

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

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

יוצרים קובץ ~/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'

הערה: מקוד המקור, אפשר להתעלם מהערות עם [START...] ו-[END...] – הן משמשות את Google באופן ספציפי.