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

/Maskin

Azure Cosmos DB är en globalt distribuerad databastjänst med flera modeller som stöder dokument-, nyckelvärdes-, bredkolumns- 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
• Fråga dokumenten i databasen med sql-liknande syntax

Nyckellänkar:

• Package (npm)
• API-referensdokumentation
• Produktdokumentation

Komma igång

Förutsättningar

Azure-prenumeration och Cosmos DB SQL API-konto

Du måste ha en Azure-prenumerationoch 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 förinstalleras med NodeJS- med hjälp av en LTS-version.

CORS

Du måste konfigurera CORS(Cross-Origin Resource Sharing) regler 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 Cosmos DB.

Installera det här paketet

npm install @azure/cosmos

Hämta kontoautentiseringsuppgifter

Du behöver din Cosmos DB--kontoslutpunkt och nyckel. Du hittar dessa i Azure-portalen eller använd 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 skull har vi inkluderat key och endpoint direkt i koden, men du vill förmodligen läsa in dessa 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:

• Database: 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 objektet Database 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 Container-objektet.

• 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 någon idgenererar SDK:et en automatiskt.

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
• med partitionsnycklar
• Infoga objekt
• Fråga 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:et 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 finns i Fråga Azure Cosmos DB-data med SQL-frågor.

Pull-modell för ändringsflöde

Ändringsflöde 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 en FeedRange) som ändringar 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 för hasMoreResults 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 användningsriktlinjer och exempel på ändringsflöde finns här.

Felhantering

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

1. ErrorResponse utlöses om svaret för en åtgärd returnerar en felkod på >=400.
2. TimeoutError utlöses om Abort anropas internt på grund av timeout.
3. AbortError utlöses om någon användare skickade en signal som orsakade avbrottet.
4. RestError utlöses om det underliggande systemanropet misslyckas på grund av nätverksproblem.
5. Fel som genereras av eventuella devDependencies. För t.ex. @azure/identity paket 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 från eventuella fel och fortsätta att fungera som förväntat. Mer information om några av dessa fel och deras 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 hjälp av 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 undantaget fångas upp och ytterligare information om felet visas.

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:er ä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örningar, till exempel Internet Explorer eller Node 6, måste du överföra SDK-koden som en del av byggprocessen.

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

När du arbetar med Cosmos DB kan det uppstå tillfälliga fel som orsakas av hastighetsbegränsningar framtvingas av tjänsten eller andra tillfälliga problem som nätverksfel. Information om hur du hanterar dessa typer av fel finns i Mönster för återförsök i guiden Mönster för molndesign och det relaterade kretsbrytarmönstret.

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med 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 se till att ange det innan loggningsbiblioteket initieras. Använd gärna kommandoraden om du använder bibliotek som dotenv kontrollera att sådana bibliotek initieras innan du loggar biblioteket.

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

Mer detaljerade anvisningar om hur du aktiverar loggar finns i @azure/logger-paketdokumenten.

Diagnostik

Cosmos Diagnostics-funktionen ger bättre insikter om alla dina klientåtgärder. Ett CosmosDiagnostics-objekt läggs till som svar på alla klientåtgärder. såsom

• Punktsökningsåtgärd – 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 är osäkra. Där endast information är avsedd för produktionssystem och felsöka och felsöka osäkra ä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

• Programatiskt

  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 ange den via klientalternativ.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic har tre medlemmar

• ClientSideRequestStatistics Type: Innehåller aggregeringar diagnostikinformation, inklusive metadatasökningar, återförsök, slutpunkter som kontaktas samt statistik för begäran 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. Liknar har 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ökning och felsökningssäker)

• ClientConfig: Samlar in viktig information som rör klientens konfigurationsinställningar under klientinitiering. (samlas in på diagnostiknivå felsökning och felsökningssäker)

Se till att aldrig ställa in diagnostiknivå på 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 som standard av @azure/logger på verbose nivå). Dessa nyttolaster kan fångas in i dina loggmottagare.

Använda diagnostik

• Eftersom diagnostics läggs till i alla svarsobjekt. Du kan programatiskt komma åt CosmosDiagnostic 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, diagnostiken loggas alltid med @azure/logger på verbose nivå. Om du anger diagnostiknivå till debug eller debug-unsafe och @azure/logger nivå till verboseloggas diagnostics.

Nästa steg

Mer exempelkod

Flera exempel är tillgängliga för dig på SDK:s GitHub-lagringsplats. De här exemplen ger 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, till exempel sortering, räkning och distinkta, stöder inte fortsättningstoken. Strömmande frågor, till exempel SELECT * FROM WHERE , stöder 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äs flera nyckelvärden för partitioner
• 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

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önster. Det här mönstret kan också göra det möjligt för program att bestå av heterogena komponenter och tekniker.

Köra icke-stremable korspartitionsfråga

Om du vill köra frågor som inte kan strömmas utan att använda fortsättningstoken kan du skapa en fråge-iterator med den frågespecifikation och de alternativ som krävs. Följande exempelkod visar hur du använder en fråge-iterator för att hämta alla resultat utan att behöva en fortsättningstoken:

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
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

Normalt kan du använda Azure Portal, REST API för Azure Cosmos DB-resursprovider, Azure CLI eller PowerShell- för kontrollplanet som inte stöds.

Ytterligare dokumentation

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

Användbara länkar

• Välkommen till Azure Cosmos DB
• Snabbstart
• Självstudie
• exempel
• Introduktion till resursmodell för Azure Cosmos DB Service
• Introduktion till SQL API för Azure Cosmos DB Service
• partitionering
• API-dokumentation

Bidragande

Om du vill bidra till det här biblioteket kan du läsa bidragsguide för att lära dig mer om hur du skapar och testar koden.