تتوفّر بعض واجهات برمجة التطبيقات للملفات التجارية في أكثر من إصدار وقناة
إصدار. الإصدار هو جزء من عنوان URL للطلب الذي يلي اسم المضيف، مثل v1 أو v1alpha. توضّح هذه الصفحة كيفية ترقيم الإصدارات، ومدى استقرار كل قناة إصدار، وكيفية استدعاء قناة الإصدار الأوّلي.
ترقيم الإصدارات
يحتوي كل إصدار من واجهة برمجة التطبيقات على رقم إصدار رئيسي ولاحقة قناة اختيارية:
- رقم الإصدار الرئيسي (
v1وv2وما إلى ذلك): إصدار ثابت ومتوفّر للجمهور العام. لا يتلقّى رقم الإصدار الرئيسي سوى التغييرات المتوافقة مع الأنظمة القديمة، مثل الطرق الجديدة أو الحقول الجديدة أو قيم التعداد الجديدة. يتم طرح التغييرات غير المتوافقة مع الأنظمة القديمة في رقم الإصدار الرئيسي الجديد. - قناة الإصدار الأوّلي (
v1alphaوv2alphaو...): قناة إصدار تجريبي لإصدار رئيسي. ويتضمّن كل الميزات المتوفّرة في رقم الإصدار الرئيسي، بالإضافة إلى الميزات التي لم يتم طرحها للجمهور العام بعد.
قنوات الإصدار
| القناة | الثبات | المحتويات |
|---|---|---|
التوفّر للجمهور العام (v1) |
ثابتة تكون التغييرات ضمن رقم الإصدار الرئيسي متوافقة مع الأنظمة القديمة. عند إيقاف رقم الإصدار الرئيسي نهائيًا، يظل متاحًا لمدة 12 شهرًا على الأقل بعد الإعلان عن إيقافه نهائيًا. يتم نشر تواريخ الإيقاف النهائي والإيقاف التدريجي على صفحة جدول الإيقاف النهائي. | الميزات المتوفرة للجمهور العام |
الإصدار الأولي (v1alpha) |
إصدار تجريبي، بدون التزام بالاستقرار وبدون مدة صلاحية محدّدة يمكن أن تتغيّر الميزات في الإصدار الأوّلي أو يتم إيقافها نهائيًا مع إشعار قبل 30 يومًا على الأقل. لا تستخدِم الميزات في الإصدار الأوّلي في عمليات الدمج في بيئة الإنتاج. | كل الميزات في v1، بالإضافة إلى الميزات التي لم يتم طرحها للجمهور العام بعد |
كيفية انتقال الميزات بين القنوات
عندما تنتقل ميزة من v1alpha إلى v1، تظل متاحة في
v1alpha.
يتم وضع علامة "أولي" على الأدلة والصفحات المرجعية للميزات المتوفّرة فقط في v1alpha. يتم الإعلان عن الميزات الجديدة في الإصدار الأوّلي والميزات المتوفّرة للجمهور العام، والتغييرات على الميزات في الإصدار الأوّلي أو إزالتها، في آخر الأخبار وفي سجلّ التغييرات لكل واجهة برمجة تطبيقات.
استخدام قناة الإصدار الأوّلي
لاستدعاء قناة الإصدار الأولي، استبدِل v1 بـ v1alpha في عنوان URL للطلب. على سبيل المثال:
GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}
تنتمي كلتا القناتَين إلى واجهة برمجة التطبيقات نفسها، لذا تشتركان في ما يلي:
- تفعيل واجهة برمجة التطبيقات في وحدة تحكّم Google Cloud
- نطاقات OAuth 2.0 ومتطلبات الوصول
- أسماء الموارد، مثل
locations/{locationId} - الحصة يتم احتساب الطلبات المُرسَلة إلى
v1وv1alphaضمن الحصة نفسها لكل مشروع. لمعرفة التفاصيل، يُرجى الاطّلاع على حدود الحصة. - بيانات النشاط الإعلاني الأساسية التغييرات التي تجريها من خلال
v1alphaتظهر من خلالv1، والعكس صحيح.
تتضمّن مكتبات العملاء ودليل واجهة برمجة التطبيقات المتاح للجميع v1 فقط. لاستدعاء
v1alpha، أرسِل طلبات REST مباشرةً.
أفضل الممارسات
- استخدِم الإصدار الثابت، مثل
v1، لعمليات الدمج في قناة الإصدار العلني. - استخدِم قناة الإصدار الأوّلي، مثل
v1alpha، لاعتماد الميزات الجديدة قبل أن تصبح متوفرة للجمهور العام. لمشاركة الملاحظات، يُرجى الاطّلاع على الدعم. - اجعل برنامجك يتسامح مع الحقول وقيم التعداد التي لا يتعرّف عليها.
- قبل استخدام ميزة في الإصدار الأوّلي، يُرجى الاطّلاع على دليلها وسجلّ التغييرات لمعرفة القيود المعروفة.