يوفر مورد 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 | قميص Google بكمّين قصيرين أسود اللون | أخضر تي شيرت من Google | قبعة Google Twill |
الوصف | قميص Google بكمّين قصيرين أسود اللون | قميص 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 |
السعر | SAR 21.99 | SAR 21.99 | 10.99 SAR |
مدى التوفّر | متوفر | متوفر | متوفر |
imageLink | https://shop.example.com/ |
https://shop.example.com/ |
https://shop.example.com/ |
رقم GTIN | 9504000059422 | 9504000059446 | 9504000059452 |
رقم القطعة بحسب الشركة المصنّعة | 00638NIC | 00638ANG | 00638ABC |
العلامة التجارية | |||
فئة المنتجات من Google | ملابس وإكسسوارات > ملابس | ملابس وإكسسوارات > ملابس | ملابس وإكسسوارات > إكسسوارات الملابس > قبعات |
اللون | باللون الأسود | أخضر | باللون الأسود |
الحجم | L | ن | ن |
age_group | للبالغين | للبالغين | للبالغين |
الجنس | ذكر | ذكر | للجنسَين |
included_destination | Shopping Actions و"إعلانات Shopping" | Shopping Actions و"إعلانات Shopping" | إجراءات التسوّق |
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 التالي للطلب مع طريقة التصحيح، وحدِّد معرّف التاجر ومعرّف المنتج ونص 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
فقط لـ "قميص 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 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 ID مثل
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"
]
}
]
}