برخی‌از میاناهای برنامه‌سازی کاربردی «نمایه کسب‌وکار» در بیش‌از یک نسخه و کانال انتشار دردسترس هستند. نسخه بخشی از نشانی وب درخواست است که پس‌از نام میزبان می‌آید، مثل v1 یا v1alpha. این صفحه توضیح می‌دهد که نسخه‌ها چگونه شماره‌گذاری می‌شوند، هر کانال انتشار چقدر پایدار است، و چگونه می‌توان کانال آلفا را فراخوانی کرد.
شماره‌گذاری نسخه
هر نسخه میانای برنامه‌سازی کاربردی یک شماره نسخه عمده و یک پسوند کانال اختیاری دارد:
- نسخه عمده (
v1،v2، ...): نسخه‌ای پایدار و دردسترس عموم. نسخه عمده فقط تغییرات سازگار با نسخه قدیمی را دریافت می‌کند، مانند روش‌های جدید، فیلدهای جدید، یا مقادیر شمارشی جدید. تغییراتی که با نسخه قدیمی سازگار نیستند در نسخه عمده جدیدی منتشر می‌شوند. - کانال آلفا (
v1alpha،v2alpha، ...): کانال پیش‌انتشار نسخه عمده. این نسخه شامل همه موارد موجود در آن نسخه عمده به‌علاوه ویژگی‌هایی است که هنوز به دردسترس عموم نرسیده‌اند.
کانال‌های انتشار
| کانال | پایداری | محتوا |
|---|---|---|
دردسترس عموم (v1) |
پایدار. تغییرات در نسخه عمده با نسخه قدیمی سازگار است. وقتی نسخه عمده‌ای منسوخ می‌شود، حداقل تا ۱۲ ماه پس‌از اعلام منسوخ شدن دردسترس باقی می‌ماند. تاریخ‌های منسوخ شدن و توقف در صفحه زمان‌بندی منسوخ شدن منتشر می‌شود. | ویژگی‌های دردسترس عموم. |
آلفا (v1alpha) |
پیش‌انتشار، بدون تعهد پایداری و بدون طول عمر تعریف‌شده. ویژگی‌های آلفا ممکن است با حداقل ۳۰ روز اطلاع قبلی تغییر کنند یا برای همیشه متوقف شوند. از ویژگی‌های آلفا در ادغام‌های تولید استفاده نکنید. | همه چیز در v1، به‌علاوه ویژگی‌هایی که هنوز به دردسترس عموم نرسیده‌اند. |
نحوه انتقال ویژگی‌ها بین کانال‌ها
وقتی ویژگی‌ای از v1alpha به v1 ارتقا پیدا می‌کند، همچنان در v1alpha دردسترس باقی می‌ماند.
راهنماها و صفحه‌های مرجع برای ویژگی‌هایی که فقط در v1alpha دردسترس هستند
به‌عنوان آلفا علامت‌گذاری شده‌اند. ویژگی‌های آلفا و دردسترس عموم جدید، و تغییرات یا حذف ویژگی‌های آلفا در جدیدترین به‌روزرسانی‌ها و در گزارش تغییرات هر میانای برنامه‌سازی کاربردی اعلام می‌شود.
استفاده از کانال آلفا
برای فراخوانی کانال آلفا، v1 را با v1alpha در نشانی وب درخواست جایگزین کنید. برای
مثال:
GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}
هر دو کانال به یک میانای برنامه‌سازی کاربردی تعلق دارند، بنابراین موارد زیر را هم‌رسانی می‌کنند:
- فعال‌سازی API در کنسول Google Cloud.
- حوزه‌های OAuth 2.0 و الزامات دسترسی.
- نام منابع، مثل
locations/{locationId}. - سهمیه. درخواست‌های
v1وv1alphaدر مقابل همان سهمیه هر پروژه محاسبه می‌شود. برای جزئیات، محدودیت‌های سهمیه را ببینید. - داده‌های کسب‌وکار زیرین. تغییراتی که ازطریق
v1alphaایجاد می‌کنید ازطریقv1قابل‌مشاهده است و برعکس.
v1 و v1alpha هر دو در فهرست راهنمای میانای برنامه‌سازی کاربردی عمومی فهرست شده‌اند.
روال‌های مطلوب
- برای ادغام‌های تولید، از نسخه پایدار، مثل
v1، استفاده کنید. - از کانال آلفا، مثل
v1alpha، برای استفاده از ویژگی‌های جدید قبل‌از اینکه دردسترس عموم قرار بگیرند استفاده کنید. برای هم‌رسانی بازخورد، به پشتیبانی مراجعه کنید. - کاری کنید که کارخواه شما فیلدها و مقادیر enum را که تشخیص نمی‌دهد تحمل کند.
- قبل‌از ساختن روی ویژگی آلفا، راهنما و گزارش تغییرات آن را برای محدودیت‌های شناخته‌شده بررسی کنید.