نقل المنتجات

توفّر Merchant API طريقة أكثر فعالية وسهولة لإدارة بيانات منتجاتك. التغيير الرئيسي هو فصل بيانات المنتجات إلى مرجعَين مختلفَين: ProductInput لإرسال بياناتك وProduct لعرض النسخة النهائية المعالَجة التي تتضمّن حالة المنتج والمشاكل. ويوفّر هذا الهيكل الجديد تجربة أكثر قابلية للتوقّع وشفافية.

يشرح لك هذا الدليل الاختلافات الرئيسية لمساعدتك في نقل عملية الدمج من Content API for Shopping. للحصول على دليل تفصيلي حول استخدام الميزات الجديدة، يُرجى الاطّلاع على مقالة إدارة منتجاتك.

الاختلافات الرئيسية

في ما يلي أهم التغييرات في طريقة إدارة المنتجات في Merchant API مقارنةً بـ Content API for Shopping:

• مراجع مخصّصة للبيانات المدخلة والمعالَجة: يقسّم Merchant API إدارة المنتجات إلى مرجعَين. يمكنك استخدام مورد ProductInput لإدراج بيانات منتجاتك وتعديلها وحذفها. يمكنك استخدام مورد Product للقراءة فقط للاطّلاع على المنتج النهائي بعد أن تعالج Google المدخلات وتطبّق القواعد وتدمج البيانات من مصادر تكميلية.

• الترميز الخاص بأسماء المنتجات: يمكنك استخدام ترميز unpadded base64url (القسم 5 من RFC 4648) لكل من الحقلين ProductInput.name وProduct.name. في حال كانت أسماء المنتجات تتضمّن أحرفًا تستخدمها Merchant API أو أحرفًا محجوزة في عناوين URL، يكون التشفير إلزاميًا. على سبيل المثال، عليك ترميز أسماء المنتجات إذا كانت تحتوي على أي من الأحرف التالية:

  % . + / : ~ , ( * ! ) & ? = @ # $
  

• حالة المنتج المدمج: تتم إزالة خدمة productstatuses. تمّت الآن إضافة مشاكل التحقّق من صحة المنتجات وحالات الوجهات مباشرةً إلى مورد Product ضمن الحقل productStatus، ما يسهّل عملية استرداد البيانات.

• تعديلات متوقّعة على المنتجات: تعدّل الطريقة الجديدة productInputs.patch إدخال منتج معيّن مباشرةً. ويُعدّ ذلك تحسّنًا كبيرًا مقارنةً بواجهة Content API for Shopping، حيث كان من الممكن أن يتم بشكل غير متوقّع استبدال التعديلات بعمليات تحميل أخرى للخلاصة. في Merchant API، يبقى التعديل ساريًا إلى أن يتم تعديل بيانات المنتج المحدّد مرة أخرى أو حذفها. يتم تطبيق تعديلات المنتجات على ProductInput الموارد بدلاً من Product الموارد المعالَجة.

• اختيار مصدر البيانات لإدارة البيانات بشكل أكثر فعالية: تتطلّب جميع عمليات الكتابة productInputsالآن مَعلمة طلب بحث dataSource، ما يوضّح مصدر البيانات الذي يتم تعديله. ويكون ذلك مفيدًا بشكل خاص إذا كان لديك مصادر متعدّدة تقدّم البيانات.

• معرّفات الموارد الجديدة: يتم الآن تحديد المنتجات من خلال مورد name متوافق مع REST بدلاً من الحقل id. التنسيق هو accounts/{account}/products/{product}.

• ما مِن دفعات مخصّصة: لم تعُد طريقة الدفع custombatch متاحة. يمكنك استخدام الطلبات غير المتزامنة أو تجميع طلبات HTTP لإرسال طلبات متعددة في طلب HTTP واحد.

ملاحظة: يمكنك تحسين معدّل النقل باستخدام مجموعات القنوات: اضبط مجموعة قنوات لتحقيق أقصى معدّل نقل للعمليات المجمّعة. يؤدي ذلك إلى تجاوز الحدّ المعتاد البالغ 100 بث لقناة gRPC واحدة من خلال إدارة اتصالات أساسية متعدّدة. لمزيد من المعلومات، اطّلِع على إعادة هيكلة الرمز البرمجي للطلبات المتزامنة: تحسين سرعة معالجة البيانات باستخدام مجموعات القنوات

.

إرشادات مصدر البيانات أثناء عملية النقل

المصطلح الأساسي: يحدث "اختطاف العروض" عندما يتم إدراج منتج محدّد من خلال مفتاحه الفريد (language وfeedlabel وofferID) في مصدر بيانات أساسي مختلف عن المصدر الذي ينتمي إليه. يؤدي ذلك إلى حذف المنتج من المصدر القديم ونقله إلى المصدر الجديد، حيث قد تنطبق قواعد مختلفة لمصدر البيانات وإعدادات الملكية. مع أنّ عملية "السرقة" يمكن استخدامها عمدًا لإعادة ترتيب المنتجات، إلا أنّها قد تحدث عن طريق الخطأ إذا تم تقديم dataSource غير صحيح أثناء الإدراج.

قبل نقل مصادر البيانات، ننصحك بشدة باختيار استراتيجية مصدر البيانات.

لضمان عملية نقل سلسة وتجنُّب مشاكل مثل سرقة العروض، اتّبِع التوصيات التالية:

• تعبئة قاعدة البيانات: بدلاً من طلب dataSources.list قبل كل عملية منتج، ننصحك بشدة بتعبئة قاعدة البيانات المحلية لمرة واحدة. أضِف حقل اسم dataSource إلى كل سجلّ منتج حتى تتمكّن من تقديم المعرّف الصحيح مباشرةً في طلباتك.

• دمج مصادر البيانات واستخدامها لأي تصنيف مصدر بيانات ولغة: تتيح Merchant API إنشاء مصدر بيانات بدون تحديد تصنيف مصدر البيانات واللغة، وبالتالي تسمح بإدراج المنتجات بأي تصنيف مصدر بيانات ولغة. ننصحك باستخدام مصدر بيانات واحد لأي تصنيف ولغة.

• حماية منتجاتك: إذا كنت تستخدم قواعد مصدر البيانات، استدعِ الدالة products.get للعثور على dataSource المرتبط بمنتج معيّن قبل تعديله أو حذفه. يضمن ذلك تعديل المصدر المقصود ويمنع سرقة العروض الترويجية عن طريق الخطأ.

ملاحظة: احرص على استخدام offerId نفسه للمنتج نفسه عند طلب بيانات من Merchant API كما فعلت مع Content API for Shopping لتجنُّب فقدان سجلّ منتجاتك. يمكنك أيضًا الاطّلاع على قسم المعرّفات في هذه الصفحة.

الطلبات

يقارن هذا القسم بين تنسيقات الطلبات في Content API for Shopping وMerchant API.

وصف الطلب	واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API
الحصول على منتج	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
عرض المنتجات	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
إدراج منتج	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
تعديل منتج	PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
حذف منتج	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
الحصول على حالة المنتج	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
قائمة حالات المنتجات	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
تجميع طلبات متعددة في دفعة واحدة	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	استخدام الطلبات غير المتزامنة أو تجميع طلبات HTTP

المعرّفات

تم تغيير تنسيق معرّفات المنتجات في Merchant API إلى اسم مرجع REST عادي.

وصف المعرّف	واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API
معرّف المنتج	سلسلة تتألف من أجزاء مفصولة بنقطتين رأسيتين (:). التنسيق: channel:contentLanguage:targetCountry:offerId أو channel:contentLanguage:feedLabel:offerId. مثال: online:en:US:sku123	سلسلة name لمورد REST التنسيق: accounts/{account}/products/{product} حيث {product} هو contentLanguage~feedLabel~offerId. مثال: accounts/12345/products/en~US~sku123. الترميز: يُنصح باستخدام ترميز base64url غير المضمّن وهو إلزامي في حال كانت أرقام تعريف المنتجات تحتوي على أحرف تستخدمها Merchant API أو أحرف محجوزة في عناوين URL.

ملاحظة: لم يعُد الحقل channel متوفّرًا في Merchant API. بالنسبة إلى المنتجات التي تتضمّن القناة LOCAL في Content API for Shopping، يجب بدلاً من ذلك ضبط الحقل legacy_local على القيمة "صحيح".

الطُرق

يعرض هذا الجدول طرق Content API for Shopping وما يعادلها في Merchant API.

طريقة Content API for Shopping	طريقة Merchant API	التوفّر والملاحظات
products.get	products.get	تعرض هذه السمة المنتج النهائي الذي تمت معالجته.
products.list	products.list	تعرض هذه السمة المنتجات النهائية التي تمت معالجتها.
products.insert	productInputs.insert	تُدرج هذه السمة حقل إدخال خاصًا بالمنتج. يتطلب هذا الإجراء الاشتراك في dataSource.
products.update	productInputs.patch	ويختلف السلوك بشكل كبير. يعدّل هذا النوع من الحقول إدخال منتج معيّن ويكون ثابتًا.
products.delete	productInputs.delete	تحذف هذه الطريقة إدخال منتج معيّنًا. يتطلب هذا الإجراء الاشتراك في dataSource.
products.custombatch	غير متوفر	استخدِم الطلبات غير المتزامنة أو تجميع طلبات HTTP.
productstatuses.get	products.get	تتم إزالة الخدمة productstatuses. أصبحت معلومات الحالة الآن جزءًا من مورد Product.
productstatuses.list	products.list	تتم إزالة الخدمة productstatuses. أصبحت معلومات الحالة الآن جزءًا من مورد Product.
productstatuses.custombatch	غير متوفر	استخدِم الطلبات غير المتزامنة أو تجميع طلبات HTTP.

التغييرات التفصيلية في الحقول

يسلّط هذا الجدول الضوء على الحقول المهمة التي تم تغييرها أو إضافتها أو إزالتها في Merchant API.

واجهة برمجة تطبيقات المحتوى في Shopping	Merchant API	الوصف
id	name	المعرّف الأساسي للمنتج هو الآن مورد REST name. يُنصح باستخدام ترميز base64url غير المضمّن وهو إلزامي في حال كانت أسماء المنتجات تحتوي على أحرف تستخدمها Merchant API أو أحرف محجوزة في عناوين URL.
سمات مواصفات بيانات المنتج على المستوى الأعلى (مثل title وprice وlink)	العنصر productAttributes	لم تعُد سمات المنتج، مثل title وprice وlink، حقولاً على المستوى الأعلى. يتم الآن تجميعها ضمن الكائن productAttributes في كل من الموردَين Product وProductInput. يوفّر ذلك بنية موارد أكثر وضوحًا وتنظيمًا.
targetCountry	feedLabel	يستخدم اسم المرجع الآن feedLabel بدلاً من targetCountry ليتوافق مع وظائف Merchant Center.
feedId	‫dataSource (مَعلمة طلب البحث)	أصبح اسم dataSource الآن مَعلمة طلب بحث مطلوبة لجميع طرق الكتابة في productInputs (insert وupdate وdelete).
channel	هذه الميزة غير متوفّرة. استخدِم القيمة legacy_local للمنتجات المتوفّرة في المتجر فقط.	لم يعُد الحقل channel متوفّرًا في Merchant API. بالنسبة إلى المنتجات التي تتضمّن القناة LOCAL في Content API for Shopping، يجب بدلاً من ذلك ضبط الحقل legacy_local على "صحيح".
غير متوفر	versionNumber	حقل اختياري جديد في ProductInput يمكن استخدامه لمنع عمليات الإدراج غير المنظَّمة في مصادر البيانات الأساسية.
حقول من النوع string تتضمّن مجموعة محدّدة من القيم	حقول من النوع enum تتضمّن مجموعة محدّدة من القيم	أصبحت الحقول ضمن سمات المنتجات التي تتضمّن مجموعة محدّدة من القيم (مثل excluded_destinations وavailability) من النوع enum.