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

إليك Merchant API (الإصدار التجريبي)، البديل الرسمي لواجهة برمجة التطبيقات Content API for Shopping.

الاطّلاع على أحدث الميزات الجديدة وإصلاحات الأخطاء وتعديلات الإصدار من Merchant API (الإصدار التجريبي)

تعرَّف على كيفية إدارة نشاطك التجاري ومنتجاتك على Google وكيفية الحصول على إذن بالوصول الآلي إلى البيانات والإحصاءات والإمكانات الفريدة على نطاق واسع. ابدأ الآن

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

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

يتطلّب نقل البيانات من الإصدار 2 إلى الإصدار 2.1 تعديل عناوين URL لنقاط النهاية من أجل طلب الإصدارات الجديدة من v2.1 وتعديل تطبيقاتك لتتوافق مع التغييرات الأساسية التي تم إدخالها في الإصدار 2.1.

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

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

على سبيل المثال، لاستدعاء طريقة products.get باستخدام الإصدار 2، يمكنك استخدام:

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

تمت إزالة خدمة inventory من الإصدار 2، وتتوفّر وظائف مماثلة مع ميزات الإصدار 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، يتم عرض كل المنتجات تلقائيًا.

• هناك تأخير الآن لبضع دقائق قبل أن تتمكّن من retrieving a product inserted via products.get or products.list.

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

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

• لا تحتوي الردود الواردة من مكالمة products.insert أو products.update إلا على السمات التالية:

  • channel
  • contentLanguage
  • id
  • offerId
  • feedLabel

• تم إيقاف استخدام الخيار includeAttributes من الإصدار 2 نهائيًا. بدلاً من ذلك، استخدِم 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) أو ما شابه، ستتعذّر المكالمات التي تتضمّن بيانات الضرائب. إذا تم تنفيذ الطلب في ولاية لا تفرض ضريبة مضافة، يتم احتساب الضريبة استنادًا إلى الإعدادات التي تم ضبطها في 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.

• تم استبدال الطريقتَين في الإصدار 2orders.returnlineitem وorders.refund بطريقتَي orderreturns.creatOrderReturn وorderreturns.process.

  ملاحظة: مع الإصدار 2.1، ننصحك باستخدام خدمة orderreturns الجديدة لإدارة عمليات الإرجاع.

• تمت إزالة الحقول 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. إذا واجهت مشاكل أثناء اختبار التعديلات، يمكنك التواصل معنا.

تغييرات إضافية في الإصدار 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 الأصلي. يجب ضبط حقل واحد بالضبط.

ملاحظة: للحصول على قائمة كاملة بالتغييرات التي طرأت على Content API، يُرجى الاطّلاع على ملاحظات الإصدار.