1. מבוא
ב-Codelab הזה, תלמדו כמה יסודות העבודה עם Content API for Shopping ועם AdWords API ותלמדו איך לפתח אפליקציה שמתבססת על שניהם. באופן ספציפי, פיתוח אפליקציית שורת הפקודה תיצור ותקשר חשבון AdWords וחשבון Merchant Center.
מה תלמדו
- איך ליצור חשבונות AdWords שמנוהלים על ידי חשבון ניהול.
- איך יוצרים חשבונות Merchant Center שמנוהלים באמצעות חשבון מרובה לקוחות
- איך לבקש קישור מחשבון Merchant Center לחשבון AdWords.
- איך מאשרים קישור Merchant Center בהמתנה בחשבון AdWords
מה צריך להכין
- חשבון ניהול ב-Google Ads
- חשבון מרובה לקוחות ב-Merchant Center
- Java 7 ואילך
- Maven
- הקוד לדוגמה
- כלי לעריכת טקסט (מומלץ להשתמש בסביבת פיתוח משולבת (IDE) שמבין פרויקטים של Maven כמו Eclipse או IntelliJ)
2. בתהליך ההגדרה
הורדת ה-Code
כדי להוריד את כל הקוד של Codelab זה, יש ללחוץ על הקישור הבא:
פורקים את קובץ ה-ZIP שהורדתם. הפעולה הזו תפרק את תיקיית הבסיס (shopping-account-linking-master
), המכילה פרויקט Maven יחד עם כל המשאבים הדרושים. חשוב לשים לב לספריות המשנה הבאות:
src/main/java
הוא הרמה הבסיסית (root) של הפרויקט ב-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 APIs ל-Java עם חשבון הניהול, אז האפשרות אמורה להיות זמינה עבורכם. אם לא, מבצעים את שלבים 1-3 כדי להתחיל בעבודה עם ספריית הלקוח של Google Ads APIs ל-Java.
הגדרה של אימות ב-Content API
אם עדיין אין לך מפתח לחשבון השירות:
- עוברים אל Merchant Center של החשבון מרובה הלקוחות ובוחרים Content API בתפריט האפשרויות הנוספות:
- בוחרים באפשרות אימות ולאחר מכן לוחצים על לחצן + הכחול:
- אחרי שתאשרו את התנאים וההגבלות של Google Cloud Platform ושל Google APIs, הדפדפן יוריד באופן אוטומטי קובץ JSON שמכיל את המפתח החדש של חשבון השירות שלכם.
עכשיו מבצעים את ההוראות להגדרת אימות עבור הדוגמאות לשופינג באמצעות חשבון שירות. כלומר, צריך למצוא עותק של המפתח של חשבון השירות בנתיב הבא מספריית הבית: shopping-samples/content/service-account.json
. אין צורך לקבוע את ההגדרות לדוגמה, אלא אם רוצים לנסות את הדוגמאות אחרי שמסיימים את ה-Codelab הזה.
רוצים לנסות?
עכשיו, אחרי שיש לך אסימוני אימות במקומות הנכונים, אפשר לנסות להריץ את הדוגמאות. אם משתמשים ב-Maven בשורת הפקודה, צריך להריץ את הפקודות הבאות:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
אם מופיעה הודעת שגיאה על כך שאובייקטים של הסשן לא סופקו, אסימוני האימות שמורים ועובדים כמו שצריך. אם לא, תקבלו הודעת שגיאה לגבי פרטי הכניסה שלא הצליחו לפעול ואיזה קובץ צריך לתקן.
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();
הגדרת שם של אפליקציה אינה הכרחית בלבד, אבל היא מראה איך להגדיר את האפשרויות הרצויות באמצעות האובייקט ShoppingContent.Builder
לפני קריאה ל-method 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 וניצור חשבון בדיקה במסגרת חשבון הניהול שלנו.
גישה ל-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 שמכיל את ההגדרות של החשבון החדש. ניצור חשבון בדיקה עבור 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
s; כאן תהיה רשימה שכוללת לקוח אחד – החשבון החדש שיצרנו. נאחזר את המזהה של החשבון החדש לשימוש עתידי, וגם נדפיס אותו כדי שנוכל לראות אותו כחלק מהפלט של הפתרון שלנו.
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 של חשבון הניהול ושם גם תראו את החשבון החדש.
6. יצירת חשבון משנה חדש ב-Merchant Center
בשלב הזה ניצור את חשבון המשנה ב-Merchant Center שנקשר אל חשבון AdWords שיצרנו בשלב האחרון. במקום לבקש בנפרד קישור אחרי יצירת חשבון המשנה, אנחנו יכולים לבקש את הקישור במהלך היצירה, כי המזהה של חשבון AdWords המתאים כבר נמצא ברשותנו.
ציון ההגדרות של חשבון המשנה החדש
להבדיל מ-AdWords API, כלי ההגדרה של המחלקה של המודל 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")));
כפי שצוין במבוא לשלב הזה, מכיוון שכבר יש לנו את מזהה Google Ads של החשבון המנוהל החדש, אפשר להוסיף את המזהה הזה לרשימה AdwordsLinks
עבור חשבון המשנה החדש. לאחר יצירת חשבון המשנה החדש, המערכת תבקש קישור זה באופן אוטומטי והוא יהיה זמין ב-AdWords API.
יצירת חשבון המשנה החדש
ב-Content API, אנחנו מפעילים את השיטה 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());
ה-method insert()
מחזירה אובייקט Account
שמכיל את ההגדרות של חשבון המשנה החדש. אנחנו מחליפים את האובייקט Account
המקורי כי הגרסה שהוחזרה כוללת מידע חשוב: המזהה של חשבון המשנה החדש. אנחנו מדפיסים את זה בפלט מהפתרון שלנו, כדי שנוכל להפעיל את הפתרון ולאחר מכן לאמת שחשבון המשנה החדש קיים ב-Merchant Center.
רוצים לנסות?
כמו קודם, נסו להפעיל את הפתרון. אם משתמשים ב-Maven משורת הפקודה:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
אם הכול תקין, עדיין לא יוצגו שגיאות, והפעם נציג את המזהים של חשבון Google Ads החדש וגם של החשבון החדש ב-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);
אישור הקישור
לסיום, נקרא ל-method mutateServiceLinks()
של האובייקט CustomerService כדי לבצע את הפעולה. כמו קודם, צריך להשתמש במערך פעולות של קישור שירות. הפעם, השיטה מחזירה רשימה של קישורי שירות (שעשויים להשתנות) באופן ישיר, לכן נדפיס את התוצאה של הפתרון שלנו על ידי הצגת הרשימה בלופ. כמובן שמכיוון שציינו פעולה אחת בלבד, יש לצפות רק בקישור אחד שיודפס בפלט.
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, קודם כל יצרנו את חשבון Google Ads בצורה חכמה כדי שנוכל להשתמש במידע שלו כדי לבקש את הקישור במהלך יצירת החשבון ב-Merchant Center. עם זאת, אם חשבון Merchant Center כבר קיים, תצטרכו לעדכן את ההגדרות שלו במקום זאת. כדאי לשנות קודם את הקוד כדי ליצור חשבון Merchant Center. אחר כך אפשר לחזור אחורה אחרי שיוצרים את חשבון AdWords ולעדכן את ההגדרות שלו כדי לבקש קישור.
קרדיט נוסף: מאמתים את יצירת הקישור על ידי אחזור פרטי חשבון AdWords ו-Merchant Center
בשלב זה, האפליקציה מתייחסת רק להיעדר שגיאות בקריאות ל-API כסימן להצלחה. אפשר להרחיב את הדוגמה כדי לבדוק את פרטי הקישור לחשבון Merchant Center החדש ולחשבון AdWords החדש ולראות שהקישור אכן פעיל.
הצדפה שלך בעולם
אם חשבתם על שינויים אחרים שאפשר לבצע, נסו אותם. אם אתם צריכים קוד עזר לרעיונות, אתם יכולים לבדוק את הדוגמאות של Google שופינג ואת הספרייה examples
במקור של ספריית הלקוח של Google Ads Java.