יצירה וקישור של חשבונות משנה ב-AdWords וב-Merchant Center

1. מבוא

ב-Codelab הזה תלמדו כמה מהיסודות של עבודה עם Content API for Shopping ועם AdWords API, ותיצרו אפליקציה שמשתמשת בשניהם. בפרט, תיצרו אפליקציית שורת פקודה שתייצר ותקשר חשבון AdWords וחשבון Merchant Center.

מה תלמדו

• איך ליצור חשבונות AdWords שמנוהלים על ידי חשבון ניהול.
• איך יוצרים חשבונות Merchant Center שמנוהלים על ידי חשבון מרובה לקוחות.
• איך שולחים בקשה לקישור חשבון Merchant Center לחשבון AdWords.
• איך מאשרים קישור של חשבון Merchant Center בהמתנה בחשבון AdWords.

מה תצטרכו

• חשבון ניהול ב-AdWords
• חשבון מרובה לקוחות ב-Merchant Center
• ‫Java 7 ומעלה
• Maven
• קוד לדוגמה
• עורך טקסט (מומלץ להשתמש ב-IDE שמבין פרויקטים של Maven, כמו Eclipse או IntelliJ)

2. תהליך ההגדרה

הורדה של הקוד

כדי להוריד את כל הקוד של ה-Codelab הזה, לוחצים על הקישור הבא:

הורדת קוד המקור

מחלצים את קובץ ה-ZIP שהורד. הפעולה הזו תפרוס תיקיית בסיס (shopping-account-linking-master), שמכילה פרויקט Maven יחד עם כל המשאבים שתצטרכו. חשוב לשים לב במיוחד לספריות המשנה הבאות:

• ‫src/main/java הוא שורש המקור של פרויקט Maven ומכיל שלד קוד שבו אפשר לעבוד.
• ‫src/main/java/solution מכיל את הפתרון המלא.

התקנת החבילות הנדרשות וביצוע build

אם אתם משתמשים ב-IDE עם תמיכה ב-Maven, כמו Eclipse או IntelliJ, אתם יכולים לייבא את התיקייה שחולצה כפרויקט Maven ואז לקמפל את הפרויקט כרגיל.

אם משתמשים ב-Maven משורת הפקודה, אפשר להריץ את הפקודה הבאה כדי לאחזר את החבילות הנדרשות ולבצע קומפילציה של הפרויקט מתיקיית הבסיס של הפרויקט שחולץ (shopping-account-linking-master):

mvn compile

3. מגדירים אימות

בשלב הזה לא נכתוב קוד, אלא נגדיר קבצים שמכילים טוקנים מתאימים לאימות עבור AdWords API ו-Content API for Shopping.

הגדרת אימות ב-AdWords API

ב-codelab הזה נעשה שימוש באותה טעינת אישורים כמו בספריית הלקוח, כך שאם כבר השתמשתם בספריית הלקוח של Google Ads API ל-Java עם חשבון הניהול שלכם, אתם כבר אמורים להיות מוכנים. אחרת, פועלים לפי השלבים 1-3 במאמר תחילת העבודה עם ספריית הלקוח של Google Ads API ל-Java.

הגדרת אימות של Content API

אם עדיין אין לכם מפתח לחשבון שירות:

1. עוברים אל Merchant Center בחשבון מרובה הלקוחות ובוחרים באפשרות Content API מתפריט האפשרויות הנוספות:
2. בוחרים באפשרות אימות ולוחצים על לחצן + הכחול:
3. אחרי שתאשרו את התנאים וההגבלות של Google Cloud Platform ושל Google APIs, הדפדפן יוריד באופן אוטומטי קובץ JSON שמכיל את המפתח החדש של חשבון השירות.

עכשיו פועלים לפי ההוראות להגדרת אימות עבור דוגמאות השופינג באמצעות חשבון שירות. כלומר, עותק של המפתח של חשבון השירות צריך להיות בנתיב הבא מספריית הבית: shopping-samples/content/service-account.json. לא צריך להגדיר את דוגמאות ההגדרות, אלא אם רוצים לנסות את הדוגמאות אחרי שמסיימים את ה-codelab הזה.

רוצים לנסות?

אחרי שמוודאים שיש אסימוני אימות במקומות הנכונים, מנסים להריץ את הדוגמאות. אם משתמשים ב-Maven בשורת הפקודה, מריצים את הפקודות הבאות:

mvn compile

הערה: אם משנים קבצים כלשהם בתיקייה src/main/resources, גם אם לא מבצעים שינויים בקוד (כמו בשלב הזה), צריך לבצע קומפילציה מחדש לפני שמריצים את הדוגמאות כדי להעתיק את המשאבים ששיניתם אל היעד.

mvn exec:java -Dexec.mainClass="SolutionRunner"

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

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

4. חיבור לממשקי ה-API

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

יצירת אובייקט סשן של Content API

כדי ליצור סשן ב-Content API, צריך ליצור אובייקט ShoppingContent.Builder ואז להשתמש בו כדי ליצור את אובייקט ShoppingContent המתאים. למזלנו, כל מה שצריך כדי ליצור את האפשרות הראשונה כבר זמין במבנה הקוד, אז אנחנו רק צריכים להרכיב אותו כך:

SolutionRunner.java

// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
    new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
        .setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
        .build();

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

בנוסף, אנחנו משמיטים כל הצהרת ייבוא שנדרשת עבור המחלקות של AdWords API ו-Content API שבהן אנחנו משתמשים בקטעי הקוד האלה. אם אתם לא משתמשים בסביבת פיתוח משולבת (IDE) שיכולה להוסיף באופן אוטומטי את הייבוא הנכון, כדאי לבדוק את הקוד בחבילה solution כדי לראות אילו ייבואים נדרשים.

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

יצירת אובייקט של סשן ב-AdWords API

באופן דומה, יש מחלקה AdWordsSession.Builder ליצירת אובייקטים מסוג AdWordsSession. ההבדל העיקרי כאן הוא שבמקום להגדיר את אפשרויות התצורה ישירות ב-builder, נשתמש בשיטה fromFile() כדי לטעון אותן מהקובץ ads.properties שהגדרנו בשלב הקודם.

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

רוצים לנסות?

נשתמש באותן פקודות כמו בקטע הקודם כדי לבנות מחדש את פרויקט Maven ולהריץ אותו, אם מריצים אותו משורת הפקודה:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

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

5. יצירה של חשבון AdWords מנוהל חדש

אחרי שיצרנו את אובייקטי הסשן של ה-API, נמשיך ליצור את החשבונות שאנחנו רוצים לקשר. נתחיל עם AdWords וניצור חשבון בדיקה בחשבון הניהול שלנו.

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

גישה אל ManagedCustomerService

ב-AdWords API, כדי לגשת לשירותים השונים שזמינים, קודם צריך לאחזר מופע של המחלקה AdWordsServices באמצעות השיטה הסטטית getInstance(). באמצעות המופע הזה, אפשר ליצור לקוחות לשירותים האלה באמצעות ה-method‏ get(), שמקבלת שני ארגומנטים: הסשן שעבורו רוצים ליצור את הלקוח והממשק של השירות הרצוי.

SolutionRunner.java

// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.

AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

ManagedCustomerServiceInterface managedCustomerService =
    adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);

כאן אנחנו ניגשים אל ManagedCustomerService, שמאפשר לנו לנהל 'לקוחות' (חשבונות) של AdWords מחשבון ניהול נתון.

מציינים את הגדרות החשבון החדשות

קודם ניצור אובייקט ManagedCustomer שמכיל את ההגדרות של החשבון החדש. ניצור חשבון בדיקה בשביל ה-codelab הזה, ונגדיר את המטבע שלו לדולר אמריקאי ואת אזור הזמן שלו לאותו אזור זמן של החוף המערבי בארה"ב.

SolutionRunner.java

Random rand = new Random();
long run = rand.nextLong();

ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");

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

יצירת החשבון המנוהל החדש

כדי ליצור את החשבון החדש בפועל, נשתמש ב-ManagedCustomerOperation כדי לציין פעולת ADD:

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

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

SolutionRunner.java

ManagedCustomerReturnValue result =
    managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);

רוצים לנסות?

כמו קודם, מנסים להריץ את הפתרון. אם משתמשים ב-Maven משורת הפקודה:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

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

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

6. יצירת חשבון משנה חדש ב-Merchant Center

בשלב הזה ניצור את חשבון המשנה ב-Merchant Center שנקשר לחשבון AdWords שיצרנו בשלב הקודם. במקום לבקש קישור בנפרד אחרי שיוצרים את החשבון המשני, אפשר לבקש את הקישור במהלך היצירה, כי כבר יש לנו את המזהה של חשבון AdWords המתאים.

מציינים את ההגדרות של חשבון המשנה החדש

בניגוד ל-AdWords API, הפונקציות להגדרת ערכים (setters) של מחלקת המודל Account מחזירות את האובייקט, כך שאפשר לשרשר את הקריאות אליהן באובייקט Account החדש. נשתמש גם במספר האקראי שיצרנו במהלך יצירת חשבון AdWords בשם של חשבון Merchant Center החדש.

SolutionRunner.java

Account newMcAccount = new Account()
    .setName(String.format("Merchant Center Account Created by Run %d", run))
    .setAdwordsLinks(
        ImmutableList.of(
            new AccountAdwordsLink()
                .setAdwordsId(BigInteger.valueOf(adWordsId))
                .setStatus("active")));

כמו שצוין במבוא לשלב הזה, מכיוון שכבר יש לנו את מספר חשבון AdWords של החשבון המנוהל החדש, אנחנו יכולים להוסיף את המספר הזה לרשימת AdwordsLinks של חשבון המשנה החדש עכשיו. כשיוצרים את חשבון המשנה החדש, הקישור הזה יתבקש באופן אוטומטי ויהיה זמין ב-AdWords API.

יצירת חשבון משנה חדש

ב-Content API, אנחנו קוראים ל-method‏ accounts() של אובייקט הסשן כדי לגשת לשירות Accounts, ואז קוראים ל-method‏ insert() ישירות במקום להגדיר אובייקט פעולה. השיטה הזו מקבלת שני ארגומנטים: המזהה של החשבון מרובה-הלקוחות שבו רוצים ליצור את חשבון המשנה החדש, ואובייקט Account שמכיל את ההגדרות הרצויות:

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

השיטה insert() מחזירה אובייקט Account שמכיל את ההגדרות של החשבון המשני החדש. אנחנו דורסים את אובייקט Account המקורי כי הגרסה שמוחזרת כוללת מידע חשוב: מזהה חשבון המשנה החדש. אנחנו מדפיסים את זה בפלט מהפתרון שלנו, כדי שנוכל להריץ את הפתרון ואז לוודא שחשבון המשנה החדש קיים ב-Merchant Center.

רוצים לנסות?

כמו קודם, מנסים להריץ את הפתרון. אם משתמשים ב-Maven משורת הפקודה:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

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

הערה: כמו ב-AdWords, כל הפעלה של הפתרון תיצור עכשיו חשבונות חדשים ב-Merchant Center. אחרי שתסיימו להשתמש בפתרון, תוכלו למחוק את כל החשבונות המשניים שיצרתם דרך Merchant Center.

7. אישור הקישור מחשבון AdWords

בשלב האחרון, יצרנו חשבון משנה חדש ב-Merchant Center וביקשנו לקשר אותו לחשבון AdWords החדש שלנו. בשלב הזה, נשלים את התהליך באמצעות AdWords API כדי לאשר את בקשת הקישור.

גישה אל CustomerService

כמו קודם, נשתמש במחלקה AdWordsServices כדי לקבל לקוח בשביל CustomerService. עם זאת, לפני שאנחנו יוצרים את חשבון הלקוח, אנחנו קודם משנים את אובייקט הסשן של AdWords כך ששימושים עתידיים יפעלו בחשבון המנוהל החדש במקום בחשבון הניהול. בסופו של דבר, חשבון Merchant Center ביקש קישור לחשבון המנוהל, לא לחשבון הניהול.

SolutionRunner.java

// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.

adWordsSession.setClientCustomerId(adWordsId.toString());

CustomerServiceInterface customerService =
    adWordsServices.get(adWordsSession, CustomerServiceInterface.class);

ציון הקישור המבוקש

בדומה ליצירה של חשבון AdWords חדש, ניצור אובייקט ServiceLink שמכיל את הגדרות הקישור, ואז אובייקט ServiceLinkOperation שמתאר את הפעולה הרצויה. במקרה הזה, אנחנו רוצים לקחת את הקישור לשירות בהמתנה לחשבון MERCHANT_CENTER וSET אותו ל-ACTIVE. בהגדרה serviceLinkId, נשתמש במזהה של חשבון Merchant Center שיצרנו, כי הוא משמש כמזהה של קישור השירות ב-AdWords.

SolutionRunner.java

ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);

ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);

אישור הקישור

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

SolutionRunner.java

ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d, type '%s' updated to status: %s.%n",
      mutatedServiceLink.getServiceLinkId(),
      mutatedServiceLink.getServiceType(),
      mutatedServiceLink.getLinkStatus());
}

רוצים לנסות?

כמו קודם, מנסים להריץ את הפתרון. אם משתמשים ב-Maven משורת הפקודה:

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

אם הכול ילך כשורה, לא אמורות להופיע שגיאות, ובנוסף תופיע הערה שהקישור לשירות עודכן והוא פעיל. בודקים ב-AdWords וב-Merchant Center ומוודאים שהחשבונות מקושרים.

8. וריאציות של עיצוב

כל הכבוד, סיימתם את ה-Codelab! עכשיו, אחרי שיש לכם פתרון שעובד באופן מלא, נראה כמה דוגמאות לאופן שבו אפשר לשנות או להרחיב אותו כדי להשתמש ביותר ממשקי ה-API שראיתם ב-codelab הזה.

נקודות בונוס: איך מעדכנים חשבון קיים ב-Merchant Center כדי לבקש קישור ל-AdWords

ב-codelab, יצרנו קודם את חשבון AdWords כדי שנוכל להשתמש בפרטים שלו כדי לבקש את הקישור כשניצור את חשבון Merchant Center. עם זאת, אם חשבון Merchant Center כבר קיים, תצטרכו לעדכן את ההגדרות שלו. אפשר לנסות לשנות את הקוד כדי ליצור קודם את חשבון Merchant Center, ואז לחזור אחרי יצירת חשבון AdWords ולעדכן את ההגדרה שלו כדי לבקש את הקישור.

הערה: מומלץ להשתמש בשיטה Accounts.update או בשיטה Accounts.patch. למעשה, כדאי לנסות גרסה עם כל אחת מהאפשרויות כדי להבין את ההבדל.

חשוב: יכול להיות שחשבון Merchant Center חדש לא יהיה זמין מיד אחרי הקריאה אל Accounts.insert. עד שהחשבון החדש יהיה זמין, תקבלו שגיאת HTTP 401 כשמנסים לגשת אליו או לשנות אותו. בדוגמאות של Shopping יש דוגמה לשימוש בהשהיה מעריכית לפני ניסיון חוזר של שיטות ב-AccountWorkflow.java, שמשתמשת בשיטה retryFailures מ-BaseWorkflowSample.java.

בונוס: אימות יצירת הקישור על ידי אחזור פרטי החשבון ב-AdWords וב-Merchant Center

נכון לעכשיו, האפליקציה מתייחסת רק להיעדר שגיאות מקריאות ל-API כסימן להצלחה. נסו להרחיב את הדוגמה כדי לבדוק את פרטי הקישור של חשבונות Merchant Center ו-AdWords החדשים, ולוודא שהקישור אכן פעיל.

הערה: בצד של Content API, כדאי לעיין בשיטה Accounts.get. בצד של AdWords, כדאי להשתמש בשיטה getServiceLinks של האובייקט CustomerServiceInterface.

The world's your oyster

אם עולים לכם רעיונות לשינויים נוספים, כדאי לנסות אותם. אם אתם צריכים קוד הפניה לרעיונות שלכם, תוכלו לעיין בדוגמאות של Google שופינג ובספרייה examples במקור של ספריית הלקוח של Google Ads Java.