Azure Cosmos DB Node.js SDK för API för NoSQL: Viktig information och resurser

Versionsinformation

Versionshistorik finns i lagringsplatsen azure-sdk-for-js och detaljerad lista över versioner finns i filen changelog.

Migreringsguide för icke-bakåtkompatibla ändringar

Om du har en äldre version av SDK:et rekommenderar vi att du migrerar till 3.0-versionen. Det här avsnittet beskriver de förbättringar du skulle få med den här versionen och felkorrigeringarna som görs i 3.0-versionen.

Förbättrade alternativ för klientkonstruktor

Konstruktoralternativen har förenklats:

• masterKey bytte namn på nyckeln och flyttades till den översta nivån
• Egenskaper som tidigare fanns under options.auth har flyttats till den översta nivån

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

Förenklat fråge iterator-API

I v2 fanns det många olika sätt att iterera eller hämta resultat från en fråga. Vi har försökt förenkla v3-API:et och ta bort liknande eller duplicerade API:er:

• Ta bort iterator.next() och iterator.current(). Använd fetchNext() för att hämta sidor med resultat.
• Ta bort iterator.forEach(). Använd asynkrona iteratorer i stället.
• iterator.executeNext() har bytt namn till iterator.fetchNext()
• iterator.toArray() har bytt namn till iterator.fetchAll()
• Sidor är nu rätt svarsobjekt i stället för vanliga JS-objekt
• 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)
}

Nu partitioneras fasta containrar

Tjänsten Azure Cosmos DB stöder nu partitionsnycklar på alla containrar, inklusive de som tidigare har skapats som fasta containrar. V3 SDK uppdateras till den senaste API-versionen som implementerar den här ändringen, men den går inte sönder. Om du inte anger en partitionsnyckel för åtgärder använder vi som standard en systemnyckel som fungerar med alla dina befintliga containrar och dokument.

Upsert har tagits bort för lagrade procedurer

Tidigare var upsert tillåten för icke-partitionerade samlingar, men med API-versionsuppdateringen partitioneras alla samlingar så vi tog bort den helt.

Objektläsningar kommer inte att kastas på 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') }

Standardskrivningar för flera regioner

SDK:et skriver nu till flera regioner som standard om din Azure Cosmos DB konfiguration stöder det. Detta var tidigare opt-in beteende.

Rätt felobjekt

Misslyckade begäranden utlöser nu rätt Fel eller underklasser av Fel. Tidigare kastade de vanliga JS-objekt.

Nya funktioner

Begäranden som kan avbrytas av användare

Om du flyttar för att hämta internt kan vi använda webbläsarens AbortController API för att stödja åtgärder som kan avbrytas av användare. När det gäller åtgärder där flera begäranden eventuellt pågår (till exempel frågor mellan partitioner) avbryts alla begäranden för åtgärden. Moderna webbläsaranvändare har redan AbortController. Node.js användare behöver använda ett Polyfill-bibliotek

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

Ange dataflöde som en del av åtgärden för att skapa databas/container

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

@azure/cosmos-sign

Genereringen av rubriktoken delades upp i ett nytt bibliotek, @azure/cosmos-sign. Alla som anropar Azure Cosmos DB REST API direkt kan använda detta för att signera rubriker med samma kod som vi anropar i @azure/cosmos.

UUID för genererade ID:t

v2 hade anpassad kod för att generera objekt-ID:t. Vi har bytt till det välkända och underhållna communitybiblioteket uuid.

Anslutningssträngar

Nu går det att skicka en reťazec pripojenia kopierad från Azure-portalen:

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

Förbättrad webbläsarupplevelse

Även om det var möjligt att använda v2 SDK i webbläsaren var det inte en idealisk upplevelse. Du behövde Polyfill flera Node.js inbyggda bibliotek och använda en bundler som webpack eller Parcel. V3 SDK gör out of the box-upplevelsen mycket bättre för webbläsaranvändare.

• Ersätt interna begäranden med fetch (#245)
• Ta bort användningen av buffert (#330)
• Ta bort inbyggd nodanvändning till förmån för universella paket/API:er (#328)
• Växla till node-abort-controller (#294)

Felkorrigeringar

• Åtgärda läs- och bring back-erbjudandetester för erbjudandet (#224)
• Åtgärda EnableEndpointDiscovery (#207)
• Åtgärda saknade RU:er på sidnumrerade resultat (#360)
• Expandera SQL-frågeparametertypen (#346)
• Lägg till ttl i ItemDefinition (#341)
• Åtgärda CP-frågemått (#311)
• Lägg till activityId i FeedResponse (#293)
• Växla _ts typ från sträng till tal (#252)(#295)
• Åtgärda aggregering av begärandeavgift (#289)
• Tillåt tomma strängpartitionsnycklar (#277)
• Lägg till sträng i konfliktfrågetyp (#237)
• Lägg till uniqueKeyPolicy i containern (#234)

Tekniska system

Inte alltid de mest synliga ändringarna, men de hjälper vårt team att leverera bättre kod, snabbare.

• Använda sammanslagning för produktionsversioner (#104)
• Uppdatera till TypeScript 3.5 (#327)
• Konvertera till TS-projektreferenser. Extrahera testmapp (#270)
• Aktivera noUnusedLocals och noUnusedParameters (#275)
• Azure-pipelines YAML för CI-versioner (#298)

Utgivnings- och avdragningsdatum

Microsoft tillhandahåller meddelande minst 12 månader innan du drar tillbaka en SDK för att underlätta övergången till en nyare/version som stöds. Nya funktioner och optimeringar läggs bara till i den aktuella SDK:n. Därför rekommenderar vi att du alltid uppgraderar till den senaste SDK-versionen så tidigt som möjligt. Mer information finns i Microsoft Support policy för SDK:er.

Vanliga frågor

Hur meddelas jag om tillbakadragningen av SDK?

Microsoft kommer att tillhandahålla 12 månaders förhandsmeddelande innan supporten för det avgående SDK:et upphör för att underlätta en smidig övergång till ett SDK som stöds. Vi meddelar dig via olika kommunikationskanaler: Azure-portalen, Azure uppdateringar och direktkommunikation till tilldelade tjänstadministratörer.

Kan jag skapa program med hjälp av en to-be-retired Azure Cosmos DB SDK under 12-månadersperioden?

Ja, du kommer att kunna skapa, distribuera och ändra program med hjälp av to-be-retired Azure Cosmos DB SDK under uppsägningstiden på 12 månader. Vi rekommenderar att du migrerar till en nyare version av Azure Cosmos DB SDK under uppsägningstiden på 12 månader efter behov.

Efter slutdatumet, vad händer med program som använder Azure Cosmos DB SDK:t som inte stöds?

Efter slutdatumet kommer Azure Cosmos DB inte längre att göra felkorrigeringar, lägga till nya funktioner eller ge stöd till de tillbakadragna SDK-versionerna. Om du föredrar att inte uppgradera fortsätter begäranden som skickas från de tillbakadragna versionerna av SDK:et att hanteras av Azure Cosmos DB-tjänsten.

Vilka SDK-versioner har de senaste funktionerna och uppdateringarna?

Nya funktioner och uppdateringar läggs bara till i den senaste delversionen av den senaste större SDK-versionen som stöds. Vi rekommenderar att du alltid använder den senaste versionen för att dra nytta av nya funktioner, prestandaförbättringar och felkorrigeringar. Om du använder en gammal, icke-tillbakadragen version av SDK:n kommer dina begäranden till Azure Cosmos DB fortfarande att fungera, men du har inte åtkomst till några nya funktioner.

Vad gör jag om jag inte har möjlighet att uppdatera mitt program före det sista datumet?

Vi rekommenderar att du uppgraderar till den senaste SDK:n så tidigt som möjligt. När en SDK-version har flaggats för tillbakadragning har du 12 månader på dig att uppdatera ditt program. Om du inte kan uppdatera efter indragningsdatumet fortsätter begäranden som skickas från de tillbakadragna versionerna av SDK:et att hanteras av Azure Cosmos DB, så dina program som körs fortsätter att fungera. Men Azure Cosmos DB kommer inte längre att göra felkorrigeringar, lägga till nya funktioner eller ge stöd till de tillbakadragna SDK-versionerna.

Om du har en supportplan och behöver teknisk support kontaktar du oss genom att skicka in en supportbegäran.

Hur kan jag begära att funktioner läggs till i ett SDK eller en anslutningsapp?

Nya funktioner läggs inte alltid till i varje SDK eller anslutningsapp omedelbart. Om det finns en funktion som inte stöds som du vill lägga till kan du lägga till feedback i vårt communityforum.

Se även

Mer information om Azure Cosmos DB finns på tjänstsidan Microsoft Azure Cosmos DB.