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

يساعدك هذا الدليل في نقل البيانات من الإصدار v1beta من Merchant API إلى الإصدار 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 لإضافة المشرف الأوّلي إلى الحساب.

السابق
Refactor code for concurrent requests
التالي
Overview