تماس با منابع محصولات

منبع products انعطاف‌پذیری و کنترل زیادی را بر روی بیش از ۶۰ ویژگی محصول فراهم می‌کند. تعدادی فیلد اجباری وجود دارد که برای تأیید نمایش در Google Shopping باید درج شوند. تعدادی فیلد اختیاری نیز وجود دارد که می‌توانند بر اساس شرایط مختلف مانند مکان، نوع محصول، انواع محصول و بسته‌های محصول، اجباری شوند. برای جزئیات بیشتر در مورد بیش از ۶۰ پارامتر اختیاری که می‌توان برای محصولات پیکربندی کرد، به مشخصات داده‌های محصول مراجعه کنید.

منبع products به شما امکان می‌دهد تا یک محصول را در یک زمان insert ، get ، update و delete و تمام محصولات موجود در پایگاه داده مرکز فروش list .

منبع productstatuses می‌تواند برای بررسی وضعیت تأیید یا عدم تأیید یک محصول خاص برای یک مقصد مورد استفاده قرار گیرد. برای جزئیات بیشتر در مورد اینکه کدام محصولات ممکن است مشکلات کیفیت داده داشته باشند و این مشکلات چه هستند، به راهنمای وضعیت محصول مراجعه کنید.

در مثال‌های API خود، از سه محصول استفاده می‌کنیم: دو تی‌شرت گوگل و یک کلاه گوگل. ما از حداقل مجموعه‌ای از داده‌های محصول که در جدول زیر نشان داده شده است، برای فراخوانی منابع products جهت درج، دریافت، به‌روزرسانی، فهرست‌بندی و حذف محصولات و دسته‌های محصولات استفاده می‌کنیم.

توصیه می‌کنیم اطلاعات ارسال و مالیات به جای سطح محصول، در سطح حساب کاربری پیکربندی شوند.

برای حساب‌های فرعی چند فروشنده‌ای Marketplaces ، همه محصولات باید شامل فیلد external_seller_id باشند. برای جزئیات بیشتر به شناسه‌های محصول مراجعه کنید.

شناسه	آنلاین:en:US:1111111111	آنلاین:en:US:2222222222	آنلاین:en:US:333333333
شناسه پیشنهاد	۱۱۱۱۱۱۱۱۱۱	۲۲۲۲۲۲۲۲۲۲	۳۳۳۳۳۳۳۳۳۳
عنوان	تی‌شرت مشکی گوگل	تی‌شرت گوگل سبز	کلاه بافتنی گوگل
توضیحات	تی‌شرت مشکی گوگل	تی‌شرت گوگل ۱۰۰٪ پنبه‌ای	کلاه کلاسیک گوگل
شناسه گروه کالا	گوگل تی	گوگل تی
پیوند	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
وضعیت	جدید	جدید	جدید
قیمت	۲۱.۹۹ دلار آمریکا	۲۱.۹۹ دلار آمریکا	۱۰.۹۹ دلار آمریکا
در دسترس بودن	موجود در انبار	موجود در انبار	موجود در انبار
لینک تصویر	https://shop.example.com/ فروشگاه/۲۰۱۶۰۵۱۲۵۱۲/دارایی‌ها/اقلام/تصاویر/ GGOEGXXX1100.jpg	https://shop.example.com/ فروشگاه/۲۰۱۶۰۵۱۲۵۱۲/دارایی‌ها/اقلام/تصاویر/ GGOEGXXX0906.jpg	https://shop.example.com/ فروشگاه/۲۰۱۶۰۵۱۲۵۱۲/دارایی‌ها/اقلام/تصاویر/ GGOEGHPB071610.jpg
جی تی ان	۹۵۰۴۰۰۰۵۹۴۲۲	۹۵۰۴۰۰۰۵۹۴۴۶	۹۵۰۴۰۰۰۵۹۴۵۲
ام پی ان	۰۰۶۳۸NIC	۰۰۶۳۸ANG	۰۰۶۳۸ای‌بی‌سی
برند	گوگل	گوگل	گوگل
دسته بندی محصولات گوگل	پوشاک و لوازم جانبی > پوشاک	پوشاک و لوازم جانبی > پوشاک	پوشاک و اکسسوری > اکسسوری‌های پوشاک > کلاه
رنگ	سیاه	سبز	سیاه
اندازه	ل	م	م
گروه_سنی	بزرگسال	بزرگسال	بزرگسال
جنسیت	مرد	مرد	یونی‌سکس
شامل_مقصد	اقدامات خرید، تبلیغات خرید	اقدامات خرید، تبلیغات خرید	اقدامات خرید

محصولات.درج

برای درج یک محصول واحد، از URL درخواست زیر استفاده کنید که شناسه فروشنده و یک بدنه JSON نمونه را مشخص می‌کند. یک درج، محصول جدید را ایجاد می‌کند. اگر مقادیری برای ویژگی‌های channel ، contentLanguage ، offerId و feedLabel برای یک محصول مشخص وجود داشته باشد، این متد آن ورودی را به‌روزرسانی کرده و تمام داده‌های مربوط به فراخوانی‌های API قبلی برای محصول مشخص شده را جایگزین می‌کند.

محصولاتی که بیش از ۷ روز از همه مقاصد حذف شوند، به‌طور خودکار حذف می‌شوند.

مثال نشان داده شده یک «تی‌شرت مشکی گوگل» جدید را به محصولات موجود اضافه می‌کند.

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 استفاده کنید. ممکن است چند دقیقه طول بکشد تا یک محصول تازه درج شده از طریق این فراخوانی در دسترس قرار گیرد.

از آدرس اینترنتی درخواست 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"
 ]
}

محصولات.به‌روزرسانی

برای به‌روزرسانی یک محصول واحد، از URL درخواست زیر با متد PATCH استفاده کنید، که شامل شناسه فروشنده، شناسه محصول و یک بدنه JSON حاوی داده‌هایی است که می‌خواهید برای محصول به‌روزرسانی کنید. برخلاف products.insert که نیاز به ارائه همه فیلدهای مربوطه دارد، products.update فقط از شما می‌خواهد فیلدهایی را که می‌خواهید تغییر دهید مشخص کنید.

برای افزودن یا تغییر یک ویژگی، فیلد مورد نظر را با مقدار جدید در بدنه JSON مشخص کنید. مثال نشان داده شده title و description یک "Black Google Tee" موجود را با داده‌های محصول ارائه شده در بدنه درخواست به‌روزرسانی می‌کند و سایر فیلدها را دست نخورده باقی می‌گذارد.

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 یک «تی‌شرت گوگل مشکی» موجود را با داده‌های محصول مربوطه که در متن درخواست ارائه شده است، به‌روزرسانی می‌کند و سایر فیلدها از جمله 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 یک «تی‌شرت مشکی گوگل» موجود را با استفاده از 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 به همراه نمونه آدرس اینترنتی درخواست HTTP، شناسه فروشنده خود و شناسه محصول (در قالب شناسه REST مانند online:en:US:1111111111 ) برای محصولی که می‌خواهید حذف کنید، استفاده کنید:

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

یک پاسخ موفق، HTTP Status 204 را بدون هیچ بدنه پاسخی برمی‌گرداند.

لیست محصولات

products.list تمام محصولاتی را که یک فروشنده در پایگاه داده مرکز فروشنده دارد، فهرست می‌کند. از آدرس درخواست زیر استفاده کنید:

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

یک فراخوانی موفق، داده‌های HTTP 200 و JSON را برای محصولات موجود در کلید "resources" برمی‌گرداند.

سه نمونه محصول زیر برگردانده می‌شوند:

{
 "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"
   ]
  }
 ]
}