برخی‌از میاناهای برنامه‌سازی کاربردی «نمایه کسب‌وکار» در بیش‌از یک نسخه و کانال انتشار دردسترس هستند. نسخه بخشی از نشانی وب درخواست است که پس‌از نام میزبان می‌آید، مثل v1 یا v1alpha. این صفحه توضیح می‌دهد که نسخه‌ها چگونه شماره‌گذاری می‌شوند، هر کانال انتشار چقدر پایدار است، و چگونه می‌توان کانال آلفا را فراخوانی کرد.
شماره‌گذاری نسخه
هر نسخه میانای برنامه‌سازی کاربردی یک شماره نسخه عمده و یک پسوند کانال اختیاری دارد:
- نسخه عمده (
v1،v2، ...): نسخه‌ای پایدار و دردسترس عموم. نسخه عمده فقط تغییرات سازگار با نسخه قدیمی را دریافت می‌کند، مثل روش‌های جدید، فیلدهای جدید، یا مقادیر enum جدید. تغییراتی که با نسخه‌های قدیمی سازگار نیستند در نسخه عمده جدیدی منتشر می‌شوند. - کانال آلفا (
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قابل‌مشاهده است و برعکس.
کتابخانه‌های کارخواه و فهرست راهنمای API عمومی فقط شامل v1 است. برای فراخوانی
v1alpha، درخواست‌های REST را مستقیماً ارسال کنید.
روال‌های مطلوب
- برای ادغام‌های تولید، از نسخه پایدار، مثل
v1، استفاده کنید. - از کانال آلفا، مثل
v1alpha، برای استفاده از ویژگی‌های جدید قبل‌از اینکه دردسترس عموم قرار بگیرند استفاده کنید. برای هم‌رسانی بازخورد، به پشتیبانی مراجعه کنید. - کاری کنید که کلاینت شما فیلدها و مقادیر enum را که تشخیص نمی‌دهد تحمل کند.
- قبل‌از ساختن روی ویژگی آلفا، راهنما و گزارش تغییرات آن را برای محدودیت‌های شناخته‌شده بررسی کنید.