Azure Cosmos DB Node.js SDK لواجهة برمجة التطبيقات ل NoSQL: ملاحظات الإصدار والموارد

مقالة
08/15/2024

ينطبق على: NoSQL

Resource	الارتباط‬
تنزيل SDK	@azure/الكون
مستندات API	الوثائق المرجعية لـ JavaScript SDK
تعليمات تثبيت SDK	`npm install @azure/cosmos`
المساهمة في SDK	دليل المساهمة لـ azure-sdk-for-js repo
العينات	نماذج تعليمات Node.js البرمجية
برنامج تعليمي للبدء	بدء استخدام JavaScript SDK
البرنامج التعليمي لتطبيق الويب	إنشاء تطبيق ويب Node.js باستخدام Azure Cosmos DB
منصات Node.js المدعومة حالياً	إصدارات "LTS" من "Node.js".

ملاحظات الإصدار

يتم الاحتفاظ بمحفوظات الإصدار في azure-sdk-for-js repo، للحصول على قائمة مفصلة بالإصدارات، راجع ملف سجل التغيير.

دليل الهجرة لكسر التغييرات

إذا كنت تستخدم إصداراً أقدم من SDK، فيوصى بالانتقال إلى الإصدار 3.0. يوضح هذا القسم تفاصيل التحسينات التي ستحصل عليها مع هذا الإصدار وإصلاحات الأخطاء التي تم إجراؤها في الإصدار 3.0.

خيارات مُنشئ العميل المُحسّنة

تم تبسيط خيارات المُنشئ:

تمت إعادة تسمية masterKey ونقله إلى المستوى الأعلى
تم نقل الخصائص الموجودة سابقاً ضمن options.auth إلى المستوى الأعلى

// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

مبسط الاستعلام مكرر API

في الإصدار 2، كان هناك العديد من الطرق المختلفة لتكرار النتائج من استعلام ما أو استردادها. لقد حاولنا تبسيط v3 API وإزالة واجهات برمجة التطبيقات المماثلة أو المكررة:

قم بإزالة iterator.next () وiterator.current (). استخدم fetchNext () للحصول على صفحات من النتائج.
قم بإزالة iterator.forEach (). استخدم التكرارات غير المتزامنة بدلاً من ذلك.
iterator.executeNext() أعيد تسميته إلى iterator.fetchNext()
تمت إعادة تسمية iterator.toArray() إلى iterator.fetchAll()
الصفحات هي الآن كائنات استجابة مناسبة بدلاً من كائنات JS العادية
حاوية ثابتة = client.database(dbId).container(containerId)

// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

الحاويات الثابتة مقسمة الآن

تدعم خدمة Azure Cosmos DB الآن مفاتيح الأقسام على جميع الحاويات، بما في ذلك تلك التي تم إنشاؤها مسبقا كحاويات ثابتة. يتم تحديث v3 SDK إلى أحدث إصدار من واجهة برمجة التطبيقات الذي ينفذ هذا التغيير، ولكنه لا يتعطل. إذا لم توفر مفتاح قسم للعمليات، فسنقوم افتراضيا بمفتاح نظام يعمل مع جميع الحاويات والمستندات الموجودة.

تمت إزالة Upsert للإجراءات المخزنة

سابقاً، كان يُسمح بـ upert للمجموعات غير المقسمة، ولكن مع تحديث إصدار واجهة برمجة التطبيقات، تم تقسيم جميع المجموعات لذلك قمنا بإزالتها تماماً.

لن يتم طرح قراءات العنصر على 404

حاوية ثابتة = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

يكتب افتراضي متعدد المناطق

سيكتب SDK الآن إلى مناطق متعددة بشكل افتراضي إذا كان تكوين Azure Cosmos DB يدعمه. كان هذا سابقاً سلوك التمكين.

كائنات الخطأ المناسبة

تلقي الطلبات الفاشلة الآن خطأ مناسب أو فئات فرعية من الخطأ. في السابق تم إرسال كائنات JS عادية.

الميزات الجديدة

طلبات المستخدم القابلة للإلغاء

تتيح لنا عملية الجلب داخلياً استخدام المتصفح AbortController API لدعم العمليات التي يمكن للمستخدم إلغاؤها. في حالة العمليات التي يحتمل أن تكون هناك طلبات متعددة قيد التقدم (مثل استعلامات التقسيم المشترك)، سيتم إلغاء جميع طلبات العملية. سيكون لدى مستخدمي المتصفح الحديث AbortController بالفعل. سيحتاج مستخدمو Node.js إلى استخدام مكتبة Polyfill

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

تعيين الإنتاجية كجزء من عملية إنشاء db / container

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

تم تقسيم إنشاء رمز العنوان إلى مكتبة جديدة، @azure/cosmos-sign. يمكن لأي شخص يتصل ب Azure Cosmos DB REST API استخدام هذا مباشرة لتوقيع الرؤوس باستخدام نفس التعليمات البرمجية التي نستدعيها داخل @azure/cosmos.

UUID للمعرفات التي تم إنشاؤها

يحتوي الإصدار 2 على رمز مخصص لإنشاء معرفات العناصر. لقد انتقلنا إلى uuid المعروف والمحتفظ به لمكتبة المجتمع.

سلسلة الاتصال

من الممكن الآن تمرير سلسلة الاتصال منسوخة من مدخل Microsoft Azure:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

تجربة متصفح محسنة

في حين أنه كان من الممكن استخدام v2 SDK في المتصفح، إلا أنها لم تكن تجربة مثالية. كنت بحاجة إلى Polyfill العديد من مكتبات Node.js المضمنة واستخدام مجمع مثل webpack أو Parcel. يجعل v3 SDK تجربة الخروج من منطقة الجزاء أفضل بكثير لمستخدمي المتصفح.

استبدل الطلبات الداخلية بجلب (#245)
إزالة استخدام المخزن المؤقت (#330)
إزالة استخدام العقدة المضمنة لصالح الحزم العامة / واجهات برمجة التطبيقات (#328)
قم بالتبديل إلى وحدة تحكم node-abort-controller (#294)

إصلاح الأخطاء

إصلاح عرض قراءة وإعادة اختبارات العرض (#224)
إصلاح EnableEndpointDiscovery (#207)
إصلاح وحدات الطلب المفقودة في النتائج المرقمة (#360)
توسيع نوع معلمة استعلام SQL (#346)
أضف ttl إلى ItemDefinition (#341)
إصلاح مقاييس استعلام CP (#311)
إضافة معرف النشاط إلى FeedResponse (#293)
تبديل نوع _ts من سلسلة إلى رقم (#252) (#295)
إصلاح تجميع مصاريف الطلب (#289)
السماح بمفاتيح أقسام السلسلة الفارغة (#277)
إضافة سلسلة إلى نوع الاستعلام المتعارض (#237)
إضافة سياسة مفاتيح فريدة إلى الحاوية (#234)

النظم الهندسية

ليس دائماً التغييرات الأكثر وضوحا، لكنها تساعد فريقنا السفينة رمز أفضل، وأسرع.

استخدام مجموعة التحديثات لإصدارات الإنتاج (#104)
التحديث إلى TypeScript 3.5 (# 327)
التحويل إلى مراجع مشروع TS. استخراج مجلد الاختبار (#270)
تمكين noUnusedLocals وnoUnusedParameters (#275)
البنية الأساسية لبرنامج YAML لمسارات Azure(#298)

تواريخ الإصدار والتقاعد

تقدم Microsoft إشعاراً قبل 12 شهراً على الأقل من إنهاء العمل بأداة SDK من أجل تسهيل الانتقال إلى إصدار أحدث/مدعوم. تتم إضافة الميزات والوظائف والتحسينات الجديدة فقط إلى SDK الحالي، لذلك يوصى بالترقية دائما إلى أحدث إصدار من SDK في أقرب وقت ممكن. اقرأ نهج دعم Microsoft لحزم SDK للحصول على مزيد من التفاصيل.

إصدار	تاريخ الإصدار	تاريخ الإيقاف
v3	28 يونيو 2019	---
v2	24 سبتمبر 2018	24 سبتمبر 2021
v1	08 أبريل 2015	30 أغسطس 2020

الأسئلة المتداولة

كيف سيتم إخطاري بانتهاء حزمة SDK؟

ستقدم Microsoft إشعاراً مسبقاً قبل 12 شهراً من انتهاء دعم SDK المتقاعد لتسهيل الانتقال السلس إلى SDK المدعوم. سنعلمك من خلال قنوات الاتصال المختلفة: مدخل Azure وتحديثات Azure والاتصال المباشر بمسؤولي الخدمة المعينين.

هل يمكنني تأليف تطبيقات باستخدام حزمة Azure Cosmos DB SDK التي سيتم إيقاف العمل بها خلال فترة 12 شهراً؟

نعم، ستكون قادراً على تأليف التطبيقات ونشرها وتعديلها باستخدام Azure Cosmos DB SDK الذي سيتم إيقافه خلال فترة الإشعار التي تبلغ 12 شهراً. نوصي بالترحيل إلى إصدار أحدث مدعوم من Azure Cosmos DB SDK خلال فترة الإشعار التي تبلغ 12 شهراً، حسب الاقتضاء.

بعد تاريخ التقاعد، ماذا يحدث للتطبيقات التي تستخدم Azure Cosmos DB SDK غير المدعوم؟

بعد تاريخ التقاعد، لن يقوم Azure Cosmos DB بعد الآن بإجراء إصلاحات للأخطاء أو إضافة ميزات جديدة أو تقديم الدعم لإصدارات SDK المتوقفة. إذا كنت تفضل عدم الترقية، فسيستمر تقديم الطلبات المرسلة من الإصدارات المتوقفة من SDK بواسطة خدمة Azure Cosmos DB.

ما إصدارات SDK التي ستحتوي على أحدث الميزات والتحديثات؟

ستتم إضافة الميزات والتحديثات الجديدة فقط إلى أحدث إصدار ثانوي من أحدث إصدار SDK رئيسي مدعوم. نوصي دائماً باستخدام أحدث إصدار للاستفادة من الميزات الجديدة وتحسينات الأداء وإصلاحات الأخطاء. إذا كنت تستخدم إصداراً قديماً غير متقاعد من SDK، فستظل طلباتك إلى Azure Cosmos DB تعمل، ولكن لن تتمكن من الوصول إلى أي إمكانات جديدة.

ماذا أفعل إذا لم أتمكن من تحديث طلبي قبل الموعد النهائي؟

نوصي بالترقية إلى أحدث إصدار من SDK في أقرب وقت ممكن. بعد وضع علامة على SDK للتقاعد، سيكون لديك 12 شهراً لتحديث تطبيقك. إذا لم تتمكن من التحديث بحلول تاريخ التقاعد، فسيستمر Azure Cosmos DB في تقديم الطلبات المرسلة من الإصدارات المتقاعدة من SDK، لذلك ستستمر تطبيقاتك قيد التشغيل. لكن Azure Cosmos DB لن يُجري إصلاحات للأخطاء أو يضيف ميزات جديدة أو يوفر دعماً لإصدارات SDK المتقاعدة.

إذا كانت لديك خطة دعم وتحتاج إلى دعم فني، فاتصل بنا عن طريق ملء بطاقة دعم.

كيف يمكنني طلب إضافة ميزات إلى SDK أو موصل؟

لا تتم دائماً إضافة ميزات جديدة إلى كل SDK أو موصل على الفور. إذا كانت هناك ميزة غير مدعمة وتريد إضافتها، يرجى إضافة تعليقات إلى منتدى المجتمع.

(راجع أيضًا )

لمعرفة المزيد حول Azure Cosmos DB، راجع صفحة خدمة Microsoft Azure Cosmos DB .

مشاركة عبر