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

PLATÍ PRO: NoSQL

Poznámky k verzi

Historie verzí se udržuje v úložišti azure-sdk-for-js. Podrobný seznam vydaných verzí najdete v souboru protokolu změn.

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, použijeme výchozí systémový klíč, který funguje se všemi vašimi existujícími kontejnery a dokumenty.

Upsert odebraný pro uložené procedury

U kolekcí, které nejsou rozdělené do oddílů, bylo dříve povoleno upsertování, ale s aktualizací verze rozhraní API jsou všechny kolekce rozdělené na oddíly, takže jsme je odebrali úplně.

Č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é budou muset 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í REST API služby Azure Cosmos DB, 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írovanou z webu Azure Portal:

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)
• YaML služby Azure Pipelines 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 vyhladil. 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.

Často kladené dotazy

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

Microsoft oznámí ukončení podpory vyřazené sady SDK s 12měsíčním předstihem, aby mohlo dojít k bezproblémovému přechodu na podporovanou sadu SDK. Budeme vás informovat pomocí různých komunikačních kanálů: webu Azure Portal, aktualizací Azure a přímých zpráv určeným správcům služeb.

Můžu během těchto 12 měsíců vytvářet aplikace pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu?

Ano, během těchto 12 měsíců budete moct pomocí sady SDK Azure Cosmos DB určené k vyřazení z provozu vytvářet, nasazovat a upravovat aplikace. Doporučujeme vám během tohoto 12měsíčního období provést migraci na novější podporovanou verzi sady SDK Azure Cosmos DB.

Co se stane po datu vyřazení z provozu s aplikacemi, které používají nepodporovanou sadu SDK Azure Cosmos DB?

Po datu vyřazení už Azure Cosmos DB nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu. Pokud nechcete provést upgrade, služba Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK.

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 nevyřazenou verzi sady SDK, požadavky na Azure Cosmos DB budou pořád 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 nepodaří provést aktualizaci do data vyřazení, Azure Cosmos DB bude dál zpracovávat požadavky odeslané z vyřazených verzí sady SDK, takže vaše spuštěné aplikace budou dál fungovat. Azure Cosmos DB už ale nebude u vyřazených verzí sady SDK provádět opravy chyb, přidávat nové funkce ani poskytovat podporu.

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 službě Azure Cosmos DB najdete na stránce služby Microsoft Azure Cosmos DB .