از Content API نسخه 2 به نسخه 2.1 مهاجرت کنید

در مارس ۲۰۱۹، نسخه ۲.۱ از رابط برنامه‌نویسی کاربردی محتوا برای خرید را منتشر کردیم و در آوریل ۲۰۲۱ اعلام کردیم که نسخه ۲ در ۳۰ سپتامبر ۲۰۲۱ از رده خارج خواهد شد. نسخه ۲ از رده خارج شده است. لطفاً فوراً به نسخه ۲.۱ مهاجرت کنید.

برنامه خود را مهاجرت دهید

مهاجرت از نسخه ۲ به نسخه ۲.۱ شامل به‌روزرسانی URLهای نقاط پایانی شما برای فراخوانی نسخه‌های جدید نسخه ۲.۱ و اصلاح برنامه‌های شما برای در نظر گرفتن تغییرات اساسی معرفی‌شده در نسخه ۲.۱ است.

فراخوانی‌های API خود را برای استفاده از نقاط پایانی نسخه ۲.۱ به‌روزرسانی کنید

برای برقراری تماس با نسخه ۲.۱، درخواست‌های خود را برای استفاده از نقاط پایانی جدید نسخه ۲.۱ به‌روزرسانی کنید.

برای مثال، برای فراخوانی متد products.get با نسخه ۲، از کد زیر استفاده می‌کنید:

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

برای نسخه ۲.۱، آدرس اینترنتی (URL) را به صورت زیر به‌روزرسانی کنید:

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

برای اطلاعات کامل در مورد سرویس‌ها و نقاط پایانی نسخه ۲.۱، به مرجع API مراجعه کنید.

اعمال تغییرات مورد نیاز

علاوه بر به‌روزرسانی URLها برای فراخوانی‌های API، باید برنامه خود را نیز به‌روزرسانی کنید تا چندین تغییر اساسی که در نسخه ۲.۱ معرفی شده‌اند را در نظر بگیرید. بخش‌های زیر را مرور کنید و در صورت نیاز، برنامه خود را به‌روزرسانی کنید.

۱. به‌روزرسانی یکپارچه‌سازی‌ها با سرویس inventory

سرویس inventory نسخه ۲ حذف شده است و قابلیت‌های معادل آن با ویژگی‌های نسخه ۲.۱ زیر در دسترس است:

  • برای به‌روزرسانی‌های جزئی محصول، از Feedهای تکمیلی جدید یا products.update استفاده کنید. به‌روزرسانی‌ها برای همه فیلدهای قابل تغییر محصول، از جمله همه فیلدهایی که قبلاً با inventory.set به‌روزرسانی شده‌اند (به استثنای فیلدهایی که منحصر به localinventory هستند)، امکان‌پذیر است. برای جزئیات بیشتر به Migrate to supplemental feeds مراجعه کنید.

  • برای به‌روزرسانی‌های محصولات محلی از سرویس جدید localinventory استفاده کنید.

۲. به‌روزرسانی تماس‌ها به سرویس accounts

  • فراخوانی‌های متد accounts.update در نسخه ۲.۱، به جای به‌روزرسانی فقط فیلدهای موجود در درخواست، منبع accounts را کاملاً بازنویسی می‌کنند. برای جلوگیری از حذف فیلدهای منبع accounts ، درخواست‌های فراخوانی خود را به‌روزرسانی کنید تا شامل همه فیلدها شوند.

  • reviewsUrl حذف شده است.

  • وضعیت لینک inactive برای adsLinks ، googleMyBusinessLink و youtubeChannelLinks حذف شده است.

۳. به‌روزرسانی فراخوانی‌ها به سرویس products

  • ویژگی‌های سفارشی دیگر شامل نوع و واحد نیستند. در عوض، واحدها به مقدار اضافه می‌شوند و نوع‌ها باید به طور خودکار شناسایی شوند.

  • فیلد تکراری productTypes جایگزین هر دو productType و additionalProductTypes شده است.

  • فیلدهای تکراری includedDestinations و excludedDestinations جایگزین فیلد تکراری destinations شده‌اند.

  • فیلدهای مرتبط با ادوردز زیر تغییر نام داده‌اند:

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

  • فیلدهای زیر حذف شده‌اند:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • پارامتر includeInvalidInsertedItems حذف شده است. در نسخه ۲.۱، همه محصولات به طور پیش‌فرض بازگردانده می‌شوند.

  • اکنون چند دقیقه طول می‌کشد تا محصول درج‌شده از طریق products.get یا products.list بازیابی شود.

  • دیگر تضمین نمی‌شود که offerId برگردانده شده با offerId ورودی یکسان باشد. نسخه ۲.۱ فاصله‌های خالی اول و آخر offerId را حذف می‌کند و چندین کاراکتر فاصله خالی را در یک کاراکتر ادغام می‌کند. این تغییر بر مقادیر offerId که با سینتکس offerId پیشنهادی مطابقت دارند، تأثیری نمی‌گذارد.

  • قیمت‌ها اکنون قبل از درج محصول اعتبارسنجی می‌شوند. فقط کاراکترهای زیر در رشته مقدار مجاز هستند: + ، - ، . و اعداد (یعنی 0 تا 9 ). کاما دیگر پذیرفته نمی‌شود.

  • پاسخ‌های دریافتی از فراخوانی products.insert یا products.update فقط شامل ویژگی‌های زیر هستند:

    • channel
    • contentLanguage
    • id
    • offerId
    • feedLabel

  • گزینه includeAttributes نسخه ۲ منسوخ شده است. در عوض، برای مشاهده اطلاعات کامل محصول، products.get به همراه ProductId استفاده کنید.

۴. به‌روزرسانی فراخوانی‌های سرویس productstatuses

  • ویژگی product به همراه پارامتر includeAttributes حذف شده است. برای بازیابی ویژگی‌های محصول مربوط به یک وضعیت، از سرویس products استفاده کنید و مقدار فیلد productId جدید را ارسال کنید.

  • پارامتر includeInvalidInsertedItems حذف شده است. اکنون productId هر محصول صرف نظر از معتبر بودن یا نبودن آن، بازگردانده می‌شود.

  • فیلدهای intention ، approvalStatus و approvalPending در destinationStatuses با status جایگزین شده‌اند که رشته‌ای است که می‌تواند یکی از approved ، disapproved یا pending داشته باشد.

  • dataQualityIssues با itemLevelIssues جایگزین شده است.

۵. به‌روزرسانی فراخوانی‌ها به سرویس datafeeds

  • فیلدهای هدف زیر جایگزین شده‌اند:

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

  • فیدهای داده با contentType = "product inventory update" حذف شده‌اند.

۶. به‌روزرسانی فراخوانی‌های سرویس‌های orders و TestOrders

  • در نسخه ۲.۱، درخواست‌ها نباید شامل داده‌های مالیاتی باشند زیرا داده‌های مالیاتی به طور خودکار محاسبه می‌شوند. اگر سفارش در ایالتی با قانون انصاف بازار (MFA) یا مشابه آن انجام شود، درخواست‌هایی که شامل داده‌های مالیاتی هستند، ناموفق خواهند بود. اگر سفارش در ایالتی غیر از MFA انجام شود، مالیات بر اساس تنظیمات پیکربندی شده در مرکز فروشندگان محاسبه می‌شود. در صورت عدم پیکربندی، مالیات محاسبه شده ۰ است.

  • فیلدهای InStoreRefundLineItem و ReturnRefundLineItem به ترتیب با amountPretax و amountTax جایگزین شده‌اند. priceAmount می‌تواند بسته به محل سفارش priceAmount قبل یا بعد از کسر مالیات باشد taxAmount

  • فیلدهای 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 حذف شده است.

  • متدهای نسخه ۲ orders.returnlineitem و orders.refund با orderreturns.creatOrderReturn و orderreturns.process جایگزین شده‌اند.

  • فیلدهای customer.email ، channelType و lineItem.product.channel حذف شده‌اند.

  • فیلد promotions از سرویس TestOrder حذف شده و قالب آن در Order تغییر یافته است.

۷. به‌روزرسانی فراخوانی‌های سرویس orderinvoice

  • فیلدهای amountPretax و amountTax به ترتیب با priceAmount و taxAmount جایگزین شده‌اند. فیلد priceAmount بسته به محل سفارش می‌تواند قبل از مالیات یا پس از مالیات باشد.

  • مانده حساب (فروشنده، مشتری، گوگل) در فیلدهای invoiceSummary و هزینه تبلیغات حذف شد.

۸. حذف قابلیت‌هایی که در نسخه ۲.۱ وجود ندارند

چندین ویژگی دیگر از API محتوا در نسخه ۲.۱ حذف شده‌اند. لیست زیر را بررسی کنید و در صورت نیاز برنامه خود را به‌روزرسانی کنید:

  • XML دیگر پشتیبانی نمی‌شود. برای اطلاعات بیشتر در مورد تغییر به JSON، به «پایان پشتیبانی از XML در API محتوا برای خرید» مراجعه کنید.

  • پارامتر dryRun حذف شده است. این تغییر برای همه فراخوانی‌های API اعمال می‌شود.

  • تمام متدهای HTTP BATCH حذف شده‌اند. به جای آن customBatch استفاده کنید.

  • روش patch از سرویس‌های زیر حذف شده است:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • سرویس orderpayments حذف شده است.

مهاجرت خود را آزمایش کنید

برای اطلاعات بیشتر در مورد آزمایش تغییرات برنامه‌هایتان پس از مهاجرت به نسخه ۲.۱، به بخش «آزمایش کاربردهای API محتوا برای خرید» مراجعه کنید. اگر هنگام آزمایش به‌روزرسانی‌های خود با مشکلی مواجه شدید، می‌توانید با ما تماس بگیرید .

تغییرات اضافی در نسخه ۲.۱

علاوه بر تغییراتی که نیاز به به‌روزرسانی دارند، نسخه ۲.۱ چندین ویژگی جدید و تغییرات دائمی را نیز معرفی می‌کند:

  • خدمات جدید:

    • سرویس جدید localinventory به شما امکان می‌دهد به‌روزرسانی‌های محلی محصولات را انجام دهید (به جای سرویس inventory در نسخه ۲).

    • سرویس جدید orderreturns مدیریت خرید در گوگل (که قبلاً با نام Shopping Actions شناخته می‌شد) را آسان‌تر می‌کند و به شما امکان می‌دهد بدون نیاز به استفاده از سرویس orders مرجوعی‌ها را پردازش کنید.

  • فیدهای تکمیلی به شما امکان می‌دهند به‌روزرسانی‌های جزئی محصول را انجام دهید.

  • تغییرات اضافی در خدمات products :

    • درخواست‌های products.insert دیگر هشدارها یا خطاهای غیرمهلک را گزارش نمی‌کنند. این به شما امکان می‌دهد محصولات را وارد کنید و به‌روزرسانی‌های بعدی را برای حل مشکلات از طریق قوانین فید در مرکز فروشندگان انجام دهید، درست همانطور که با فیدهای مدیریت‌شده خارج از API محتوا انجام می‌دهید.

    • products.update اضافه شده است تا به شما امکان دهد مجموعه‌ای از فیلدهای محصول انتخابی را به‌روزرسانی کنید. برای اطلاعات بیشتر در مورد کاربردهای احتمالی، به راهنما مراجعه کنید.

    • مقادیر نامعتبر برای ویژگی‌های زیر دیگر باعث ایجاد خطاهای درج نمی‌شوند و به عنوان بخشی از itemLevelIssues توسط سرویس productstatus بازگردانده می‌شوند:

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

    • ویژگی‌های سفارشی اکنون بازگشتی هستند که نیاز به گروه‌های سفارشی را از بین می‌برد.

    • ویژگی‌های سفارشی اکنون علاوه بر فیلد value اصلی، یک فیلد groupValues ​​نیز دارند. دقیقاً یکی از فیلدها باید تنظیم شود.