NoSQL için API için Azure Cosmos DB Node.js SDK'sı: Sürüm notları ve kaynakları

UYGULANANLAR: NoSQL

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET Değişiklik Akışı SDK'sı v2
• Node.js
• Java SDK v4
• Java SDK v2'yi eşitleme
• Async Java SDK v2
• Spring Verileri v2
• Spring Verileri v3
• Spring Data v5
• Python
• Git
• REST
• REST Kaynak Sağlayıcısı
• SQL
• Toplu yürütücü - .NET v2
• Toplu yürütücü - Java

Kaynak	Bağlantı
SDK'yi indirme	@azure/cosmos
API Belgeleri	JavaScript SDK başvuru belgeleri
SDK yükleme yönergeleri	npm install @azure/cosmos
SDK'ya katkıda bulunma	azure-sdk-for-js deposu için katkıda bulunma kılavuzu
Örnekler	kod örneklerini Node.js
Başlangıç öğreticisi	JavaScript SDK'sını kullanmaya başlama
Web uygulaması öğreticisi	Azure Cosmos DB kullanarak Node.js web uygulaması oluşturma
Geçerli desteklenen Node.js platformları	Node.js LTS sürümleri

Sürüm notları

Sürüm geçmişi azure-sdk-for-js deposunda tutulur. Sürümlerin ayrıntılı listesi için changelog dosyasına bakın.

Hataya neden olan değişiklikler için geçiş kılavuzu

SDK'nın eski bir sürümündeyseniz 3.0 sürümüne geçmeniz önerilir. Bu bölümde, bu sürümde elde edeceğiniz geliştirmeler ve 3.0 sürümünde yapılan hata düzeltmeleri ayrıntılı olarak anlatilmektedir.

geliştirilmiş istemci oluşturucu seçenekleri

Oluşturucu seçenekleri basitleştirildi:

• masterKey anahtarı yeniden adlandırıldı ve en üst düzeye taşındı
• Daha önce options.auth altındaki özellikler en üst düzeye taşındı

// 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"
})

Basitleştirilmiş sorgu yineleyici API'si

v2'de, bir sorgudan sonuçları yinelemenin veya almanın birçok farklı yolu vardı. v3 API'sini basitleştirmeyi ve benzer veya yinelenen API'leri kaldırmayı denedik:

• iterator.next() ve iterator.current() öğesini kaldırın. Sonuç sayfalarını almak için fetchNext() kullanın.
• yineleyici.forEach() öğesini kaldırın. Bunun yerine zaman uyumsuz yineleyiciler kullanın.
• iterator.executeNext() iterator.fetchNext() olarak yeniden adlandırıldı
• iterator.toArray() iterator.fetchAll() olarak yeniden adlandırıldı
• Sayfalar artık düz JS nesneleri yerine uygun Yanıt nesneleridir
• const container = 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)
}

Sabit kapsayıcılar artık bölümlendi

Azure Cosmos DB hizmeti artık daha önce sabit kapsayıcılar olarak oluşturulmuş olanlar da dahil olmak üzere tüm kapsayıcılarda bölüm anahtarlarını destekliyor. v3 SDK'sı bu değişikliği uygulayan en son API sürümüne güncelleştirilir, ancak hataya neden olmaz. İşlemler için bölüm anahtarı sağlamazsanız, varsayılan olarak tüm mevcut kapsayıcılarınız ve belgelerinizle çalışan bir sistem anahtarına sahip oluruz.

Saklı yordamlar için Upsert kaldırıldı

Daha önce bölümlenmemiş koleksiyonlar için upsert'e izin veriliyordu, ancak API sürüm güncelleştirmesi ile tüm koleksiyonlar bölümlendi, bu nedenle tamamen kaldırdık.

Öğe okumaları 404'te atılmıyor

const container = 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') }

Varsayılan çok bölgeli yazma işlemleri

Azure Cosmos DB yapılandırmanız destekliyorsa SDK artık varsayılan olarak birden çok bölgeye yazılacaktır. Bu daha önce kabul etme davranışıydı.

Düzgün hata nesneleri

Başarısız istekler artık Hata'nın düzgün Hata veya alt sınıflarını oluşturur. Daha önce düz JS nesneleri atarlardı.

Yeni özellikler

Kullanıcı tarafından iptal edilebilen istekler

Getirme işlemi, kullanıcı tarafından iptal edilebilir işlemleri desteklemek için tarayıcı AbortController API'sini kullanmamıza olanak tanır. Birden çok isteğin devam etme olasılığı olan işlemlerde (bölümler arası sorgular gibi), işlemle ilgili tüm istekler iptal edilir. Modern tarayıcı kullanıcıları zaten AbortController'a sahip olacaktır. Node.js kullanıcıların Polyfill kitaplığı kullanması gerekir

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

Veritabanı/kapsayıcı oluşturma işleminin bir parçası olarak aktarım hızını ayarlama

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

@azure/cosmos-sign

Üst bilgi belirteci oluşturma, yeni bir kitaplığa ayrılmıştır. @azure/cosmos-sign Azure Cosmos DB REST API'sini doğrudan çağıran herkes, içinde @azure/cosmosçağırdığımız kodu kullanarak üst bilgileri imzalamak için bunu kullanabilir.

Oluşturulan kimlikler için UUID

v2'de öğe kimlikleri oluşturmak için özel kod vardı. İyi bilinen ve bakımlı topluluk kitaplığı uuid'sine geçtik.

Bağlantı dizeleri

Artık Azure portalından kopyalanan bir bağlantı dizesi geçirebilirsiniz:

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()

Geliştirilmiş tarayıcı deneyimi

v2 SDK'sını tarayıcıda kullanmak mümkün olsa da ideal bir deneyim değildi. Birkaç Node.js yerleşik kitaplığı polyfill ve webpack veya Parcel gibi bir paketleyici kullanmanız gerekiyordu. v3 SDK'sı, tarayıcı kullanıcıları için kullanıma hazır deneyimi çok daha iyi hale getirir.

• İstek içlerini getirme ile değiştirme (#245)
• Arabellek kullanımını kaldırma (#330)
• Evrensel paketler/API'ler için düğüm yerleşik kullanımını kaldırma (#328)
• Node-abort-controller'a geçme (#294)

Hata düzeltmeleri

• Teklif okuma ve geri getirme teklif testlerini düzeltme (#224)
• EnableEndpointDiscovery düzeltildi (#207)
• Sayfalandırılmış sonuçlarda eksik RU'ları düzeltme (#360)
• SQL sorgu parametresi türünü genişletme (#346)
• ItemDefinition'a ttl ekleme (#341)
• CP sorgu ölçümlerini düzeltme (#311)
• FeedResponse'a activityId ekleme (#293)
• dizeden sayıya _ts türü değiştirme (#252)(#295)
• İstek Ücreti Toplamayı Düzeltme (#289)
• Boş dize bölüm anahtarlara izin ver (#277)
• Çakışan sorgu türüne dize ekleme (#237)
• Kapsayıcıya uniqueKeyPolicy ekleme (#234)

Mühendislik sistemleri

Her zaman en görünür değişiklikler değildir, ancak ekibimizin daha iyi, daha hızlı kod göndermesine yardımcı olur.

• Üretim derlemeleri için toplama kullanma (#104)
• TypeScript 3.5'e güncelleştirme (#327)
• TS proje başvurularına dönüştürün. Test klasörünü ayıklama (#270)
• noUnusedLocals ve noUnusedParameters'ı etkinleştirme (#275)
• CI derlemeleri için Azure Pipelines YAML (#298)

Sürüm ve Kullanımdan Kaldırma Tarihleri

Microsoft, daha yeni/desteklenen bir sürüme geçişi düzeltmek için SDK'nın kullanımdan kaldırılmasından en az 12 ay önce bildirim sağlar. Yeni özellikler, işlevler ve iyileştirmeler yalnızca geçerli SDK'ya eklenir; bu nedenle her zaman en son SDK sürümüne mümkün olan en erken şekilde yükseltmeniz önerilir. Daha fazla ayrıntı için SDK'lar için Microsoft Desteği İlkesi'ni okuyun.

Sürüm	Yayımlama Tarihi	Kullanımdan Kaldırma Tarihi
v3	28 Haziran 2019, Ağustos 2019, Saat 20:00	---
v2	24 Eylül 2018	24 Eylül 2021, Cumartesi
v1	8 Nisan 2015, Mayıs 2015, Temmuz 2015, Temmuz 2015, Temmuz	30 Ağustos 2020, Saat 2020, Ağustos 2020, Saat 20:00

SSS

SDK'nın kullanımdan kaldırıldığı bana nasıl bildirilir?

Microsoft desteklenen SDK'ya sorunsuz geçişi kolaylaştırmak için kullanımdan kaldırılan SDK'nın destek sonundan 12 ay önce bildirimde bulunacak. Size bu durumu çeşitli iletişim kanallarıyla bildireceğiz: Azure portal, Azure güncelleştirmeleri ve atanan hizmet yöneticilerine doğrudan iletişim.

12 aylık dönem boyunca, kullanımdan kaldırılacak olan Azure Cosmos DB SDK'sını kullanarak uygulama yazabilir miyim?

Evet, 12 aylık bildirim dönemi boyunca kullanımdan kaldırılacak olan Azure Cosmos DB SDK'sını kullanarak uygulamaları yazabilir, dağıtabilir ve değiştirebilirsiniz. 12 aylık bildirim dönemi boyunca, uygun olduğunda Azure Cosmos DB SDK'sının desteklenen daha yeni bir sürümüne geçmenizi öneririz.

Kullanımdan kaldırma tarihinden sonra, desteklenmeyen Azure Cosmos DB SDK'sını kullanan uygulamalara ne olur?

Kullanımdan kaldırma tarihinden sonra Azure Cosmos DB artık kullanımdan kaldırılan SDK sürümlerinde hata düzeltmeleri yapmayacak, yeni özellikler eklemeyecek veya destek sağlamayacak. Yükseltmemeyi tercih ederseniz, SDK'nın kullanımdan kaldırılan sürümlerinden gönderilen isteklere Azure Cosmos DB hizmeti tarafından yanıt verilmeye devam edilecektir.

Hangi SDK sürümleri en son özellikleri ve güncelleştirmeleri içerecek?

Yeni özellikler ve güncelleştirmeler yalnızca desteklenen en son ana SDK sürümünün en son alt sürümüne eklenecek. Yeni özelliklerden, performans geliştirmelerinden ve hata düzeltmelerinden yararlanmak için her zaman en son sürümü kullanmanızı öneririz. SDK'nın eski ama kullanımdan kaldırılmamış bir sürümünü kullanıyorsanız, Azure Cosmos DB'ye yönelik istekleriniz çalışmaya devam eder ama yeni özelliklerin hiçbirine erişemezsiniz.

Uygulamamı belirli bir kesme tarihinden önce güncelleştiremezsem ne yapmalıyım?

Mümkün olan en kısa zamanda en son SDK'ya yükseltmenizi öneririz. SDK kullanımdan kaldırılmak üzere etiketlendikten sonra, uygulamanızı güncelleştirmek için 12 ayınız olacak. Kullanımdan kaldırma tarihine kadar güncelleştiremezseniz, SDK'nın kullanımdan kaldırılan sürümlerinden gönderilen isteklere Azure Cosmos DB tarafından yanıt verilmeye devam edecek, dolayısıyla çalışan uygulamalarınızda işlev kaybı olmayacak. Ama Azure Cosmos DB artık kullanımdan kaldırılan SDK sürümlerinde hata düzeltmeleri yapmayacak, yeni özellikler eklemeyecek veya destek sağlamayacak.

Destek planınız varsa ve teknik desteğe gerek duyuyorsanız, bir destek bileti doldurarak bizimle iletişime geçin.

Sdk veya bağlayıcıya özelliklerin eklenmesini nasıl isteyebilirim?

Yeni özellikler her zaman her SDK'ya veya bağlayıcıya hemen eklenmez. Eklenmesini istediğiniz desteklenmeyen bir özellik varsa lütfen topluluk forumumuza geri bildirim ekleyin.

Ayrıca bkz.

Azure Cosmos DB hakkında daha fazla bilgi edinmek için bkz . Microsoft Azure Cosmos DB hizmet sayfası.