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

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