Azure Cosmos DB-klientbibliotek för JavaScript – version 4.0.0

Artikel
09/13/2023

/Maskin

Azure Cosmos DB är en globalt distribuerad databastjänst för flera modeller som har stöd för dokument, nyckelvärden, breda kolumner och grafdatabaser. Det här paketet är avsett för JavaScript-/TypeScript-program att interagera med SQL API-databaser och de JSON-dokument som de innehåller:

Skapa Cosmos DB-databaser och ändra deras inställningar
Skapa och ändra containrar för att lagra samlingar av JSON-dokument
Skapa, läsa, uppdatera och ta bort objekten (JSON-dokument) i dina containrar
Köra frågor mot dokumenten i databasen med sql-liknande syntax

Nyckellänkar:

Komma igång

Förutsättningar

Azure-prenumeration och Cosmos DB SQL API-konto

Du måste ha en Azure-prenumeration och ett Cosmos DB-konto (SQL API) för att kunna använda det här paketet.

Om du behöver ett Cosmos DB SQL API-konto kan du använda Azure Cloud Shell för att skapa ett med det här Azure CLI-kommandot:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

Eller så kan du skapa ett konto i Azure-portalen

NodeJS

Det här paketet distribueras via npm som levereras förinstallerat med NodeJS. Du bör använda Node v10 eller senare.

CORS

Du måste konfigurera CORS-regler (Cross-Origin Resource Sharing) för ditt Cosmos DB-konto om du behöver utveckla för webbläsare. Följ anvisningarna i det länkade dokumentet för att skapa nya CORS-regler för din Cosmos DB.

Installera det här paketet

npm install @azure/cosmos

Hämta kontoautentiseringsuppgifter

Du behöver cosmos DB-kontots slutpunkt och nyckel. Du hittar dem i Azure-portalen eller använder Azure CLI-kodfragmentet nedan. Kodfragmentet är formaterat för Bash-gränssnittet.

az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv

Skapa en instans av `CosmosClient`

Interaktion med Cosmos DB börjar med en instans av klassen CosmosClient

const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

async function main() {
  // The rest of the README samples are designed to be pasted into this function body
}

main().catch((error) => {
  console.error(error);
});

För enkelhetens key skull har vi inkluderat och endpoint direkt i koden, men du vill förmodligen läsa in dem från en fil som inte finns i källkontrollen med hjälp av ett projekt som dotenv eller inläsning från miljövariabler

I produktionsmiljöer bör hemligheter som nycklar lagras i Azure Key Vault

Viktiga begrepp

När du har initierat en CosmosClient kan du interagera med de primära resurstyperna i Cosmos DB:

Databas: Ett Cosmos DB-konto kan innehålla flera databaser. När du skapar en databas anger du det API som du vill använda när du interagerar med dess dokument: SQL, MongoDB, Gremlin, Cassandra eller Azure Table. Använd databasobjektet för att hantera dess containrar.
Container: En container är en samling JSON-dokument. Du skapar (infogar), läser, uppdaterar och tar bort objekt i en container med hjälp av metoder i containerobjektet .
Objekt: Ett objekt är ett JSON-dokument som lagras i en container. Varje objekt måste innehålla en id nyckel med ett värde som unikt identifierar objektet i containern. Om du inte anger en idgenereras en automatiskt av SDK:t.

Mer information om dessa resurser finns i Arbeta med Azure Cosmos-databaser, containrar och objekt.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Cosmos DB-uppgifterna, inklusive:

Skapa en databas
Skapa en container
Använda partitionsnycklar
Infoga objekt
Köra en fråga mot dokument
Läsa ett objekt
Ta bort ett objekt
CRUD på container med hierarkisk partitionsnyckel

Skapa en databas

När du har autentiserat Din CosmosClient kan du arbeta med valfri resurs i kontot. Kodfragmentet nedan skapar en NOSQL API-databas.

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);

Skapa en container

I det här exemplet skapas en container med standardinställningar

const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);

Använda partitionsnycklar

Det här exemplet visar olika typer av partitionsnycklar som stöds.

await container.item("id", "1").read();        // string type
await container.item("id", 2).read();          // number type
await container.item("id", true).read();       // boolean type
await container.item("id", {}).read();         // None type
await container.item("id", undefined).read();  // None type
await container.item("id", null).read();       // null type

Om partitionsnyckeln består av ett enda värde kan den anges antingen som ett literalvärde eller en matris.

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

Om partitionsnyckeln består av fler än ett värden ska den anges som en matris.

await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();

Infoga objekt

Om du vill infoga objekt i en container skickar du ett objekt som innehåller dina data till Items.upsert. Azure Cosmos DB-tjänsten kräver att varje objekt har en id nyckel. Om du inte anger något genererar SDK:t en id automatiskt.

Det här exemplet infogar flera objekt i containern

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
  await container.items.create(city);
}

Läsa ett objekt

Om du vill läsa ett enskilt objekt från en container använder du Item.read. Det här är en billigare åtgärd än att använda SQL för att fråga efter id.

await container.item("1", "1").read();

CRUD på container med hierarkisk partitionsnyckel

Skapa en container med hierarkisk partitionsnyckel

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

Infoga ett objekt med hierarkisk partitionsnyckel definierad som - ["/name", "/address/zip"]

const item = {
  id: 1,
  name: 'foo',
  address: {
    zip: 100
  },
  active: true
}
await container.items.create(item);

Läsa ett enskilt objekt från en container med hierarkisk partitionsnyckel definierad som - ["/name", "/address/zip"],

await container.item("1", ["foo", 100]).read();

Fråga ett objekt med hierarkisk partitionsnyckel med hierarkisk partitionsnyckel definierad som - ["/name", "/address/zip"],

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
          partitionKey: ["foo", 100],
        })
  .fetchAll();
for (const item of resources) {
  console.log(`${item.name}, ${item.address.zip} `);
}

Ta bort ett objekt

Om du vill ta bort objekt från en container använder du Item.delete.

// Delete the first item returned by the query above
await container.item("1").delete();

Fråga databasen

En Cosmos DB SQL API-databas stöder frågor mot objekten i en container med Items.query med sql-liknande syntax:

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

Utför parametriserade frågor genom att skicka ett objekt som innehåller parametrarna och deras värden till Items.query:

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }]
  })
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

Mer information om hur du kör frågor mot Cosmos DB-databaser med hjälp av SQL-API:et finns i Köra frågor mot Azure Cosmos DB-data med SQL-frågor.

Pull-modell för ändringsflöde

Ändringsflödet kan hämtas för en partitionsnyckel, ett flödesintervall eller en hel container.

Om du vill bearbeta ändringsflödet skapar du en instans av ChangeFeedPullModelIterator. När du först skapar ChangeFeedPullModelIteratormåste du ange ett obligatoriskt changeFeedStartFrom värde i ChangeFeedIteratorOptions som består av både startpositionen för att läsa ändringar och resursen (en partitionsnyckel eller ett FeedRange) som ändringarna ska hämtas för. Du kan också använda maxItemCount i ChangeFeedIteratorOptions för att ange det maximala antalet objekt som tas emot per sida.

Obs! Om inget changeFeedStartFrom värde anges hämtas changefeed för en hel container från Now().

Det finns fyra startpositioner för ändringsflöde:

Beginning

// Signals the iterator to read changefeed from the beginning of time.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning();
}
const iterator = container.getChangeFeedIterator(options);

Time

// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11") // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time);
}

Now

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now();
}

Continuation

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken);
}

Här är ett exempel på hur du hämtar ändringsflöde för en partitionsnyckel

const partitionKey = "some-partition-Key-value";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
  const response = await iterator.readNext();
  // process this response
}

Eftersom ändringsflödet i praktiken är en oändlig lista över objekt som omfattar alla framtida skrivningar och uppdateringar är värdet hasMoreResults för alltid true. När du försöker läsa ändringsflödet och det inte finns några nya ändringar tillgängliga får du ett svar med NotModified status.

Mer detaljerade riktlinjer för användning och exempel på ändringsflöde finns här.

Felhantering

SDK:et genererar olika typer av fel som kan inträffa under en åtgärd.

ErrorResponse utlöses om svaret för en åtgärd returnerar felkoden >=400.
TimeoutError utlöses om Abort anropas internt på grund av timeout.
AbortError utlöses om någon användare skickade en signal som orsakade avbrottet.
RestError genereras om det underliggande systemanropet misslyckas på grund av nätverksproblem.
Fel som genereras av eventuella devDependencies. För t.ex. @azure/identity paketet kan utlösa CredentialUnavailableError.

Följande är ett exempel på hantering av fel av typen ErrorResponse, TimeoutError, AbortErroroch RestError.

try {
  // some code
} catch (err) {
  if (err instanceof ErrorResponse) {
    // some specific error handling.
  } else if (err instanceof RestError) {
    // some specific error handling.
  }
  // handle other type of errors in similar way.
  else {
    // for any other error.
  }
}

Det är viktigt att hantera dessa fel korrekt för att säkerställa att programmet kan återställas korrekt efter eventuella fel och fortsätta fungera som förväntat. Mer information om några av dessa fel och möjliga lösningar finns här.

Felsökning

Allmänt

När du interagerar med Cosmos DB-fel som returneras av tjänsten motsvarar samma HTTP-statuskoder som returneras för REST API-begäranden:

HTTP-statuskoder för Azure Cosmos DB

Konflikter

Om du till exempel försöker skapa ett objekt med en id som redan används i Cosmos DB-databasen returneras ett 409 fel som anger konflikten. I följande kodfragment hanteras felet korrekt genom att fånga upp undantaget och visa ytterligare information om felet.

try {
  await containers.items.create({ id: "existing-item-id" });
} catch (error) {
  if (error.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Transpilering

Azure SDK:erna är utformade för att stödja ES5 JavaScript-syntax och LTS-versioner av Node.js. Om du behöver stöd för tidigare JavaScript-körningsmiljöer som Internet Explorer eller Node 6 måste du transpilera SDK-koden som en del av byggprocessen.

Hantera tillfälliga fel med återförsök

När du arbetar med Cosmos DB kan du stöta på tillfälliga fel som orsakas av hastighetsbegränsningar som framtvingas av tjänsten eller andra tillfälliga problem som nätverksfel. Information om hur du hanterar dessa typer av fel finns i Återförsöksmönster i guiden för molndesignmönster och relaterade Kretsbrytarmönster.

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger. När du använder AZURE_LOG_LEVEL måste du ange det innan loggningsbiblioteket initieras. Vi rekommenderar att du skickar den via kommandoraden om du använder bibliotek som dotenv att se till att sådana bibliotek initieras innan du loggar bibliotek.

const { setLogLevel } = require("@azure/logger");
setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokumentationen om @azure-/loggningspaket.

Diagnostik

Cosmos Diagnostics-funktionen ger förbättrade insikter om alla dina klientåtgärder. Ett CosmosDiagnostics-objekt läggs till som svar på alla klientåtgärder. Som

Referensåtgärd för punktsökning – item.read(), container.create(), database.delete()
Frågeåtgärden reponse -queryIterator.fetchAll(),
Mass- och Batch-åtgärder -item.batch().
Fel-/undantagssvarsobjekt.

Ett CosmosDiagnostics-objekt läggs till som svar på alla klientåtgärder. Det finns 3 Cosmos-diagnostiknivåer, information, felsökning och felsökning som inte är säkra. Där endast information är avsedd för produktionssystem och felsökning och felsökning som är osäker är avsedda att användas under utveckling och felsökning, eftersom de förbrukar betydligt högre resurser. Cosmos-diagnostiknivån kan anges på två sätt

Programmatiskt

  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });

Använda miljövariabler. (Diagnostiknivå som anges av miljövariabeln har högre prioritet än att ställa in den via klientalternativ.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic har tre medlemmar

ClientSideRequestStatistics Type: Innehåller aggregerad diagnostikinformation, inklusive metadatasökningar, återförsök, slutpunkter som kontaktas och statistik för förfrågningar och svar, till exempel nyttolaststorlek och varaktighet. (samlas alltid in, kan användas i produktionssystem.)
DiagnosticNode: Är en trädliknande struktur som samlar in detaljerad diagnostikinformation. har Liknar inspelning som finns i webbläsare. Den här funktionen är inaktiverad som standard och är endast avsedd för felsökning av icke-produktionsmiljöer. (samlas in på diagnostiknivå– felsöka och felsöka–osäkra)
ClientConfig: Samlar in viktig information om klientens konfigurationsinställningar under klientinitiering. (samlas in på diagnostiknivå– felsöka och felsöka–osäkra)

Se till att aldrig ange diagnostiknivå till debug-unsafe i produktionsmiljön, eftersom den här nivån CosmosDiagnostics samlar in nyttolaster för begäran och svar och om du väljer att logga den (den loggas @azure/logger som standard på verbose nivå). Dessa nyttolaster kan samlas in i dina loggmottagare.

Använda diagnostik

Eftersom diagnostics läggs till i alla svarsobjekt. Du kan komma åt CosmosDiagnostic programmatiskt på följande sätt.

  // For point look up operations
  const { container, diagnostics: containerCreateDiagnostic } =
    await database.containers.createIfNotExists({
      id: containerId,
      partitionKey: {
        paths: ["/key1"],
      },
  });

  // For Batch operations
   const operations: OperationInput[] = [
    {
      operationType: BulkOperationType.Create,
      resourceBody: { id: 'A', key: "A", school: "high" },
    },
  ];
  const response = await container.items.batch(operations, "A"); 
  
  // For query operations
  const queryIterator = container.items.query("select * from c");
  const { resources, diagnostics } = await queryIterator.fetchAll();

  // While error handling
  try {
    // Some operation that might fail
  } catch (err) {
    const diagnostics = err.diagnostics
  }

Du kan också logga diagnostics med @azure/logger, diagnostik loggas alltid med på verbose@azure/logger nivå. Så om du anger Diagnostiknivå till debug eller debug-unsafe och @azure/logger nivå till verbose, diagnostics loggas.

Nästa steg

Mer exempelkod

Det finns flera exempel på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Cosmos DB:

Databasåtgärder
Containeråtgärder
Objektåtgärder
Konfigurera indexering
Läsa en container ändringsflöde
Lagrade procedurer
Ändra dataflödesinställningar för databas/container
Skrivåtgärder för flera regioner

Begränsningar

För närvarande stöds inte funktionerna nedan. Alternativ finns i avsnittet Lösningar nedan.

Begränsningar för dataplanet:

Frågor med COUNT från en DISTINCT-underfråga
Direkt åtkomst till TCP-läge
Aggregerade frågor mellan partitioner, t.ex. sortering, räkning och distinkta, stöder inte fortsättningstoken. Strömmande frågor, till exempel SELECT * FROM WHERE , har stöd för fortsättningstoken. Se avsnittet "Lösning" för att köra frågor som inte kan strömmas utan en fortsättningstoken.
Ändringsflöde: Processor
Ändringsflöde: Läsa nyckelvärden för flera partitioner
Ändra feedens pull-modell, alla versioner och borttagningsläge nr 27058
Stöd för pull-modell för ändringsflöde för partiella hierarkiska partitionsnycklar #27059
ORDER BY mellan partitioner för blandade typer

Begränsningar för kontrollplan:

Hämta måtten CollectionSizeUsage, DatabaseUsage och DocumentUsage
Skapa geospatialt index
Uppdatera dataflöde för autoskalning

Provisoriska lösningar

Fortsättningstoken för frågor mellan partitioner

Du kan uppnå frågor mellan partitioner med stöd för fortsättningstoken med hjälp av sidobilsmönstret. Det här mönstret kan även göra det möjligt för program att bestå av heterogena komponenter och tekniker.

Köra frågor mellan partitioner som inte kan tas bort

Om du vill köra frågor som inte kan strömmas utan användning av fortsättningstoken kan du skapa en frågeiterator med nödvändig frågespecifikation och alternativ. Följande exempelkod visar hur du använder en frågeiterator för att hämta alla resultat utan att behöva en fortsättningstoken:

const querySpec = {
  query: "SELECT * FROM c WHERE c.status = @status",
  parameters: [{ name: "@status", value: "active" }],
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

Den här metoden kan också användas för strömmande frågor.

Kontrollplansåtgärder

Vanligtvis kan du använda Azure-portalen, REST-API:et för Azure Cosmos DB-resursprovidern, Azure CLI eller PowerShell för begränsningar som inte stöds av kontrollplanet.

Ytterligare dokumentation

Mer omfattande dokumentation om Cosmos DB-tjänsten finns i Azure Cosmos DB-dokumentationen om docs.microsoft.com.

Användbara länkar

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar koden.

Visningar

Dela via