تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

يوفّر المورد 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
العنوان	قميص Google Tee الأسود	قميص Google Tee الأخضر	قبعة Google ضيقة
الوصف	قميص 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	New	New
السعر	21.99 SAR	21.99 SAR	10.99 SAR
مدى التوفّر	متوفر	متوفر	متوفر
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	ملابس وإكسسوارات > ملابس	ملابس وإكسسوارات > ملابس	ملابس وإكسسوارات > إكسسوارات ملابس > قبعات
لون	باللون الأسود	أخضر	باللون الأسود
size	L	ن	ن
age_group	للبالغين	للبالغين	للبالغين
gender	ذكر	ذكر	للجنسَين
included_destination	Shopping Actions وإعلانات Shopping	Shopping Actions وإعلانات Shopping	إجراءات التسوّق

products.insert

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

يتم تلقائيًا حذف المنتجات المستبعَدة من جميع الوجهات لأكثر من 7 أيام.

يدرج المثال المعروض "قميص Google Tee" جديد إلى المنتجات المتاحة.

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 لقميص 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 من "قميص 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 لقميص 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"
   ]
  }
 ]
}

معرّفات المنتجات

وضع الدفعة