نقل البيانات من الإصدار الثاني من Content API إلى الإصدار 2.1

في آذار (مارس) 2019، أصدرنا الإصدار 2.1 من Content API for Shopping، وفي نيسان (أبريل) 2021 أعلنّا عن إيقاف الإصدار الثاني في 30 أيلول (سبتمبر) 2021. تم إيقاف الإصدار 2. يُرجى الانتقال إلى الإصدار 2.1 على الفور.

نقل بيانات تطبيقك

يتضمّن الانتقال من الإصدار 2.1 إلى الإصدار 2.1 تحديث عناوين URL لنقاط النهاية لاستدعاء الإصدارات الجديدة من الإصدار 2.1 وتعديل تطبيقاتك لمراعاة أي تغييرات قد تؤدي إلى أعطال تم إدخالها في الإصدار 2.1.

تعديل طلبات البيانات من واجهة برمجة التطبيقات لاستخدام نقاط النهاية الإصدار 2.1

لإجراء طلبات لاستخدام الإصدار 2.1، يجب تعديل طلباتك لاستخدام نقاط النهاية الجديدة التي تستخدم الإصدار 2.1.

على سبيل المثال، لاستدعاء الإجراء products.get مع v2، يمكنك استخدام:

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

بالنسبة إلى الإصدار 2.1، يمكنك تحديث عنوان URL إلى:

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

للحصول على معلومات كاملة حول خدمات الإصدار 2.1 ونقاط النهاية، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

إجراء التغييرات المطلوبة

بالإضافة إلى تحديث عناوين URL لطلبات البيانات من واجهة برمجة التطبيقات، يجب أيضًا تحديث تطبيقك لمراعاة العديد من التغييرات التي قد تؤدي إلى أعطال تم إدخالها في الإصدار 2.1. يُرجى مراجعة الأقسام التالية وتعديل تطبيقك حسب الحاجة.

1- تحديث عمليات الدمج مع خدمة inventory

تمت إزالة الإصدار 2 من خدمة inventory، وتتوفّر وظائف مكافئة مع ميزات الإصدار 2.1 التالية:

  • استخدِم الخلاصات التكميليّة الجديدة أو products.update للحصول على تعديلات جزئية من المنتج. يمكن إجراء تعديلات على جميع حقول المنتجات القابلة للتغيير، بما في ذلك جميع الحقول التي تم تعديلها سابقًا باستخدام السمة inventory.set (باستثناء تلك التي لا تشملها السمة localinventory). يُرجى الاطّلاع على نقل البيانات إلى الخلاصات التكميلية للحصول على مزيد من التفاصيل.

  • يمكنك استخدام خدمة localinventory الجديدة للاطّلاع على آخر الأخبار عن المنتجات المحلية.

2. تعديل المكالمات لخدمة "accounts"

  • تؤدي الاستدعاءات إلى طريقة accounts.update في الإصدار 2.1 إلى استبدال مورد accounts بالكامل، بدلاً من تعديل الحقول المضمّنة في الطلب فقط. لتجنّب حذف الحقول في مورد accounts، يجب تعديل طلبات الاتصال لتضمين جميع الحقول.

  • تمّت إزالة reviewsUrl.

  • تمت إزالة حالة الرابط inactive لـ adsLinks وgoogleMyBusinessLink وyoutubeChannelLinks.

3. تعديل المكالمات لخدمة "products"

  • لم تعد السمات المخصّصة تحتوي على نوع ووحدة. وبدلاً من ذلك، يجب إلحاق الوحدات بالقيمة ويجب اكتشاف الأنواع تلقائيًا.

  • لقد حل الحقل المتكرر productTypes محل productType وadditionalProductTypes على حد سواء.

  • تم استبدال الحقل المكرر destinations بالحقلين المتكررين includedDestinations وexcludedDestinations.

  • تمت إعادة تسمية الحقول التالية المرتبطة بخدمة AdWords:

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • تمت إزالة الحقول التالية:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • تمت إزالة المَعلمة includeInvalidInsertedItems. في الإصدار 2.1، يتم إرجاع جميع المنتجات بشكل افتراضي.

  • هناك الآن تأخير لبضع دقائق قبل أن تتمكّن من استرداد المنتج الذي تم إدراجه من خلال products.get أو products.list.

  • لم يعُد من المضمون أن تكون قيمة offerId المعروضة مماثلة للإدخال offerId. يقطع الإصدار 2.1 المسافة البيضاء البادئة واللاحقة في offerId ويدمج أحرف مسافات بيضاء متعددة في حرف واحد. لن يؤثر هذا التغيير في قيم offerId التي تتوافق مع بنية offerId المقترَحة.

  • تم الآن التحقّق من صحة الأسعار قبل إدراج المنتج. يُسمح باستخدام الأحرف التالية فقط في سلسلة القيمة: + و- و. والأرقام (أي 0-9). لم يعُد يتم قبول الفواصل.

  • تحتوي الردود من استدعاء products.insert أو products.update فقط على السمات التالية:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • تم إيقاف خيار الإصدار 2 includeAttributes نهائيًا. بدلاً من ذلك، يمكنك استخدام السمة products.get مع السمة ProductId لعرض معلومات المنتج الكاملة.

4. تعديل المكالمات لخدمة "productstatuses"

  • تمت إزالة السمة product مع المعلمة includeAttributes. لاسترداد سمات المنتج المقابلة للحالة، استخدِم خدمة products واضبط قيمة حقل productId الجديد.

  • تمت إزالة المَعلمة includeInvalidInsertedItems. يتم الآن عرض productId لكل منتج بغض النظر عمّا إذا كان المنتج صالحًا أم لا.

  • تم استبدال الحقول intention وapprovalStatus وapprovalPending في destinationStatuses بـ status، وهي سلسلة يمكن أن تكون ضمن approved أو disapproved أو pending.

  • تم استبدال الحقل "dataQualityIssues" بـ "itemLevelIssues".

5. تعديل المكالمات لخدمة "datafeeds"

  • تم استبدال الحقول المستهدفة التالية:

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations، وexcludedDestinations

  • تمت إزالة خلاصات البيانات التي تحتوي على contentType = "product inventory update".

6. تعديل المكالمات إلى خدمتَي "orders" و"TestOrders"

  • في الإصدار 2.1، يجب ألا تتضمن المكالمات بيانات ضريبية لأنه يتم احتساب البيانات الضريبية تلقائيًا. إذا تم تنفيذ الأمر في ولاية تتّبع قانون العدالة في السوق (MFA) أو ما شابه، سيتعذّر تنفيذ الطلبات التي تتضمّن بيانات ضريبية. إذا تم تنفيذ الطلب في حالة لا تندرج ضمن "MFA"، يتم احتساب الضريبة استنادًا إلى الإعدادات التي تم ضبطها في Merchant Center. وفي حال عدم ضبط هذه السياسة، تكون الضريبة المحسوبة 0.

  • تم استبدال الحقلَين InStoreRefundLineItem وReturnRefundLineItem amountPretax وamountTax بالحقلَين priceAmount وtaxAmount على التوالي. يمكن أن يكون priceAmount بدون الضريبة أو بعد الضريبة، حسب موقع الطلب.

  • تم نقل الحقول ShipLineItem carrier وshipmentId وtrackingId في الطلب إلى shipmentInfos.

  • أصبح billingAddress وpredefinedBillingAddress الآن حقلَي المستوى الأعلى في orders وTestOrder، على التوالي.

  • تم استبدال الحقل "customer.explicitMarketingPreference" بـ "customer.marketingRightsInfo".

  • تم تقسيم الحقل netAmount إلى netPriceAmount وnetTaxAmount.

  • تم استبدال الحقل "shippingOption" بـ "lineItems[].shippingDetails".

  • تمت إزالة الحقول CancelLineItem amount وamountPretax وamountTax في الطلب. يتم الآن حساب المبلغ الذي تم رده تلقائيًا.

  • تمّت إزالة CustomBatch.

  • تمّت إزالة Refund. يمكنك استخدام refundOrder أو refundItem كبديل.

  • تمت إزالة الحقل paymentMethod.

  • تم استبدال الطريقتين v2orders.returnlineitem وorders.refund بالرمز orderreturns.creatOrderReturn وorderreturns.process

  • تمّت إزالة الحقول customer.email وchannelType وlineItem.product.channel.

  • تمت إزالة الحقل promotions من خدمة TestOrder وتغيير تنسيقه في Order.

7. تعديل المكالمات لخدمة "orderinvoice"

  • تم استبدال الحقلين amountPretax وamountTax بالحقلَين priceAmount وtaxAmount على التوالي. يمكن أن يكون الحقل priceAmount قبل الضريبة أو ما بعد الضريبة، حسب موقع الطلب.

  • تمت إزالة الأرصدة (التاجر أو العميل أو Google) في invoiceSummary والحقول المرتبطة برسوم العرض الترويجي.

8. إزالة الوظائف غير المضمّنة في الإصدار 2.1

وقد تمت إزالة ميزات أخرى متعددة من Content API في الإصدار 2.1. يُرجى مراجعة القائمة التالية وتعديل طلبك حسب الحاجة:

  • لم يعُد تنسيق XML متوافقًا. لمزيد من المعلومات حول التبديل إلى JSON، يُرجى الاطّلاع على الإيقاف النهائي لاستخدام XML في Content API for Shopping.

  • تمت إزالة المَعلمة dryRun. وينطبق هذا التغيير على كل طلبات البيانات من واجهة برمجة التطبيقات.

  • تمت إزالة جميع الطرق البالغ عددها HTTP BATCH. يمكنك استخدام customBatch كبديل.

  • تمت إزالة طريقة patch من الخدمات التالية:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • تمت إزالة خدمة orderpayments.

اختبار نقل البيانات

للاطّلاع على مزيد من المعلومات حول اختبار التغييرات التي أجريتها على تطبيقاتك بعد الانتقال إلى الإصدار 2.1، يمكنك الاطّلاع على اختبار استخدامات Content API for Shopping. إذا واجهت مشاكل أثناء اختبار التحديثات، يمكنك نشرها على منتدى Content API.

تغييرات إضافية في الإصدار 2.1

بالإضافة إلى التغييرات التي تتطلب تحديثات، يوفر الإصدار 2.1 أيضًا العديد من الميزات الجديدة والتغييرات غير الفاصلة:

  • الخدمات الجديدة:

    • تتيح لك خدمة localinventory الجديدة إجراء تعديلات على المنتجات المحلية (بدلاً من خدمة inventory في الإصدار 2).

    • تسهّل خدمة orderreturns الجديدة إدارة ميزة "الشراء على Google" (المعروفة سابقًا باسم Shopping Actions) من خلال السماح لك بمعالجة المرتجعات بدون الحاجة إلى استخدام خدمة orders.

  • تتيح لك الخلاصات التكميلية إجراء تعديلات جزئية على المنتجات.

  • تغييرات إضافية على خدمة "products":

    • لم تعُد طلبات products.insert تُبلغ عن التحذيرات أو الأخطاء غير الفادحة. يتيح لك ذلك إدراج المنتجات وإجراء التعديلات اللاحقة لحلّ المشاكل من خلال قواعد الخلاصات في Merchant Center، تمامًا كما تفعل في الخلاصات المدارة خارج Content API.

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

    • إنّ القيم غير الصالحة للسمات التالية لم تعُد تؤدي إلى ظهور أخطاء الإدراج، وسيتم عرضها كجزء من itemLevelIssues من خلال خدمة productstatus:

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • أصبحت السمات المخصّصة الآن متكررة، ما يؤدّي إلى إلغاء الحاجة إلى المجموعات المخصّصة.

    • تحتوي السمات المخصّصة الآن على حقل groupValues بالإضافة إلى حقل value الأصلي. يجب ضبط حقل واحد فقط.