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

1. מבוא

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

מה תלמדו

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

מה צריך להכין

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

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

מורידים את הקוד

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

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

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

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

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

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

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

mvn compile

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

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

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

בקודלאב הזה נעשה שימוש באותו טעינת פרטי הכניסה כמו בספריית הלקוח, כך שאם כבר השתמשתם בספריית הלקוח של 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 באמצעות חשבון שירות. כלומר, עותק של המפתח של חשבון השירות צריך להיות ממוקם בנתיב הבא מספריית הבית: shopping-samples/content/service-account.json. אין צורך להגדיר את ההגדרות של הדוגמאות, אלא אם אתם רוצים לנסות את הדוגמאות אחרי שסיימתם את הקודלאב הזה.

רוצים לנסות?

עכשיו, כשאסימוני האימות נמצאים במקומות הנכונים, אפשר לנסות להריץ את הדוגמאות. אם משתמשים ב-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(). באמצעות המופע הזה, אפשר ליצור לקוחות לשירותים האלה באמצעות השיטה 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 שמכיל את ההגדרות של החשבון החדש. נוצר חשבון בדיקה לקודלאב הזה, ונגדיר את המטבע שלו כדולר ארה"ב ואת אזור הזמן שלו כאותו אזור זמן של החוף המערבי בארה"ב.

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

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

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

בקודלאב, יצרנו קודם את חשבון 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, צריך להשתמש ב-method getServiceLinks של האובייקט CustomerServiceInterface.

העולם הוא מגרש המשחקים שלכם

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