קריאות משאבים למוצרים

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

המשאב products מאפשר insert, get, update ו-delete מוצר אחד בכל פעם ו-list את כל המוצרים במסד הנתונים של Merchant Center.

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

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

מומלץ להגדיר את פרטי המשלוח והמס ברמת החשבון ולא ברמת המוצר.

בחשבונות משנה של זירות מסחר שמוגדרים בהם כמה אתרי מכירה, כל המוצרים צריכים לכלול את השדה external_seller_id. לפרטים נוספים, ראו מזהי מוצרים.

id online:en:US:1111111111 online:en:US:2222222222 online:en:US:3333333333
offerId 1111111111 2222222222 3333333333
title חולצת Google השחורה ירוק טי של Google Google Caps Cap
תיאור חולצת Google השחורה טישרט של Google מ-100% כותנה כובע קלאסי של Google
מזהה קבוצת פריטים google_tee google_tee
קישור http://my.site.com/blacktee http://my.site.com/greentee http://my.site.com/blackhat
מצב חדש חדש חדש
price 99.90 ILS 99.90 ILS 49.90 ILS
זמינות במלאי במלאי במלאי
imageLink https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
gtin [מספר_פריט_מסחרי_גלובלי] 9504000059422 9504000059446 9504000059452
mpn [קוד_MPN] 00638NIC 00638ANG 00638ABC
brand Google Google Google
קטגוריית מוצרים ב-Google לבוש ואביזרים > ביגוד לבוש ואביזרים > ביגוד לבוש ואביזרים > אביזרי הלבשה > כובעים
color [צבע] שחור green שחור
size L M M
age_group למבוגרים למבוגרים למבוגרים
gender זכר זכר יוניסקס
included_destination Shopping Actions, מודעות שופינג Shopping Actions, מודעות שופינג Shopping Actions

products.insert

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

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

בדוגמה שמוצגת כאן מוסיפה 'חולצת Google שחורה' חדשה למוצרים הזמינים.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

דוגמה לקריאה לגוף הבקשה עבור products.insert:

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

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

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

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

קריאה בוצעה בהצלחה מחזירה קוד HTTP 200 וגוף תשובה שמכיל את משאב המוצר שנוסף, כשרק id, offerId, contentLanguage, feedLabel ו-channel מאוכלסים:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

כדי לקבל מידע על מוצר ספציפי במסד הנתונים של Merchant Center, משתמשים ב-products.get. יכול להיות שיעברו כמה דקות עד שמוצר חדש שנוסף יהיה זמין בשיחה הזו.

משתמשים בכתובת ה-URL ובפרמטרים הבאים של בקשת HTTP, במזהה המוכר ובמזהה המוצר (פורמט מזהה REST) של המוצר שרוצים לקבל:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

קריאה בוצעה בהצלחה מחזירה HTTP 200 ואת 'product resource' בגוף התשובה. לפניכם דוגמה לנתוני מוצרים שאוחזרו ממוצר עם המזהה online:en:US:1111111111:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

כדי לעדכן מוצר בודד, צריך להשתמש בכתובת ה-URL של הבקשה הבאה בשיטת PATCH, ולציין את מספר המוכר, מזהה המוצר וגוף JSON שמכיל את הנתונים שרוצים לעדכן לגבי המוצר. בניגוד ל-products.insert, כדי להשתמש בכל השדות הרלוונטיים צריך לציין את כל השדות הרלוונטיים, ב-products.update רק צריך לציין את השדות שרוצים לשנות.

כדי להוסיף או לשנות מאפיין, צריך לציין את השדה עם הערך החדש בגוף ה-JSON. בדוגמה המוצגת, הערכים title ו-description של 'חולצת Google שחורה' הקיימים יתעדכנו בנתוני המוצר שצוינו בגוף הבקשה, כך שכל שאר השדות ללא שינוי.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

דוגמה לקריאה לגוף הבקשה עבור products.update:

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

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

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

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

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

בדוגמה שמוצגת למטה מתבצע עדכון רק description ו-availability של 'חולצת Google שחורה' קיימת, בהתאם לנתוני המוצר המתאימים שמופיעים בגוף הבקשה, כך שכל שאר השדות, כולל title, יישארו ללא שינוי.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

דוגמה לקריאה לגוף הבקשה עבור products.update:

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

אם צוין שדה ברשימה updateMask אבל לא בגוף הבקשה, השדה הזה יימחק מהמשאב Product, אם הוא קיים.

בדוגמה הבאה נשתמש ב-updateMask כדי להסיר את הערך בשדה salePrice.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

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

כדי להשתמש ב-updateMask בתוך בקשת products.custombatch, צריך לציין את updateMask בגוף הבקשה.

הדוגמה המוצגת תעדכן את הערכים price ו-availability של 'חולצת Google שחורה' קיימת באמצעות products.custombatch עם נתוני המוצר שסופקו ברשומה בכמות גדולה, כך שכל שאר השדות, כולל title ו-description, לא נקלטו.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

כדי למחוק מוצר בודד, משתמשים ב-products.delete עם כתובת ה-URL לדוגמה של בקשת ה-HTTP, במזהה המוכר ובמזהה המוצר (בפורמט של מזהה REST כמו online:en:US:1111111111) של המוצר שרוצים למחוק:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

תשובה מוצלחת תחזיר HTTP Status 204 ללא גוף תשובה.

products.list

products.list מפרט את כל המוצרים שיש למוכר במסד הנתונים של Merchant Center. משתמשים בכתובת ה-URL הבאה של הבקשה:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

קריאה בוצעה בהצלחה מחזירה נתוני HTTP 200 ו-JSON למוצרים שבמפתח 'משאבים'.

מוחזרים שלושת המוצרים הבאים:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}
הקודם
מזהי המוצרים
הבא
מצב אצווה