مكالمات موارد المنتجات

يتيح مصدر products قدراً كبيراً من المرونة والتحكّم في أكثر من 60 سمة من سمات المنتجات.هناك عدد من الحقول الإلزامية التي يجب تضمينها من أجل الموافقة على عرضها على Google Shopping. هناك عدد من الحقول الاختيارية التي يمكن أن تصبح إلزامية استنادًا إلى شروط مختلفة، مثل الموقع الجغرافي ونوع المنتج وخيارات المنتج وحِزم المنتجات. لمزيد من التفاصيل حول أكثر من 60 مَعلمة اختيارية يمكن ضبطها للمنتجات، يُرجى الرجوع إلى مواصفات بيانات المنتج.

يتيح لك المرجع products insert وget وupdate وdelete منتجًا واحدًا في كل مرة، كما يتيح لك list جميع المنتجات في قاعدة بيانات Merchant Center.

يمكن استخدام المورد productstatuses للتحقّق من حالة الموافقة أو الرفض لمنتج معيّن في وجهة معيّنة. يُرجى الرجوع إلى دليل حالة المنتج للحصول على مزيد من التفاصيل حول المنتجات التي قد تواجه مشاكل في جودة البيانات وأنواع هذه المشاكل.

في أمثلة واجهة برمجة التطبيقات، نستخدم ثلاثة منتجات: قميصان من Google وقبعة من Google. ونستخدم مجموعة بسيطة من بيانات المنتجات الموضّحة في الجدول أدناه لإجراء طلبات المورد products من أجل إدراج المنتجات الفردية ومجموعات المنتجات والحصول عليها وتعديلها وإدراجها وحذفها.

ننصحك بضبط معلومات الشحن والضريبة على مستوى الحساب بدلاً من ضبطها على مستوى المنتج.

بالنسبة إلى الحسابات الفرعية المتعددة البائعين في الأسواق، يجب أن تتضمّن جميع المنتجات الحقل external_seller_id. يمكنك الاطّلاع على معرّفات المنتجات لمزيد من التفاصيل.

id online:en:US:1111111111 online:en:US:2222222222 online:en:US:3333333333
offerId 1111111111 2222222222 3333333333
title قميص Black Google Tee Google Tee Green قبّعة من القماش القطني من Google
الوصف قميص Black Google Tee قميص Google مصنوع من القطن بنسبة% 100 الحد الأقصى الكلاسيكي في Google
معرّف مجموعة السلع google_tee google_tee
رابط http://my.site.com/blacktee http://my.site.com/greentee http://my.site.com/blackhat
الشرط جديد New جديد
price 21.99 USD 21.99 USD ‫10.99 ريال سعودي
مدى التوفّر متوفر متوفر متوفر
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
رقم القطعة بحسب الشركة المصنّعة 00638NIC 00638ANG 00638ABC
العلامة التجارية Google Google Google
فئة المنتجات من Google ملابس وإكسسوارات > ملابس ملابس وإكسسوارات > ملابس ملابس وإكسسوارات > إكسسوارات الملابس > قبعات
اللون أسود أخضر أسود
الحجم L M M
age_group للبالغين للبالغين للبالغين
الجنس ذكر ذكر للجنسَين
included_destination ‫Shopping Actions و"إعلانات Shopping" ‫Shopping Actions و"إعلانات Shopping" Shopping Actions

products.insert

لإدراج منتج واحد، استخدِم عنوان URL الخاص بالطلب التالي، مع تحديد معرّف التاجر ونموذج لنص JSON. يؤدي الإدراج إلى إنشاء المنتج الجديد. إذا كانت هناك قيم للسمات channel وcontentLanguage وofferId وfeedLabel لمنتج معيّن، تعدّل هذه الطريقة الإدخال وتستبدل جميع البيانات من طلبات البيانات السابقة من واجهة برمجة التطبيقات للمنتج المعيّن.

سيتم تلقائيًا حذف المنتجات التي تم استبعادها من كل الوجهات لأكثر من 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 تضع حدًا أقصى للمشتريات لكل طلب من العميل حسب تعريف المنتج، كما أنّها متوافقة مع الخلاصات. لا يزال هذا العنصر في مرحلة الإصدار التجريبي إلى أن يصبح متوافقًا بالكامل مع واجهة برمجة التطبيقات. يمكن للتاجر إضافة أي سمة مخصّصة إضافية، ولكن لن تؤدي إلى أي معالجة معيّنة من خلال واجهات برمجة التطبيقات.

تعرض المكالمة الناجحة الرمز 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 و "مورد المنتج" في نص الاستجابة. في ما يلي نموذج لبيانات منتج تم استردادها من منتج يحمل المعرّف 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 لمنتج حالي بعنوان "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 للمنتج الحالي "Black Google Tee" باستخدام بيانات المنتج المعنيّة المقدَّمة في نص الطلب، مع ترك جميع الحقول الأخرى، بما في ذلك 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 لمنتج حالي بعنوان "Black Google Tee" باستخدام 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"
   ]
  }
 ]
}
السابق
معرّفات المنتجات
التالي
وضع الدفعة