می‌توانید داده‌های محصول را بااستفاده از فیدهای مبتنی بر فایل، Merchant API، یا ترکیبی از هر دو در Merchant Center بارگذاری کنید:
- فیدهای محصول مبتنی بر فایل: فایل‌های CSV، TSV، یا XML را بااستفاده از SFTP، Google Cloud Storage، «کاربرگ‌نگار Google»، یا واکشی‌های زمان‌بندی‌شده بارگذاری کنید.
- Merchant API: درخواست‌های برنامه‌ای را مستقیماً از باطن خود برای به‌روزرسانی‌های افزایشی با تغییر داده‌های محصول، در کنار همگام‌سازی‌های دوره‌ای کامل کاتالوگ ارسال کنید.
این راهنما هر دو رویکرد را مقایسه می‌کند، توضیح می‌دهد که چه زمانی باید از یکی به‌جای دیگری (یا هر دو باهم) استفاده کرد، و اگر تصمیم بگیرید برخی یا همه محصولاتتان را از فیدهای فایل به API منتقل کنید، یک دستورالعمل گام‌به‌گام انتقال ارائه می‌دهد.
رویکرد منبع داده‌تان را انتخاب کنید
برای تصمیم‌گیری درباره اینکه از Merchant API، فیدهای فایل، یا راه‌اندازی ترکیبی استفاده کنید، نوسان کاتالوگ، معماری پس‌بک، و گردش کار عملیاتی خود را ارزیابی کنید.
چه زمانی باید از Merchant API استفاده کرد
در شرایط زیر از منبع داده اصلی API استفاده کنید:
- ادغام برنامه‌ای مستقیم: ترجیح می‌دهید به‌جای تولید فایل و مدیریت خطوط انتقال فایل (مثل SFTP یا Google Cloud Storage)، مستقیماً از باطن خودتان با میانای برنامه‌سازی کاربردی تماس بگیرید.
- نوسان بالای قیمت و موجودی: قیمت محصولات یا سطح موجودی شما درطول روز به‌طور مکرر تغییر می‌کند.
- به‌روزرسانی فوری هنگام تغییر داده‌ها: می‌خواهید تغییرات محصول را به‌محض وقوع در پس‌زمینه به Google ارسال کنید، به‌جای اینکه منتظر تولید و بارگذاری فایل زمان‌بندی‌شده بعدی بمانید.
- به‌روزرسانی‌های افزایشی کاتالوگ: می‌خواهید محصولات را به‌صورت تکی با تغییر آن‌ها درج، به‌روزرسانی، یا حذف کنید، بدون اینکه هربار کل کاتالوگ را دوباره بارگذاری کنید.
- به‌روزرسانی‌های جزئی مشخصه: می‌خواهید فیلدهای خاصی از محصول را (مثل
priceیاavailabilityبااستفاده ازproductInputs.patch) بدون ارسال مجدد بار داده کامل محصول به‌روز کنید.
چه زمانی از فیدهای فایل استفاده کنیم
در شرایط زیر از منبع داده اصلی فایل‌محور استفاده کنید:
- کاتالوگ ثابت: داده‌های محصول شما به‌ندرت تغییر می‌کند (برای مثال، یک‌بار در روز یا کمتر).
- بخش پشتی فقط عکس آنی بدون ردیابی دلتا: بخش پشتی شما فقط عکس‌های آنی کامل کاتالوگ را صادر می‌کند و نمی‌تواند تغییرات سطح مورد یا حذف صریح محصول را ردیابی کند.
- گردش کار مبتنی بر صفحه‌گسترده: تیم‌های غیرمهندسی داده‌های محصول را مستقیماً در «کاربرگ‌نگار Google» یا فایل‌های CSV مدیریت یا لغو می‌کنند.
- عملیات با نگهداری کم: شما صادر کردن فایل زمان‌بندی‌شده را ترجیح می‌دهید که در آن Merchant Center واکشی و پردازش عکس آنی را انجام می‌دهد، به‌جای اینکه ادغام میانای برنامه‌سازی کاربردی را با سرعت درخواست، مدیریت تلاش مجدد، و همگام‌سازی‌های دوره‌ای کل کاتالوگ انجام دهد.
چه زمانی از هر دو استفاده کنیم
در سناریوهای زیر می‌توانید فیدهای فایل و Merchant API را در یک حساب Merchant Center ترکیب کنید:
- کاتالوگ‌های محصول پارتیشن‌بندی‌شده: از Merchant API برای محصولاتی که سریع تغییر می‌کنند (مانند حراج‌های فوری یا موجودی با گردش بالا) و فیدهای فایل برای بخش‌های کاتالوگ ایستا یا خطوط محصول جداگانه استفاده می‌کنید. مطمئن شوید هر محصول فقط توسط یک منبع داده اصلی بارگذاری شده باشد (به استفاده موازی و مالکیت منبع داده اصلی مراجعه کنید).
- داده‌های اصلی API با فیدهای تکمیلی مبتنی بر فایل: شما داده‌های اصلی محصول را ازطریق منبع داده‌های اصلی API مدیریت می‌کنید، درحالی‌که تیم‌های غیرمهندسی یا شرکای شخص ثالث مشخصه‌های اضافی را ازطریق فیدهای تکمیلی مبتنی بر فایل (مانند «کاربرگ‌نگار Google» یا فایل‌های CSV) که با قوانین مشخصه پیوند داده شده‌اند، یا برعکس، ارائه می‌دهند.
- انتقال جزئی یا مرحله‌ای: بازارها، دسته‌ها، یا حساب‌های فرعی خاصی را به API منتقل می‌کنید، درحالی‌که بقیه کاتالوگتان را در فیدهای فایل نگه می‌دارید.
اگر تصمیم گرفتید برخی یا همه محصولاتتان را از فیدهای فایل به Merchant API منتقل کنید، کتاب راهنمای گام‌به‌گام انتقال را دنبال کنید.
تفاوت‌های معماری کلیدی
فیدهای فایل و Merchant API مبتنی بر ارسال ازنظر نحوه پردازش و مدیریت داده‌های محصول توسط Google با یکدیگر تفاوت دارند:
| مفهوم | فیدهای فایل | میانای برنامه‌سازی کاربردی فروشنده |
|---|---|---|
| مدل ادغام | انتقال فایل آفلاین: کاتالوگتان را به یک فایل صادر می‌کنید و آن را بااستفاده از SFTP، Google Cloud Storage، «کاربرگ‌نگار Google»، یا واکشی‌های زمان‌بندی‌شده منتقل می‌کنید. | ادغام برنامه‌ای مستقیم: باطن شما درخواست‌ها را مستقیماً به نقطه پایانی API ارسال می‌کند. |
| جزئیات دگرگونی | پردازش انبوه: اصلاح یک مورد معمولاً نیاز به پردازش مجدد کل فایل دارد. | تراکنش‌های جزئی: می‌توانید فقط محصولاتی را که تغییر کرده‌اند درج، وصله، یا حذف کنید. |
| زمان‌بندی همگام‌سازی | همگام‌سازی دسته‌ای: تغییرات در پس‌بک شما منتظر می‌مانند تا چرخه بعدی صادر کردن و انتقال فایل زمان‌بندی‌شده انجام شود. | فراخوانی‌های فوری یا زمان‌بندی‌شده: می‌توانید تغییرات افزایشی را بلافاصله پس‌از وقوع، در کنار همگام‌سازی‌های کامل دوره‌ای ارسال کنید. |
| رفتار حذف | ضمنی (عکس آنی): هر فایل یک عکس آنی کامل است؛ برداشتن یک ردیف از فایل اصلی‌تان محصول را حذف می‌کند. | صریح: مفهوم عکس آنی وجود ندارد؛ برای برداشتن محصول متوقف‌شده، با productInputs.delete تماس بگیرید. |
| نمایش منبع | تک‌ایالتی: ردیف‌های فایل شما نشان‌دهنده ورودی خام است. | جدا کردن داده‌های خام و پردازش‌شده: میانای برنامه‌سازی کاربردی داده‌ها را به ProductInput (ورودی خام شما) و Product (وضعیت پردازش‌شده نهایی) تقسیم می‌کند. |
| قوانین مشخصه (جارزن) | روی ستون‌های فایل خام در میانای کاربری Merchant Center اعمال می‌شود. | در واسط کاربر Merchant Center پشتیبانی می‌شود. هنگام ادغام داده‌های میانای برنامه‌سازی کاربردی با فایل‌های تکمیلی شخص ثالث الزامی است؛ برای تبدیل‌های تک‌منبعی اختیاری است اگر در زیرینه شما انجام شود. |
استفاده موازی و مالکیت منبع داده اصلی («آخرین به‌روزرسانی برنده است»)
اگرچه می‌توانید از فیدهای فایل و API در همان حساب Merchant Center استفاده کنید، اما به‌شدت توصیه می‌کنیم که فقط از یک روش برای درج هر محصول خاص استفاده کنید.
Merchant Center براساس مدل «آخرین به‌روزرسانی برنده است» عمل می‌کند. منبع داده اصلی (میانای برنامه‌سازی کاربردی یا فید فایل) که جدیدترین درج محصول را ارسال کرده است، مالکیت اصلی داده‌های آن محصول را به‌دست می‌آورد:
- وقتی منبع داده فایل مالک محصول است: حذف محصول از بارگذاری فایل بعدی باعث حذف ضمنی می‌شود و محصول را از Merchant Center برمی‌دارد.
- وقتی منبع داده میانای برنامه‌سازی کاربردی مالک محصول است: حذف محصول از بارگذاری فایل تأثیری ندارد زیرا فید فایل دیگر مالک محصول نیست.
برای برداشتن آن باید با
accounts.productInputs.deleteتماس بگیرید. - خطر مالکیت مجدد تصادفی: اگر فید فایل به‌روزشده پس‌از ارسال API اجرا شود و حاوی محصول باشد، منبع داده فایل دوباره مالکیت را به‌دست می‌آورد. حذف‌های بعدی از فایل سپس به‌طور غیرمنتظره‌ای محصول را حذف خواهد کرد.
برای جلوگیری از حذف‌های غیرمنتظره یا ازدست رفتن به‌روزرسانی‌های میانای برنامه‌سازی کاربردی، به‌روزرسانی‌های هم‌زمان را برای محصولات یکسان بااستفاده از هر دو منبع داده‌های اصلی میانای برنامه‌سازی کاربردی و فایل انجام ندهید.
ملاحظات کلیدی میانای برنامه‌سازی کاربردی
قبل‌از شروع پیاده‌سازی، با این رفتارهای مهم Merchant API آشنا شوید:
منابع داده انعطاف‌پذیر (بدون زبان یا برچسب)
برخلاف فیدهای فایل که شما را ملزم می‌کنند برچسب فید هدف و زبان خاصی را ازقبل تعریف کنید، Merchant API به شما امکان می‌دهد منابع داده اصلی را بدون مشخص کردن feedLabel یا contentLanguage ایجاد کنید.
- بارگذاری‌های انعطاف‌پذیر: این ویژگی به شما امکان می‌دهد محصولات را با هر زبان یا ترکیب برچسب فید در یک منبع داده واحد بارگذاری کنید.
- مدیریت ساده‌شده: لازم نیست برای هر بازار هدف، منابع داده جداگانه ایجاد و مدیریت کنید. توجه: برای جزئیات بیشتر درباره انتخاب راهبرد منبع داده، به انتخاب راهبرد منبع داده مراجعه کنید.
راهبرد همگام‌سازی و سهمیه‌ها
برخلاف فید فایل که در آن کل کاتالوگ خود را در یک دسته بارگذاری می‌کنید، ادغام Merchant API خود را هم براساس به‌روزرسانی‌های افزایشی و هم همگام‌سازی‌های کامل زمان‌بندی‌شده طراحی کنید:
- به‌روزرسانی‌های افزایشی را با همگام‌سازی‌های کامل دوره‌ای ترکیب کنید:
درخواست‌های
productInputs.insertیاproductInputs.patchرا با تغییر مشخصه‌های محصول در باطن خود ارسال کنید. چون اتکای صرف به به‌روزرسانی‌های افزایشی می‌تواند باعث شود داده‌هایتان به‌مرور زمان از همگام‌سازی خارج شود، همگام‌سازی‌های کامل دوره‌ای را نیز اجرا کنید تا کاتالوگتان با منبع حقیقت شما مطابقت داشته باشد (که این کار همچنین انقضای ۳۰ روزه محصول را بازآوری می‌کند). تعداد دفعات اجرای همگام‌سازی کامل به اندازه کاتالوگ و سهمیه میانای برنامه‌سازی کاربردی دردسترس بستگی دارد. - درخواست‌ها را برای رعایت سهمیه‌های API تنظیم کنید: API را برای همه محصولات خود به‌طور هم‌زمان فراخوانی نکنید. درحالی‌که تغییرات افزایشی را می‌توان به‌محض وقوع ارسال کرد، درخواست‌های همگام‌سازی کامل را به‌طور یکنواخت درطول روز توزیع کنید تا در محدوده سهمیه‌های فراخوانی روش دقیقه‌ای و روزانه خود باقی بمانید. برای جزئیات، سهمیه‌ها و محدودیت‌ها و به‌روزرسانی مکرر محصولات را ببینید.
درحال آزمایش یکپارچه‌سازی
قبل‌از انتقال به محیط تولید، منطق ادغام خود را در محیطی امن اعتبارسنجی کنید.
استفاده از حساب‌های آزمایشی
قبل‌از اعمال تغییرات در تولید، توصیه می‌کنیم مراحل اولیه انتقال را در حساب آزمایشی جعبه امن اجرا کنید:
- ایجاد حساب آزمایشی: یک حساب آزمایشی مجزا راه‌اندازی کنید تا بتوانید بدون تأثیر گذاشتن بر آگهی‌های فعال یا فهرستگان‌های رایگان، به‌طور ایمن آزمایش کنید.
- ایجاد منبع داده میانای برنامه‌سازی کاربردی: ایجاد منبع داده اصلی میانای برنامه‌سازی کاربردی را تمرین کنید.
- آزمایش کردن قوانین مشخصه: تبدیل‌های داده و پیوستن‌های فید تکمیلی را درستی‌سنجی کنید.
- اعتبارسنجی بار داده‌ها و کلیدهای محصول: محصولات نمونه را برای تأیید حروف بزرگ و کوچک، کدگذاری، و مدیریت خطای «واحد نگهداری موجودی» (SKU) ارسال کنید.
برای جزئیات، به مرحله ۱: ایجاد حساب‌های آزمایشی و راهنمای حساب‌های آزمایشی مراجعه کنید.
اعتبارسنجی هم‌ترازی کلید محصول
مطمئن شوید که کلید محصول بار داده برنامه‌ای شما دقیقاً با SKUهای فید فایل شما مطابقت داشته باشد. Google محصولات را با ترکیب موارد زیر شناسایی می‌کند:
offerId(در فیدهای فایل،idنامیده می‌شود، حروف‌حساس)-
contentLanguage(برای مثالen) -
feedLabel(برای مثالUS)
نویسه‌های خاص و کدبندی
اگر شناسه‌های محصولتان حاوی نویسه‌هایی مثل /، %، یا ~ است، از
قالب کدبندی‌شده (کدبندی base64url بدون لایه) در فراخوانی‌های میانای برنامه‌سازی کاربردی استفاده کنید. برای اطلاعات بیشتر،
ProductInput.name را
ببینید
کنترل همزمانی
در ادغام هم‌زمان، به‌روزرسانی‌ها ممکن است به‌دلیل تأخیر شبکه به‌ترتیب نرسند. برای جلوگیری از رونویسی داده‌های جدیدتر توسط به‌روزرسانی‌های قدیمی‌تر، از فیلد
versionNumber
در منبع ProductInput استفاده کنید.
کتاب راهنمای گام‌به‌گام انتقال
اگر تصمیم دارید برخی یا همه محصولاتتان را از فیدهای فایل به Merchant API منتقل کنید، این راهنمای گام‌به‌گام را دنبال کنید تا محصولاتتان را بدون ازدست دادن ظهورها یا سابقه ارائه منتقل کنید.
۱. انتقال را در حساب آزمایشی تمرین کنید
قبل‌از اعمال تغییرات در تولید، بااستفاده از روش
accounts.createTestAccount یک حساب آزمایشی جعبه امن ایجاد کنید (به راهنمای
حساب‌های آزمایشی مراجعه کنید). حساب‌های آزمایشی محیطی مجزا فراهم می‌کنند که در آن پیشنهادها به‌طور پیش‌فرض تأیید می‌شوند، درستی‌سنجی دامنه لازم نیست، و داده‌ها هرگز به‌طور عمومی ارائه نمی‌شوند.
از حساب آزمایشی‌تان برای بازتاب دادن راه‌اندازی تولید و تمرین کردن انتقال سرتاسری استفاده کنید:
- راه‌اندازی فید فایل را منعکس کنید: منبع داده اصلی فایل (و هر منبع داده تکمیلی) را در حساب آزمایشی ایجاد کنید و نمونه‌ای از فایل فید تولید خود را بارگذاری کنید.
- ایجاد منبع داده میانای برنامه‌سازی کاربردی آزمایشی و قوانین: منبع داده اصلی میانای برنامه‌سازی کاربردی ایجاد کنید و هرگونه قانون مشخصه لازم یا پیوستن فید تکمیلی را پیکربندی کنید.
- آزمایش کردن تصاحب مالکیت و هم‌ترازی کلید:
productInputs.insertدرخواست برای محصولات نمونه ارسال کنید و تأیید کنید که منبع داده API مالکیت موارد موجود را بدون ایجاد محصولات تکراری تصاحب می‌کند. - درستی‌سنجی به‌روزرسانی‌ها و حذف‌ها: به‌روزرسانی‌های جزئی را با
productInputs.patchو حذف‌ها را باproductInputs.deleteآزمایش کنید و منابع حاصل را باproducts.getبررسی کنید.
۲. ایجاد کردن منابع داده API تولید
قبل‌از ارسال داده‌ها، یک منبع داده اصلی از نوع API در حسابتان ایجاد کنید.
ایجاد منبع داده اصلی API
برای ایجاد منبع داده‌ای که ارسال‌های API را می‌پذیرد، درخواست POST را به نقطه پایانی dataSources ارسال کنید. برای جزئیات بیشتر،
ایجاد منبع داده محصولات اصلی را ببینید.
۳. قوانین مشخصه سفارشی انتقال
قوانین مشخصه سفارشی به منابع داده خاصی متصل می‌شوند و به‌طور خودکار از منبع داده فایل به منبع داده میانای برنامه‌سازی کاربردی جدید منتقل نمی‌شوند.
نحوه انتقال قوانین مشخصه به هدف آن‌ها بستگی دارد:
- ادغام بین‌منبعی و فیدهای تکمیلی طرف سوم: اگر داده‌های میانای برنامه‌سازی کاربردی اصلی را با منابع داده تکمیلی خارجی (مانند فایل‌های تأمین‌کننده طرف سوم، صفحه‌گسترده‌های موجودی، یا فیدهای تبلیغاتی) ترکیب می‌کنید، باید قوانین مشخصه را در واسط کاربری Merchant Center بازآفرینی کنید و آن‌ها را به منبع داده میانای برنامه‌سازی کاربردی جدید پیوست کنید. پیش‌پردازش سمت کارخواه نمی‌تواند جایگزین قوانینی شود که داده‌ها را در چندین منبع مستقل به هم متصل می‌کنند.
- تبدیل داده‌های تک‌منبعی: برای پاک‌سازی تک‌منبعی، مقادیر پیش‌فرض، یا قالب‌بندی رشته در داده‌های کاتالوگ اصلی، یکی از گزینه‌های زیر را انتخاب کنید:
- تبدیل‌های پس‌زمینه (توصیه‌شده): تبدیل‌ها را در سیستم خودتان قبل‌از فراخوانی میانای برنامه‌سازی کاربردی اعمال کنید. این کار کنترل برنامه‌ای بیشتر، آزمایش آسان‌تر، و اشکال‌زدایی ساده‌تری را برای شما فراهم می‌کند.
- قوانین مشخصه Merchant Center: اگر می‌خواهید Merchant Center همچنان به‌طور خودکار آن‌ها را مدیریت کند، قوانین تبدیل را برای منبع داده API جدیدتان در میانای کاربری Merchant Center بازسازی کنید.
۴. فعال کردن یکپارچه‌سازی میانای برنامه‌سازی کاربردی
ادغام میانای برنامه‌سازی کاربردی تولید را روشن کنید تا درج، به‌روزرسانی، و حذف محصولات را در منبع داده اصلی میانای برنامه‌سازی کاربردی جدیدتان شروع کنید:
درج و به‌روزرسانی محصولات (تصاحب مالکیت): درخواست‌های
productInputs.insertوproductInputs.patchرا از ادغام خود ارسال کنید. وقتی محصولی را بااستفاده از API با همان کلید (offerId،contentLanguage،feedLabel) محصول فید فایل موجود درج می‌کنید، منبع داده API مالکیت آن محصول را به‌دست می‌گیرد و سابقه ارائه آن را حفظ می‌کند. برای راهنمایی بیشتر، درج محصول و افزودن و مدیریت محصولات را ببینید.حذف محصولات توقف‌تولیدشده: یکپارچه‌سازی‌تان را پیکربندی کنید تا هروقت محصولی از کاتالوگتان برداشته شد، صریحاً
productInputs.deleteرا فراخوانی کند.استقرار تدریجی: برای کاتالوگ‌های بزرگ، ادغام را برای یک زیرحساب Merchant Center یا یک منبع داده در هر زمان فعال کنید.
پیکربندی همزمانی: اگر درخواست‌های زیادی ارسال می‌کنید، کارخواه خود را پیکربندی کنید تا درخواست‌های هم‌زمان را مدیریت کند و چندین اتصال را مدیریت کند. راهنمای بازسازی کد برای درخواست‌های هم‌زمان را ببینید.
۵. توقف موقت به‌روزرسانی‌های منبع داده فایل
وقتی ادغام میانای برنامه‌سازی کاربردی فعال شد، به‌روزرسانی‌های فایل را قبل‌از اجرای زمان‌بندی‌شده بعدی فایل متوقف کنید تا منبع داده فایل، به‌روزرسانی‌های میانای برنامه‌سازی کاربردی را رونویسی نکند:
- بارگذاری فایل‌های جدید در مکان SFTP/FTP، Google Cloud Storage، یا «کاربرگ‌نگار Google» را متوقف کنید.
- در میانای کاربری Merchant Center، به منبع داده فایل بروید و واکشی زمان‌بندی‌شده آن را موقتاً متوقف کنید.
- محصولات موجود متعلق به منبع داده فایل تا ۳۰ روز فعال باقی می‌مانند تا زمانی که یکپارچه‌سازی میانای برنامه‌سازی کاربردی شما آن‌ها را درج کند.
۶. منتظر بمانید تا انتقال تکمیل و تأیید شود
صبر کنید تا همه محصولات فعال از منبع داده فایل به منبع داده میانای برنامه‌سازی کاربردی منتقل شوند. درحالی‌که به‌روزرسانی‌های افزایشی محصولات را با تغییر آن‌ها منتقل می‌کنند، اجرای همگام‌سازی کامل کاتالوگ با سرعت مناسب ازطریق ادغام منظم شما، سرعت انتقال کل کاتالوگ شما را افزایش می‌دهد (به استراتژی همگام‌سازی و سهمیه‌ها مراجعه کنید).
درطول این مرحله:
- در واسط کاربر Merchant Center، تعداد کالاها را پایش کنید. صبر کنید تا
تعداد منبع داده فایل به
0کاهش یابد و تعداد منبع داده API با کاتالوگ فعال شما مطابقت داشته باشد. - از
products.getاستفاده کنید تا مطمئن شوید مشخصه‌ها و قوانین مشخصه سفارشی طبق انتظار ادغام می‌شوند. - ابزار عیب‌یابی میانای برنامه‌سازی کاربردی را در میانای کاربری Merchant Center پایش کنید تا نرخ خطا و عملکرد میانای برنامه‌سازی کاربردی را ردیابی کنید.
۷. ازکار انداختن منبع داده فایل
پس‌از تکمیل گذار و زمانی که تعداد موارد فید فایل 0 است:
- مطمئن شوید به‌روزرسانی‌ها به‌طور هم‌زمان منعکس می‌شوند.
- منبع داده فایل قدیمی را در میانای کاربر Merchant Center حذف کنید تا به‌روزرسانی‌های تصادفی مبتنی بر فایل داده‌های میانای برنامه‌سازی کاربردی شما را بازنویسی نکنند.