העברת מוצרים

‫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 שעבר עיבוד.

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

• מזהי משאבים חדשים: מוצרים מזוהים עכשיו על ידי משאב RESTful‏ name במקום השדה id. הפורמט הוא accounts/{account}/products/{product}.

• ללא קבוצות מותאמות אישית: השיטה custombatch לא זמינה יותר. אפשר להשתמש בבקשות אסינכרוניות או בקיבוץ באצווה של HTTP כדי לשלוח כמה בקשות בקריאת HTTP אחת.

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

הנחיות לגבי מקורות נתונים במהלך ההעברה

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

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

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

• מילוי חוזר של מסד הנתונים: במקום לקרוא ל-dataSources.list לפני כל פעולת מוצר, מומלץ מאוד לבצע מילוי חוזר חד-פעמי של מסד הנתונים המקומי. מוסיפים שדה dataSource שם לכל רשומת מוצר כדי שתוכלו לספק את המזהה הנכון ישירות בבקשות.

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

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

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

בקשות

בקטע הזה מוצגות השוואות בין פורמטים של בקשות ב-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.

הערה: השדה channel לא מופיע יותר ב-Merchant API. במקום זאת, במוצרים עם ערוץ LOCAL ב-Content API for Shopping צריך להגדיר את השדה legacy_local לערך true.

Methods

בטבלה הזו מוצגות השיטות של Content API for Shopping והשיטות המקבילות שלהן ב-Merchant API.

שיטה של Content API for Shopping	שיטת 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	המזהה הראשי של מוצר הוא עכשיו משאב ה-REST‏ name. מומלץ להשתמש בקידוד base64url ללא ריפוד, והוא חובה במקרה של שמות מוצרים שמכילים תווים שמשמשים את Merchant API או תווים שמורים בכתובת URL.
מאפיינים של מפרט נתוני מוצרים ברמה העליונה (לדוגמה, title, ‏ price, ‏ link)	אובייקט productAttributes	מאפייני מוצר כמו title, price ו-link כבר לא מופיעים כשדות ברמה העליונה. הם מקובצים עכשיו באובייקט productAttributes במשאבים Product ו-ProductInput. כך מתקבל מבנה משאבים נקי ומאורגן יותר.
targetCountry	feedLabel	שם המשאב כולל עכשיו את התו feedLabel במקום targetCountry, בהתאם לפונקציונליות של Merchant Center.
feedId	dataSource (פרמטר של שאילתה)	הפרמטר dataSource name הוא עכשיו פרמטר שאילתה נדרש לכל שיטות הכתיבה של 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.