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

يوفر مورد 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/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 ن ن
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"
   ]
  }
 ]
}
السابق
معرّفات المنتجات
التالي
وضع الدفعة