Merchant API הוא דרך חזקה ואינטואיטיבית יותר לנהל את נתוני המוצרים. השינוי העיקרי הוא הפרדה של נתוני המוצרים לשני משאבים נפרדים: ProductInput לשליחת הנתונים ו-Product לצפייה בגרסה הסופית המעובדת, כולל סטטוס המוצר והבעיות. המבנה החדש הזה מספק חוויה צפויה ושקופה יותר.
המדריך הזה מסביר את ההבדלים העיקריים כדי לעזור לכם להעביר את השילוב מ-Content API for Shopping. במאמר ניהול המוצרים מוסבר בפירוט איך להשתמש בתכונות החדשות.
ההבדלים העיקריים
אלה השינויים המשמעותיים ביותר בניהול מוצרים ב-Merchant API בהשוואה ל-Content API for Shopping:
משאבים ייעודיים לקלט ולנתונים מעובדים: ב-Merchant API, ניהול המוצרים מחולק לשני משאבים. אתם יכולים להשתמש במשאב
ProductInputכדי להוסיף, לעדכן ולמחוק את נתוני המוצרים שלכם. אתם יכולים להשתמש במשאבProductלקריאה בלבד כדי לראות את המוצר הסופי אחרי ש-Google מעבדת את הקלט, מחילה כללים ומשלבת נתונים ממקורות משלימים.קידוד של שמות מוצרים: אפשר להשתמש בקידוד base64url ללא ריפוד (RFC 4648 סעיף 5) גם בשדה
ProductInput.nameוגם בשדהProduct.name. אם שמות המוצרים מכילים תווים שמשמשים את Merchant API או תווים ששמורים לכתובות URL, חובה לקודד אותם. לדוגמה, צריך לקודד את שמות המוצרים אם הם מכילים את אחד מהתווים הבאים:% . + / : ~ , ( * ! ) & ? = @ # $סטטוס המוצר המשולב: השירות
productstatusesהוסר. בעיות באימות מוצרים וסטטוסים של יעדים נכללים עכשיו ישירות במשאבProductבשדהproductStatus, מה שמקל על אחזור הנתונים.עדכוני מוצרים צפויים: השיטה החדשה
productInputs.patchמשנה ישירות קלט של מוצר ספציפי. זהו שיפור משמעותי לעומת Content API for Shopping, שבו עדכונים עלולים להידרס באופן בלתי צפוי על ידי העלאות של פידים אחרים. ב-Merchant API, עדכון נשאר עד שקלט המוצר הספציפי הזה מתעדכן שוב או נמחק. עדכוני המוצרים חלים על המשאבProductInputבמקום על המשאב המעובדProduct.בחירת מקור נתונים לניהול נתונים נקי יותר: כל פעולות הכתיבה של
productInputsדורשות עכשיו פרמטר שאילתה שלdataSource, כך שברור איזה מקור נתונים אתם משנים. האפשרות הזו שימושית במיוחד אם יש לכם כמה מקורות שמספקים נתונים.מזהי משאבים חדשים: המוצרים מזוהים עכשיו באמצעות משאב RESTful
nameבמקום השדהid. הפורמט הואaccounts/{account}/products/{product}.אין אצוות בהתאמה אישית: השיטה
custombatchלא זמינה יותר. אפשר להשתמש בבקשות לא סנכרוניות או לקבץ בקשות HTTP כדי לשלוח כמה בקשות בקריאת HTTP אחת.
הנחיות לגבי מקורות נתונים במהלך ההעברה
לפני שאתם מעבירים את מקורות הנתונים, מומלץ מאוד לבחור את האסטרטגיה של מקורות הנתונים.
כדי להבטיח שההעברה תתבצע בצורה חלקה ולמנוע בעיות כמו גניבת מבצעים, כדאי לפעול לפי ההמלצות הבאות:
מילוי חוסרים במסד הנתונים: במקום להפעיל את
dataSources.listלפני כל פעולה שקשורה למוצר, מומלץ מאוד לבצע מילוי חוסרים חד-פעמי במסד הנתונים המקומי. מוסיפים שדה שםdataSourceלכל רשומת מוצר כדי שתוכלו לספק את המזהה הנכון ישירות בבקשות.איחוד ושימוש במקורות נתונים לכל תווית ושפה: באמצעות Merchant API אפשר ליצור מקור נתונים בלי לציין תווית ושפה, וכך להוסיף מוצרים עם כל תווית של מקור נתונים ושפה. כדאי להשתמש במקור נתונים אחד לכל תווית ושפה.
הגנה על המוצרים: אם אתם משתמשים בכללים של מקורות נתונים, צריך להפעיל את
products.getכדי למצוא את ה-dataSourceהמדויק שמשויך למוצר לפני שמעדכנים או מוחקים אותו. כך אפשר לוודא שאתם משנים את המקור הרצוי ומונעים גניבה מקרית של מבצעים.
בקשות
בקטע הזה אנחנו משווים בין הפורמטים של הבקשות ב-Content API for Shopping וב-Merchant API.
| תיאור הבקשה | Content API for Shopping | Merchant API |
|---|---|---|
| קבלת מוצר | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product} |
| תעשה לי רשימת מוצרים | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products |
| הוסף מוצר | POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products |
POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert |
| עדכון מוצר | PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput} |
| מחיקת מוצר | DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} |
DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput} |
| קבלת סטטוס המוצר | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId} |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product} |
| רשימת סטטוסים של מוצרים | GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses |
GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products |
| שליחת כמה בקשות באצווה | POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch |
שימוש בבקשות לא סנכרוניות או בקיבוץ בקשות HTTP |
מזהים
הפורמט של מזהי המוצרים ב-Merchant API השתנה לשם משאב REST סטנדרטי.
| תיאור המזהה | Content API for Shopping | Merchant API |
|---|---|---|
| מזהה מוצר | מחרוזת שמורכבת ממקטעים שמופרדים בנקודתיים (:).פורמט: channel:contentLanguage:targetCountry:offerId או channel:contentLanguage:feedLabel:offerId.דוגמה: online:en:US:sku123 |
מחרוזת name של משאב REST.פורמט: accounts/{account}/products/{product} כאשר {product} הוא contentLanguage~feedLabel~offerId.דוגמה: accounts/12345/products/en~US~sku123.קידוד: מומלץ להשתמש בקידוד base64url ללא ריפוד, וחובה להשתמש בו במקרה של מזהי מוצרים שמכילים תווים שמשמשים את Merchant API או תווים ששמורים לכתובות URL. |
Methods
בטבלה הזו מוצגות השיטות של Content API for Shopping והשיטות המקבילות ב-Merchant API.
| שיטת Content API for Shopping | ה-Method ב-Merchant API | זמינות והערות |
|---|---|---|
products.get |
products.get |
אחזור המוצר הסופי שעבר עיבוד. |
products.list |
products.list |
רשימה של מוצרים סופיים שעברו עיבוד. |
products.insert |
productInputs.insert |
הוספת קלט של מוצר. נדרש dataSource. |
products.update |
productInputs.patch |
ההתנהגות שונה באופן משמעותי. הוא מעדכן קלט של מוצר ספציפי והוא קבוע. |
products.delete |
productInputs.delete |
מחיקת קלט של מוצר ספציפי. נדרש dataSource. |
products.custombatch |
לא זמין | משתמשים בבקשות לא סנכרוניות או מקבצים בקשות HTTP. |
productstatuses.get |
products.get |
השירות productstatuses יוסר. פרטי הסטטוס הם עכשיו חלק מהמשאב Product. |
productstatuses.list |
products.list |
השירות productstatuses יוסר. פרטי הסטטוס הם עכשיו חלק מהמשאב Product. |
productstatuses.custombatch |
לא זמין | משתמשים בבקשות לא סנכרוניות או בקיבוץ בקשות HTTP. |
שינויים מפורטים בשדות
בטבלה הזו מודגשים שדות חשובים שהשתנו, נוספו או הוסרו ב-Merchant API.
| Content API for Shopping | Merchant API | תיאור |
|---|---|---|
id |
name |
המזהה הראשי של מוצר הוא עכשיו המשאב name ב-REST. מומלץ להשתמש בקידוד base64url ללא ריפוד, וחובה להשתמש בו אם שמות המוצרים מכילים תווים שמשמשים את Merchant API או תווים ששמורים לכתובות URL. |
מאפיינים ברמה העליונה של מפרט נתוני המוצרים (למשל, title, price, link) |
אובייקט productAttributes |
מאפייני מוצר כמו title, price ו-link הם כבר לא שדות ברמה העליונה. עכשיו הם מקובצים באובייקט productAttributes במשאבים Product ו-ProductInput. כך מבנה המשאבים נקי ומאורגן יותר. |
targetCountry |
feedLabel |
שם המשאב משתמש עכשיו ב-feedLabel במקום ב-targetCountry כדי להתאים לפונקציונליות של Merchant Center. |
feedId |
dataSource (פרמטר של שאילתה) |
שם של dataSource הוא עכשיו פרמטר חובה של שאילתה לכל שיטות הכתיבה של productInputs (insert, update, delete). |
channel |
לא זמין. צריך להשתמש בערך legacy_local למוצרים שנמכרים בחנויות מקומיות בלבד. |
השדה channel לא קיים יותר ב-Merchant API. במוצרים עם ערוץ LOCAL ב-Content API for Shopping, צריך להגדיר את השדה legacy_local כ-true. |
| לא זמין | versionNumber |
שדה אופציונלי חדש ב-ProductInput שמאפשר למנוע הוספה של פריטים לא מסודרים למקורות נתונים ראשיים. |
שדות מסוג string עם קבוצת ערכים מוגדרת |
שדות מסוג enum עם קבוצת ערכים מוגדרת |
שדות בתוך מאפייני מוצרים עם קבוצת ערכים מוגדרת (לדוגמה excluded_destinations, availability) הם עכשיו מסוג enum. |
gtin |
productAttributes.gtins |
השתנה ממחרוזת יחידה (gtin) למחרוזת חוזרת (gtins). |
sizes |
productAttributes.size |
השתנה ממחרוזת חוזרת (sizes) למחרוזת יחידה (size). |
sizeType, additionalSizeType |
productAttributes.sizeTypes |
השדות sizeType ו-additionalSizeType הוחלפו בערך enum חוזר (sizeTypes) מסוג SizeType שמקבל עד שני ערכים (לדוגמה, ["PETITE", "MATERNITY"]). |