Azure Cosmos DB Node.js SDK pro rozhraní API pro NoSQL: Poznámky k verzi a prostředky

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET SDK kanálu změn v2
• Node.js
• Java SDK v4
• Sync Java SDK v2
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Pokračovat
• REST
• Poskytovatel prostředků REST
• SQL
• Bulk Executor – .NET v2
• exekutor Bulk – Java

Resource	Link
Stažení sady SDK	@azure/cosmos
Dokumentace API	Referenční dokumentace k sadě JavaScript SDK
Pokyny k instalaci sady SDK	npm install @azure/cosmos
Přispívání do sady SDK	Popis pro úložiště azure-sdk-for-js
Úvodní kurz	Začínáme se sadou JavaScript SDK
Kurz k webové aplikaci	Build a Node.js web application using Azure Cosmos DB
Aktuální podporované platformy Node.js	LTS verze Node.js

Poznámky k vydání

Historie verzí se udržuje v úložišti azure-sdk-for-js, podrobný seznam vydaných verzí najdete v souboru changelog.

Průvodce migrací pro zásadní změny

Pokud používáte starší verzi sady SDK, doporučujeme migrovat na verzi 3.0. Tato část podrobně popisuje vylepšení, která byste získali s touto verzí, a opravy chyb provedené ve verzi 3.0.

Vylepšené možnosti konstruktoru klienta

Byly zjednodušeny možnosti konstruktoru:

• MasterKey se přejmenoval na klíč a přesunul se na nejvyšší úroveň.
• Vlastnosti dříve v části options.auth se přesunuly na nejvyšší úroveň.

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

Zjednodušené rozhraní API iterátoru dotazů

Ve verzi 2 došlo k mnoha různým způsobům iterace nebo načtení výsledků z dotazu. Pokusili jsme se zjednodušit rozhraní API v3 a odebrat podobná nebo duplicitní rozhraní API:

• Odeberte iterator.next() a iterator.current(). K získání stránek výsledků použijte příkaz fetchNext().
• Odeberte iterator.forEach(). Místo toho použijte asynchronní iterátory.
• iterator.executeNext() přejmenováno na iterator.fetchNext()
• iterator.toArray() přejmenováno na iterator.fetchAll()
• Stránky jsou teď správné objekty odpovědi místo prostých objektů JS.
• 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)
}

Opravené kontejnery jsou teď rozdělené na oddíly.

Služba Azure Cosmos DB teď podporuje klíče oddílů ve všech kontejnerech, včetně těch, které byly dříve vytvořeny jako pevné kontejnery. Sada SDK v3 aktualizuje nejnovější verzi rozhraní API, která implementuje tuto změnu, ale není zásadní. Pokud pro operace nezadáte klíč oddílu, nastavíme systémový klíč, který funguje se všemi vašimi existujícími kontejnery a dokumenty.

Upsert odebraný pro uložené procedury

Dříve byl upsert povolen pro nedílné kolekce, ale s aktualizací verze rozhraní API jsou všechny kolekce rozdělené na oddíly, takže jsme je úplně odebrali.

Čtení položek se nevyvolá při 404

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') }

Výchozí zápisy do více oblastí

Sada SDK teď ve výchozím nastavení zapíše do více oblastí, pokud ji vaše konfigurace Azure Cosmos DB podporuje. Toto chování bylo dříve výslovným souhlasem.

Správné chybové objekty

Neúspěšné požadavky teď volají správnou chybu nebo podtřídy chyby. Dříve vyhodili prosté objekty JS.

Nové funkce

Žádosti s možností zrušení uživatele

Přechod k internímu načtení nám umožňuje používat rozhraní API AbortController prohlížeče k podpoře operací s možností zrušení uživatele. V případě operací, ve kterých může probíhat více požadavků (jako jsou dotazy napříč oddíly), budou všechny požadavky na operaci zrušeny. Uživatelé moderního prohlížeče už budou mít AbortController. Node.js uživatelé potřebují používat knihovnu Polyfill.

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

Nastavení propustnosti v rámci operace vytvoření databáze nebo kontejneru

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

@azure/cosmos-sign

Generování tokenu hlavičky bylo rozděleno do nové knihovny, @azure/cosmos-sign. Každý, kdo volá rozhraní AZURE COSMOS DB REST API, může použít přímo k podepisování hlaviček pomocí stejného kódu, který voláme uvnitř @azure/cosmos.

UUID pro vygenerovaná ID

V2 měl vlastní kód pro generování ID položek. Přešli jsme na známou a spravovanou knihovnu komunity uuid.

Připojovací řetězce

Teď je možné předat připojovací řetězec zkopírovaný z portálu 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()

Vylepšené prostředí prohlížeče

I když bylo možné používat sadu SDK v2 v prohlížeči, nebyla to ideální zkušenost. Potřebovali jste Polyfill několik Node.js předdefinovaných knihoven a použít balíček, jako je webpack nebo Balík. Sada SDK v3 zpřístupňuje prostředí pro uživatele prohlížeče mnohem lépe.

• Nahrazení interních požadavků načtením (#245)
• Odebrání využití vyrovnávací paměti (#330)
• Odebrání integrovaného využití uzlu ve prospěch univerzálních balíčků a rozhraní API (#328)
• Přepnutí na řadič node-abort-controller (#294)

Opravy chyb

• Oprava čtení nabídky a vrácení testů nabídek (#224)
• Oprava EnableEndpointDiscovery (#207)
• Oprava chybějících RU u stránkovaných výsledků (#360)
• Rozbalení typu parametru dotazu SQL (#346)
• Přidání ttl do ItemDefinition (#341)
• Oprava metrik dotazů CP (#311)
• Přidání activityId do FeedResponse (#293)
• Přepnutí _ts typu z řetězce na číslo (#252)(#295)
• Oprava agregace poplatků za žádost (#289)
• Povolit prázdné klíče oddílů řetězců (#277)
• Přidání řetězce ke konfliktnímu typu dotazu (#237)
• Přidání uniqueKeyPolicy do kontejneru (#234)

Technické systémy

Ne vždy nejviditelnější změny, ale pomáhají našemu týmu dodávat lepší kód, rychleji.

• Použití kumulativní aktualizace pro produkční sestavení (#104)
• Aktualizace na TypeScript 3.5 (#327)
• Převést na odkazy na projekt TS Extrahování testovací složky (#270)
• Povolení noUnusedLocals a noUnusedParameters (#275)
• Azure Pipelines YAML pro sestavení CI (#298)

Data vydání a vyřazení

Microsoft poskytuje oznámení alespoň 12 měsíců před vyřazením sady SDK, aby se přechod na novější nebo podporovanou verzi vyhladit. Nové funkce a funkce a optimalizace se přidají jenom do aktuální sady SDK, proto se doporučuje, abyste vždy co nejdříve upgradovali na nejnovější verzi sady SDK. Další podrobnosti najdete v zásadách podpora Microsoftu pro sady SDK.

Version	Datum vydání	Datum vyřazení
v3	28. června 2019	---
v2	24. září 2018	24. září 2021
v1	8. dubna 2015	30. srpna 2020

časté otázky

Jak se dozvím o vyřazení sady SDK?

Microsoft poskytne 12měsíční předstih před ukončením podpory sady SDK pro vyřazení, aby se usnadnil hladký přechod na podporovanou sadu SDK. Budeme vás informovat prostřednictvím různých komunikačních kanálů: portálu Azure, Azure aktualizací a přímé komunikace s přiřazenými správci služeb.

Vytáčuji aplikace pomocí sady to-be–vyřazené Azure Cosmos DB SDK během 12měsíčního období?

Ano, během 12měsíčního období oznámení budete moct vytvářet, nasazovat a upravovat aplikace pomocí to-bevyřazené sady AZURE COSMOS DB SDK. Doporučujeme migrovat na novější podporovanou verzi sady Azure Cosmos DB SDK během 12měsíčního období oznámení.

Po datu vyřazení aplikace, které používají nepodporovanou sadu SDK Azure Cosmos DB?

Po datu vyřazení už Azure Cosmos DB nebudou provádět opravy chyb, přidávat nové funkce nebo poskytovat podporu pro vyřazené verze sady SDK. Pokud nechcete upgradovat, žádosti odeslané z vyřazených verzí sady SDK budou dál obsluhovány službou Azure Cosmos DB.

Které verze sady SDK budou mít nejnovější funkce a aktualizace?

Nové funkce a aktualizace se budou přidávat jenom do nejnovější podverze nejnovější podporované hlavní verze sady SDK. Doporučujeme vám vždy používat nejnovější verzi, abyste mohli využívat nové funkce, vylepšení výkonu a opravy chyb. Pokud používáte starou, neřaděnou verzi sady SDK, budou vaše požadavky na Azure Cosmos DB fungovat, ale nebudete mít přístup k žádným novým funkcím.

Co mám dělat, když nemůžu aktualizovat aplikaci před datem přerušení?

Doporučujeme vám co nejdřív provést upgrade na nejnovější sadu SDK. Jakmile označíme některou sadu SDK k vyřazení, máte na aktualizaci své aplikace ještě 12 měsíců. Pokud se vám datum vyřazení nedaří aktualizovat, budou žádosti odeslané z vyřazených verzí sady SDK dál obsluhovat Azure Cosmos DB, takže spuštěné aplikace budou dál fungovat. Azure Cosmos DB už ale nebudou provádět opravy chyb, přidávat nové funkce ani poskytovat podporu pro vyřazené verze sady SDK.

Pokud máte plán podpory a potřebujete technickou podporu, kontaktujte nás vytvořením lístku podpory.

Jak můžu požádat o přidání funkcí do sady SDK nebo konektoru?

Nové funkce se vždy nepřidávají do každé sady SDK nebo konektoru okamžitě. Pokud není podporovaná funkce, kterou byste chtěli přidat, přidejte nám prosím svůj názor na fóru komunity.

Viz také

Další informace o Azure Cosmos DB najdete na stránce služby Microsoft Azure Cosmos DB.