از v1beta به v1 مهاجرت کنید

این راهنما به شما کمک می‌کند تا از API فروشگاهی v1beta به v1 ، اولین نسخه برای دسترسی عمومی، مهاجرت کنید. نسخه ۱ شامل چندین به‌روزرسانی و چند تغییر است که ممکن است نیاز به به‌روزرسانی کد داشته باشند. این تغییرات برای ساده‌سازی API و بهبود مدیریت حساب مرکز فروشگاهی شما طراحی شده‌اند.

تفاوت‌های کلیدی

در اینجا مهمترین تغییراتی که باید هنگام مهاجرت از v1beta به v1 از آنها آگاه باشید، آورده شده است:

  • ثبت نام یکباره حداقل یک توسعه‌دهنده API برای استفاده از Merchant API: شما باید متد registerGcp را فراخوانی کنید (فقط یک بار برای هر پروژه Google Cloud که برای احراز هویت استفاده می‌شود) تا اطلاعات تماس خود را ارائه دهید، که به شما امکان می‌دهد از API استفاده کنید و به‌روزرسانی‌ها و اطلاعیه‌های مربوط به Merchant API را دریافت کنید. تا زمانی که این مرحله تکمیل نشود، نمی‌توانید از هیچ API v1 یا v1alpha استفاده کنید. برای راهنمایی، به بخش ثبت نام به عنوان توسعه‌دهنده مراجعه کنید.

  • کدگذاری نام محصول : فیلدهای ProductInput.name و Product.name از کدگذاری base64url بدون حاشیه (RFC 4648 بخش 5) پشتیبانی می‌کنند. این دستورالعمل‌ها را دنبال کنید:

    • قبل از کدگذاری، رشته باید قالب 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 حذف شده‌اند. برای اطلاعات بیشتر ، مقاله راهنمای مرکز بازرگانان گوگل در مورد مالیات را بررسی کنید.

  • تغییرات در فیلد 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 مفرد برای مرتبط کردن یک کاربر اولیه با یک حساب کاربری جدید استفاده کنید.

  • انواع ویژگی‌های خاص از رشته‌ها به enums تغییر یافتند: برخی از فیلدهای موجود در منابع Product و Inventory با لیست کوتاه مقادیر تعریف‌شده، برای اعتبارسنجی بهتر داده‌ها از نوع string به نوع enum تغییر یافتند (برای مثال، فیلد Product.ProductAttributes.condition اکنون یک enum است).

  • حذف متد به‌روزرسانی سیاست بازگشت آنلاین: متد onlineReturnPolicy.update در v1 حذف شده است. به جای آن، یک سیاست بازگشت آنلاین با استفاده از متد onlineReturnPolicy.create ایجاد کنید.

چگونه مهاجرت کنیم

قرار است نسخه v1beta از Merchant API در تاریخ 28 فوریه 2026 از رده خارج شود. برای اطلاعات بیشتر در مورد برنامه منسوخ شدن، به راهنمای نسخه‌بندی Merchant API مراجعه کنید.

  • اولین قدم شما در مهاجرت، انجام یک ثبت‌نام توسعه‌دهنده‌ی یک‌باره است (به بخش «ثبت‌نام به عنوان توسعه‌دهنده » مراجعه کنید). قبل از اینکه هرگونه روش v1 کار کند، باید برای هر پروژه Google Cloud که برای احراز هویت استفاده می‌کنید، متد registerGcp را فراخوانی کنید.

  • صرف نظر از نحوه فراخوانی APIها (با REST، gRPC یا با استفاده از کتابخانه‌های کلاینت )، می‌توانید به صورت مرحله‌ای مهاجرت کنید. این بدان معناست که می‌توانید کد خود را به صورت یک API در یک زمان به‌روزرسانی و مهاجرت دهید (به عنوان مثال، API Products را به v1 منتقل کنید در حالی که API Accounts در v1beta نگه دارید) بدون اینکه مجبور باشید کل ادغام خود را به طور همزمان به‌روزرسانی کنید.

تغییرات جزئی فیلدها

این جدول مقایسه دقیقی از فیلدهایی که بین نسخه‌های 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 است. نوع Availability از string به enum تغییر کرد.
price ، salePrice ، salePriceEffectiveDate ، availability ، quantity ، pickupMethod ، pickupSla و instoreProductLocation در LocalInventory به LocalInventory.localInventoryAttributes منتقل شد این فیلدها به زیر localInventoryAttributes منتقل شده‌اند.
فیلد LocalInventory.availability یک string است LocalInventory.localInventoryAttributes.availability اکنون یک enums است. نوع Availability از 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