این سند دستورالعملهایی برای بهترین شیوهها ارائه میدهد. برای اطلاعات بیشتر به نکات مربوط به عملکرد مراجعه کنید.
چه زمانی از API استفاده کنیم
برای ارسال درخواستها به صورت برنامهنویسیشده
چه بخواهید هر بخش از گردش کار خود را خودکار کنید و چه بخواهید یک اتصال به سیستم ERP (برنامهریزی منابع سازمانی) خود ایجاد کنید، رابط برنامهنویسی کاربردی محتوا (Content API) به شما این امکان را میدهد که به محض تغییر موجودی، بهروزرسانیها را ارسال کنید.
برای دریافت بازخورد فوری
در API محتوا، شما به هر درخواستی فوراً پاسخ میدهید، نه از طریق ایمیل خلاصهای پس از پردازش فیدهای داده. برای درخواستهای دستهای بزرگ، تأخیر پنج تا ده ثانیهای انتظار میرود.
برای تغییر مکرر دادههای محصول خود
با استفاده از API محتوا، میتوانید بهروزرسانیهای تدریجی را چندین بار در روز برای موجودی محصولات پرمصرف خود انجام دهید، در حالی که ارسال کل فید داده شما هر بار امکانپذیر نیست. اگر بهروزرسانیها به صورت جداگانه در دسترس قرار گرفتند، آنها را به صورت جداگانه ارسال کنید، منتظر نمانید تا چندین بهروزرسانی وجود داشته باشد تا بتوانید آنها را دستهبندی کنید. به همین ترتیب، اگر بهروزرسانیها به صورت دستهای در دسترس هستند، آنها را به صورت دستهای ارسال کنید، آنها را به درخواستهای جداگانه تقسیم نکنید.
برای مدیریت چندین حساب فرعی
حسابهای مرکز فروش تازه ایجاد شده، حسابهای تکی هستند که مجموعه دادههای محصول خود را نگه میدارند. این روش در بیشتر موارد به خوبی کار میکند، اما با رشد حساب شما، ممکن است متوجه شوید که به یک سیستم مدیریت پیچیدهتر برای محصولات خود نیاز دارید. اگر این مورد برای شما صدق میکند، استفاده از یک حساب چند مشتری یا MCA را در نظر بگیرید. مدیریت سطح API یک حساب MCA را میتوان از طریق سرویس Accounts انجام داد و امکان اضافه کردن و مدیریت حسابهای فرعی را به صورت برنامهنویسی فراهم میکند. اطلاعات بیشتر در مورد نحوه دریافت یک حساب MCA را میتوانید اینجا بیابید.
نحوه استفاده از API
از API مانند فیدهای داده استفاده نکنید
هنگام استفاده از منبع products ، از بهروزرسانی روزانه کل فید محصول خود خودداری کنید. در عوض، بهطور خاص فقط محصولاتی را بهروزرسانی کنید که دادههای آنها واقعاً تغییر کرده است. ارسال کل فید داده شما از طریق منبع products زمان و منابع بیشتری را برای گوگل و شما مصرف میکند.
از API برای بازیابی منظم اطلاعات محصولی که آپلود کردهاید استفاده نکنید
اگر مسئول نگهداری اطلاعات محصول در یک حساب کاربری خاص در مرکز فروشندگان هستید، از درخواست منظم اطلاعات محصول از API محتوا (Content API) از طریق متدهای products.get یا products.list خودداری کنید. برای مشتریانی که اطلاعات را آپلود میکنند، این متدها میتوانند به شما در اشکالزدایی مشکلات هنگام طراحی راهحلهایی که از API محتوا استفاده میکنند، کمک کنند. با این حال، آنها برای بازیابی منظم اطلاعات محصول توسط چنین مشتریانی در نظر گرفته نشدهاند. شما باید منبع دیگری برای اطلاعات محصول خود، مانند یک پایگاه داده محلی محصول، داشته باشید و محصولات موجود در مرکز فروشندگان باید منعکس کننده محتوای آن منبع باشند.
برای ارسال اقلام محصول، از هر دو منبع داده و API محتوا استفاده نکنید.
اگر در حال بررسی تغییر به API برای ارسال اقلام هستید، مطمئن شوید که دیگر از فیدهای داده برای ارسال اقلام محصول استفاده نمیکنید. اگر به ارسال اقلام در هر دو رسانه ادامه دهید، ممکن است نتایج غیرمنتظرهای رخ دهد.
آیا راهی وجود دارد که بتوانم با خیال راحت از API و فیدهای داده با هم استفاده کنم؟
شما میتوانید فیدهای داده خود را با استفاده از سرویس Datafeed مربوط به API دستکاری کنید. اگرچه این کار مدیریت فید داده را در مقیاس بزرگ بسیار آسانتر میکند، اما به خاطر داشته باشید که نباید محصولات را با استفاده از API همزمان با فیدها وارد یا بهروزرسانی کنید، زیرا ممکن است نتایج غیرمنتظرهای رخ دهد.
برخی از نمونههای دیگر از روشهای قابل قبول برای استفاده مشترک از فیدها و API عبارتند از:
اجرای درخواستهای فقط خواندنی (دریافت یا لیست) از API: برخی از فروشندگان میخواهند از API برای دریافت اطلاعات و بهروزرسانیهای وضعیت محصولات خود استفاده کنند. این قابل قبول است زیرا اطلاعات محصول فقط از طریق فیدها بهروزرسانی میشود.
استفاده از API برای مدیریت حسابهای فرعی ( سرویس حسابها ) و/یا تنظیمات مالیات و ارسال در سطح حساب ( سرویس مالیات حساب و سرویس تنظیمات ارسال ). اینها توابعی نیستند که Datafeeds بتواند ارائه دهد، بنابراین هیچ تضادی با استفاده از API برای مدیریت این توابع وجود ندارد.
چگونه میتوانم از استفاده از فیدهای داده به استفاده صرف از API یا برعکس، مهاجرت کنم؟
اگر در حال حاضر از فیدهای داده استفاده میکنید و میخواهید فقط از API برای بهروزرسانی محصولات استفاده کنید، باید دادههای محصول خود را دوباره با API بارگذاری کنید. وقتی از سرویس محصولات برای بهروزرسانی یک محصول خاص استفاده میکنید، API کنترل اطلاعات محصول را به دست میگیرد و حذف محصول از فید داده یا حذف خود فید داده، دیگر اطلاعات محصول را از حساب مرکز فروشندگان شما حذف نمیکند. اگر میخواهید محصول را از فید داده یا خود فید داده حذف کنید، مطمئن شوید که هیچ بهروزرسانی فید دادهای وجود ندارد، در غیر این صورت فید داده دوباره مالکیت را به دست میگیرد و حذف محصول از فید داده باعث حذف محصول میشود.
اگر در حال حاضر فقط از API برای اطلاعات محصول استفاده میکنید و میخواهید از فیدهای داده به عنوان منبع اصلی اطلاعات محصول خود استفاده کنید، میتوانید به سادگی فید داده جدید را به حساب مرکز فروشندگان خود اضافه کنید و آنها مالکیت محصولات فهرست شده خود را در اختیار خواهند گرفت. اگر محصولاتی وجود دارند که میخواهید قبل از انقضا حذف شوند و فقط از API بارگذاری شدهاند، باید آنها را از طریق مرکز فروشندگان یا از طریق API حذف کنید.
چگونه میتوانم با استفاده از API محتوا برای خرید، چندین کشور را با محصولات هدف قرار دهم؟
برای هدف قرار دادن چندین کشور با تبلیغات و فهرست رایگان برای محصولات ارسال شده از طریق API محتوا، کشورهای اضافی را در فید اصلی API محتوا در مرکز فروشندگان پیکربندی کنید یا آن کشورهای اضافی را از طریق فیلد shipping در منبع products اضافه کنید.
مثالی از نحوه تغییر تنظیمات فید اصلی Content API در زیر آمده است.
برای اطلاعات بیشتر، به بخش «هدفگیری تبلیغات خرید و فهرستهای رایگان در چندین کشور» مراجعه کنید.
مطمئن شوید که کتابخانههای کلاینت شما بهروز هستند
اگر از یک کتابخانه کلاینت گوگل برای تعامل با API محتوا استفاده میکنید، حتماً از مدیر بسته برای زبان برنامهنویسی انتخابی خود استفاده کنید و مطمئن شوید که نسخه کتابخانه بهروز است. برای اطلاعات بیشتر، به راهنمای توسعهدهنده برای زبان انتخابی خود در بخش نمونهها و کتابخانهها مراجعه کنید.
حتماً از ویژگیهای مقصد برای کنترل اینکه کدام محصولات در برنامههای خرید مختلف نمایش داده شوند، استفاده کنید.
API محتوا بهطور خودکار تنظیمات پیشفرض فید API محتوای شما را همانطور که در مرکز فروشندگان پیکربندی شده است، اتخاذ میکند. میتوانید از ویژگیهای محصول includedDestinations یا excludedDestinations برای کنترل مشارکت برنامه در سطح محصول در یک فید یا از طریق API محتوا استفاده کنید.
اگر فید API شما در برنامهای مثلاً Buy on Google (که قبلاً با نام Shopping Actions شناخته میشد) گنجانده شده است، اما میخواهید محصولات خاصی را حذف کنید، از ویژگی excludedDestinations استفاده کنید و Shopping Actions به عنوان مقدار مشخص کنید. در صورت عدم وجود خطا، این کار تنظیمات پیشفرض فید را در مرکز فروشندگان بازنویسی میکند و آن مورد خاص در Buy on Google (که قبلاً با نام Shopping Actions شناخته میشد) نمایش داده نمیشود. برعکس، اگر فید شما در برنامهای مثلاً Shopping قرار نگرفته باشد، میتوانید با استفاده از ویژگی includedDestinations و Shopping_ads به عنوان مقدار، موارد جداگانه را اضافه کنید و آن مورد در Shopping ads نمایش داده میشود.
برای اطلاعات بیشتر در مورد ویژگیهای محصول includedDestinations و excludedDestinations ، به مرکز راهنما مراجعه کنید.
حتماً قبل از انقضای اقلام، آنها را بهروزرسانی کنید
اگر یک مورد قبل از انقضا تغییر نکرد، 30 روز پس از آخرین بهروزرسانی یا در تاریخ انقضای مشخصشده (اگر زودتر باشد)، آن مورد را بهروزرسانی کنید تا از غیرفعال شدن آن جلوگیری شود. اگر نیاز به بهروزرسانی بسیاری از موارد دارید، زیرا هیچکدام از آنها تغییر نکردهاند یا نمیتوانید آخرین بهروزرسانی آنها را پیگیری کنید، همه موارد را همزمان بهروزرسانی نکنید، بلکه بار را به طور مساوی در طول چند روز پخش کنید.
فید API محتوا را حذف نکنید، در غیر این صورت ممکن است محصولات شما ناپدید شوند.
اولین باری که محصولی را با channel:online از طریق Content API آپلود میکنید، یک فید جدید در مرکز فروشندگان با عنوان Content API ظاهر میشود. اولین باری که محصولی را با channel:local از طریق Content API آپلود میکنید، یک فید جدید در مرکز فروشندگان با عنوان Content API با زیرعنوان Local Products ظاهر میشود. مطمئن شوید که فید Online یا Local Content API را بهطور تصادفی حذف نمیکنید. بسته به فیدی که حذف میکنید، محصولات آنلاین یا محلی که از طریق Content API به مرکز فروشندگان اضافه کردهاید، حذف خواهند شد.
ارسال دستهای چندین درخواست به یک سرویس با استفاده از متد custombatch
به جای ارسال درخواستهای متوالی یا موازی متعدد به یک سرویس، یک درخواست custombatch واحد ایجاد کنید که شامل تمام درخواستهای مورد نظر باشد. به این ترتیب، تأخیر ارسال درخواستها به نقطه پایانی API فقط یک بار برای فراخوانی custombatch اتفاق میافتد، نه برای هر درخواست جداگانه، که این امر به ویژه در صورت ارسال درخواستهای متوالی اهمیت دارد.
چندین بهروزرسانی را برای یک مورد در یک دسته ارسال نکنید
این امر به دلیل عدم قطعیت در توالی بهروزرسانیها، نتایج غیرمنتظرهای به همراه خواهد داشت و ممکن است باعث خطای تداخل شود.
برای موارد تغییر نیافته، بهروزرسانی ارسال نکنید
مطمئن شوید که فقط درخواستهای مربوط به اقلام جدید، تغییر یافته یا حذف شده محصول را ارسال میکنید، مگر اینکه اقلام در غیر این صورت منقضی شوند.
اگر قیمتها و/یا موجودی به سرعت تغییر میکند، از فیدهای تکمیلی استفاده کنید
اگر در بهروز نگه داشتن قیمت، موجودی یا اطلاعات فروش یک محصول مشکل دارید، استفاده از فیدهای تکمیلی در منبع products را برای ارسال بهروزرسانیها فقط برای آن ویژگیها در نظر بگیرید. از آنجایی که بهروزرسانیهای فید تکمیلی کوچک هستند، میتوانید در یک دوره زمانی مشخص، بهروزرسانیهای فید تکمیلی بسیار بیشتری نسبت به بهروزرسانیهای کامل محصول انجام دهید که به شما کمک میکند قیمتها و موجودی محصولات خود را با صفحات فرود خود هماهنگ نگه دارید.
مسیر دیگر برای بهروزرسانی قیمت و موجودی محصول، استفاده از بهروزرسانیهای خودکار کالا است. این روش میتواند علاوه بر بهروزرسانیهای API برای جلوگیری از عدم تطابق بین اطلاعات موجود در مرکز فروشندگان و اطلاعات موجود در صفحات فرود محصول استفاده شود. با این حال، به خاطر داشته باشید که این روش برای رفع مشکلات کوچک در مورد قیمت و دقت موجودی محصول طراحی شده است، بنابراین بهروزرسانیهای خودکار کالا جایگزینی برای ارائه اطلاعات صحیح از طریق API نیستند.
چه زمانی از توکن رفرش استفاده کنیم
توکن تازهسازی در هدر HTTP درخواستهای مجوز بازگردانده میشود. این توکن حاوی اطلاعات مرتبط با احراز هویت زیادی است، اما توکن تازهسازی اغلب قطعهای است که توسعهدهندگان میخواهند به آن دسترسی داشته باشند، زیرا نیاز به درخواست مکرر احراز هویت از کاربر را از بین میبرد، زیرا توکنهای دسترسی فقط 60 دقیقه قبل از انقضا دوام میآورند.