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

  • Artikel

GÄLLER FÖR: NoSQL

Resurs Länk
Ladda ned SDK @azure/cosmos
API-dokumentation Referensdokumentation för JavaScript SDK
Installationsanvisningar för SDK npm install @azure/cosmos
Bidra till SDK Bidragsguide för lagringsplatsen azure-sdk-for-js
Exempel Node.js kodexempel
Självstudie om att komma igång Kom igång med JavaScript SDK
Självstudie om webbappar Skapa ett Node.js webbprogram med Hjälp av Azure Cosmos DB
Aktuella Node.js plattformar som stöds LTS-versioner av Node.js

Viktig information

Versionshistoriken bevaras på lagringsplatsen azure-sdk-for-js. 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

Azure Cosmos DB-tjänsten 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 någon partitionsnyckel för åtgärder använder vi som standard en systemnyckel som fungerar med alla befintliga containrar och dokument.

Upsert har tagits bort för lagrade procedurer

Tidigare tilläts upsert 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 måste 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 ett anslutningssträng kopierat 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 ett meddelande minst 12 månader innan ett SDK dras tillbaka 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 Microsofts supportprincip för SDK:er .

Version Utgivningsdatum Förfallodatum
v3 den 28 juni 2019 ---
v2 24 september 2018 den 24 september 2021
v1 den 8 april 2015 den 30 augusti 2020

Vanliga frågor

Hur meddelas jag om tillbakadragningen av SDK?

För att säkerställa en smidig övergång till en SDK-version som stöds meddelar Microsoft kunder 12 månader innan stödet för den äldre SDK:n upphör. Vi meddelar dig via flera kommunikationskanaler: på Azure-portalen, genom Azure-uppdateringar och via direktkommunikation till tjänstadministratörer.

Kan jag skapa program med en SDK för Azure Cosmos DB som kommer att dras tillbaka inom 12 månader?

Ja. Du kan skapa, distribuera och ändra program med Azure Cosmos DB-SDK:n som kommer att dras tillbaka under 12-månadsperioden. Vi rekommenderar att du migrerar till en senare version av SDK:n för Azure Cosmos DB under 12-månadsperioden.

Vad händer med program som använder den Azure Cosmos DB-SDK som inte längre stöds efter tillbakadragningsdatumet?

Efter tillbakadragningsdatumet kommer Azure Cosmos DB inte att erbjuda buggkorrigeringar, nya funktioner eller stöd för de SDK-versioner som har dragits tillbaka. Om du föredrar att inte uppgradera kommer begäranden från de inaktuella versionerna av SDK:n att fortsätta att hanteras av tjänsten Azure Cosmos DB.

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 kommer inte att ha tillgång till 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 har möjlighet att uppdatera före tillbakadragningsdatumet kommer begäranden som skickas från de tillbakadragna versionerna av SDK:n att fortsätta att betjänas av Azure Cosmos DB, och dina aktiva program kommer att fortsätta att fungera. Men Azure Cosmos DB kommer inte längre att erbjuda felkorrigeringar, nya funktioner eller stöd för 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 för Microsoft Azure Cosmos DB .