نقل البيانات من الإصدار التجريبي 1 إلى الإصدار 1

يساعدك هذا الدليل في نقل بياناتك من Merchant API v1beta إلى v1، وهو الإصدار الأول من واجهة برمجة التطبيقات المتاحة للجميع. يقدّم الإصدار 1 عدة تعديلات وتغييرات قليلة قد تتطلّب تعديل الرموز البرمجية. تم تصميم هذه التغييرات لتبسيط واجهة برمجة التطبيقات وتحسين إدارة حسابك على Merchant Center.

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

في ما يلي أهم التغييرات التي يجب معرفتها عند نقل البيانات من v1beta إلى v1:

• التسجيل لمرة واحدة لمطوّر واحد على الأقل من مطوّري واجهة برمجة التطبيقات لاستخدام Merchant API: عليك استدعاء طريقة registerGcp (مرة واحدة فقط لكل مشروع على Google Cloud مستخدَم للمصادقة) لتقديم تفاصيل الاتصال بك، ما يتيح لك استخدام واجهة برمجة التطبيقات وتلقّي آخر الأخبار والإعلانات المتعلقة بـ Merchant API. لن تتمكّن من استخدام أي v1 أو v1alpha واجهة برمجة تطبيقات إلى أن تكتمل هذه الخطوة. لمزيد من المعلومات حول عملية التسجيل، يُرجى الاطّلاع على مقالة التسجيل.

• ترميز اسم المنتج: يتيح الحقلان ProductInput.name و Product.name الحقلان ترميز base64url بدون إضافة أحرف تكميلية (القسم 5 من RFC 4648). اتّبِع الإرشادات التالية:

  • قبل الترميز، يجب أن تتوافق السلسلة مع التنسيق contentLanguage~feedLabel~offerId.

  • يكون الترميز إلزاميًا إذا كان اسم منتجك يحتوي على أحرف مستخدَمة في Merchant API أو أحرف محجوزة في عناوين URL، مثل:

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

  • إذا كان اسم منتجك يتّبع التنسيق contentLanguage~feedLabel~offerId ولايحتوي على أي أحرف مستخدَمة في Merchant API أو أحرف محجوزة في عناوين URL، يمكنك استخدام التنسيق العادي بدون ترميز.

  • لضمان تحليل متّسق وصحيح، ننصحك باستخدام ترميز base64url بدون إضافة أحرف تكميلية لجميع أسماء المنتجات.

• إزالة المعلومات الضريبية على مستوى المنتج: تمت إزالة الحقلَين taxes وtaxCategory.

• تغيير اسم Product.attributes: تم تغيير اسم الحقل Product.attributes إلى Product.productAttributes.

• إزالة المعلومات الضريبية على مستوى المنتج: تمت إزالة الحقلَين taxes وtaxCategory من العنصر Product.productAttributes. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة المساعدة في Google Merchant Center حول الضرائب.

• تغييرات على حقل GTIN: تم تغيير اسم الحقل gtin في العنصر Product.productAttributes إلى gtins ليعكس بشكل أفضل أنّه يمكن أن يحتوي على قيم متعدّدة. أصبح الحقل gtin في العنصر OrderTrackingSignals.lineItemDetails الآن array وتم تغيير اسمه إلى gtins أيضًا.

• إزالة حقل القناة: تمت إزالة الحقل channel من المنتجات والبيانات المُدخَلة للمنتجات ومصادر البيانات. تمت إضافة حقل منطقي جديد، وهو legacyLocal، لتحديد المنتجات التي تُباع حصريًا في المتاجر الفعلية بوضوح. ملاحظة: الحقل legacyLocal هو حقل مساعد للمساعدة في عملية نقل البيانات وسيتم إيقافه نهائيًا في النهاية بعد أن يصبح من الممكن استهداف طرق التسويق على الإنترنت وفي المتاجر المحلية بشكل كامل باستخدام مصدر منتج واحد. لمزيد من المعلومات، يُرجى الاطّلاع على الجدول في القسم التالي.

• حقول جديدة لسمات المنتجات المتوفرة على مستوى منطقة معيّنة وفي المتجر:

  • يتم الآن تضمين جميع RegionalInventory الحقول باستثناء name وaccount وregion ضمن عنصر جديد يُسمّى regionalInventoryAttributes . على سبيل المثال، أصبحت السمة RegionalInventory.price الآن ضمن RegionalInventory.regionalInventoryAttributes.price.
  • يتم الآن تضمين جميع LocalInventory الحقول باستثناء name وaccount وstoreCode ضمن عنصر جديد يُسمّى localInventoryAttributes . على سبيل المثال، أصبحت السمة LocalInventory.price الآن ضمن LocalInventory.localInventoryAttributes.price.

• إزالة customAttributes من المنتجات المتوفرة على مستوى منطقة معيّنة وفي المتجر: تمت إزالة الحقل customAttributes من كلٍّ من المَوردَين RegionalInventory وLocalInventory.

• إنشاء حساب محسّن: تمت إزالة الحقل users غير الضروري من CreateAndConfigureAccountRequest. استخدِم الحقل المفرد user لربط مستخدم أولي بحساب جديد.

• تغيير أنواع سمات معيّنة من سلاسل إلى تعدادات: تم تغيير بعض الحقول ضمن Product وInventory الموارد التي تتضمّن قائمة قصيرة محدّدة من القيم من النوع string إلى النوع enum لتحسين التحقّق من صحة البيانات (على سبيل المثال، أصبح الحقل Product.ProductAttributes.condition الآن enum).

• إزالة طريقة تعديل سياسة الإرجاع على الإنترنت: تمت إزالة الطريقة onlineReturnPolicy.update في v1. يمكنك إنشاء سياسة إرجاع على الإنترنت باستخدام onlineReturnPolicy.create بدلاً من ذلك.

كيفية نقل البيانات

من المقرّر إيقاف الإصدار v1beta من Merchant API نهائيًا في 28 فبراير 2026. لمزيد من المعلومات حول جدول الإيقاف النهائي، يُرجى الاطّلاع على دليل تحديد إصدارات Merchant API.

• خطوتك الأولى في نقل البيانات هي إكمال عملية تسجيل المطوّر لمرة واحدة (راجِع مقالة التسجيل كمطوِّر. عليك استدعاء طريقة registerGcp لكل مشروع على Google Cloud تستخدمه للمصادقة قبل أن تعمل أي من طرق v1.

• بغض النظر عن طريقة استدعاء واجهات برمجة التطبيقات (باستخدام REST أو gRPC أو باستخدام مكتبات العملاء)، يمكنك نقل البيانات على مراحل. يعني ذلك أنّه يمكنك تعديل الرمز البرمجي ونقل بياناته لواجهة برمجة تطبيقات واحدة في كل مرة (على سبيل المثال، نقل واجهة برمجة التطبيقات Products إلى v1 مع إبقاء واجهة برمجة التطبيقات Accounts على v1beta) بدون الحاجة إلى تعديل عملية التكامل بالكامل في آنٍ واحد.

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

يقدّم هذا الجدول مقارنة تفصيلية للحقول التي تم تغييرها بين الإصدارَين v1beta وv1.

v1beta	v1	الوصف
ProductInput.name	ProductInput.name	Unpadded base64url encoding مدعوم وإلزامي لـ أسماء المنتجات التي تحتوي على أحرف مستخدَمة في Merchant API أو أحرف محجوزة في عناوين URL.
Product.name	Product.name	Unpadded base64url encoding مدعوم وإلزامي لـ أسماء المنتجات التي تحتوي على أحرف مستخدَمة في Merchant API أو أحرف محجوزة في عناوين URL.
Product.gtin	Product.gtins	تم تغيير اسم حقل أرقام GTIN.
Product.taxes	تمّت إزالته	تمت إزالة الحقل taxes
Product.taxCategory	تمّت إزالته	تمت إزالة الحقل taxCategory
Product.channel	تمّت إزالته	تمت إزالة الحقل channel. استخدِم الحقل legacyLocal لحالات الاستخدام المحلية.
Product.attributes	Product.productAttributes	تم تغيير اسم الحقل attributes إلى productAttributes.
يتم تمثيل الحقول availability وcondition وgender وincludedDestinations وexcludedDestinations في Product على شكل strings (أو array من strings)	أصبحت هذه الحقول الآن enums (أو array من enums)	تم تغيير الحقول التي تتضمّن قائمة قصيرة محدّدة من القيم من النوع string إلى النوع enum.
price وsalePrice وsalePriceEffectiveDate وavailability في RegionalInventory	تم نقلها إلى RegionalInventory.regionalInventoryAttributes	تم نقل هذه الحقول ضمن regionalInventoryAttributes.
الحقل RegionalInventory.availability هو string	أصبح RegionalInventory.regionalInventoryAttributes.availability الآن enums	تم تغيير نوع الحقل "التوفّر" من string إلى enum.
price وsalePrice وsalePriceEffectiveDate وavailability وquantity وpickupMethod وpickupSla وinstoreProductLocation في LocalInventory	تم نقلها إلى LocalInventory.localInventoryAttributes	تم نقل هذه الحقول ضمن localInventoryAttributes.
الحقل LocalInventory.availability هو string	أصبح LocalInventory.localInventoryAttributes.availability الآن enums	تم تغيير نوع الحقل "التوفّر" من string إلى enum.
LocalInventory.customAttributes	تمّت إزالته	لم تعُد السمات المخصّصة متاحة للمنتجات المتوفرة في المتجر.
RegionalInventory.customAttributes	تمّت إزالته	لم تعُد السمات المخصّصة متاحة للمنتجات المتوفرة على مستوى منطقة معيّنة.
ProductInput.channel	تمّت إزالته	تمت إزالة الحقل channel. استخدِم الحقل legacyLocal لحالات الاستخدام المحلية.
DataSource.channel	تمّت إزالته	تمت إزالة الحقل channel. استخدِم الحقل legacyLocal لحالات الاستخدام المحلية.
غير متوفر	ProductInput.legacyLocal	حقل منطقي جديد للإشارة إلى أنّه لا يمكن للمنتج استهداف سوى طرق التسويق المحلية. سيتضمّن معرّف مَورد المنتج البادئة "local~".
غير متوفر	Product.legacyLocal	حقل منطقي جديد للإشارة إلى أنّ المنتج يُباع في المتاجر المحلية فقط ولا يتوفّر للشراء على الإنترنت.
غير متوفر	DataSource.legacyLocal	حقل منطقي جديد للإشارة إلى أنّ مصدر البيانات يحتوي على منتجات تُباع في المتاجر المحلية فقط.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	تم تغيير اسم الحقل gtin إلى gtins وأصبح الآن مصفوفة من السلاسل (بدلاً من سلسلة).
CreateAndConfigureAccountRequest.users	تمّت إزالته	تمت إزالة الحقل users. استخدِم الحقل user لإضافة المشرف الأولي إلى الحساب.