Azure Cosmos DB-clientbibliotheek voor JavaScript - versie 4.2.0

Artikel
11/20/2024

/TypeScript

Azure Cosmos DB is een wereldwijd gedistribueerde databaseservice met meerdere modellen die ondersteuning biedt voor document-, sleutel-waarde-, brede kolom- en grafiekdatabases. Dit pakket is bedoeld voor JavaScript-/TypeScript-toepassingen om te communiceren met SQL API databases en de JSON-documenten die ze bevatten:

Cosmos DB-databases maken en hun instellingen wijzigen
Containers maken en wijzigen om verzamelingen JSON-documenten op te slaan
De items (JSON-documenten) in uw containers maken, lezen, bijwerken en verwijderen
Query's uitvoeren op de documenten in uw database met behulp van sql-achtige syntaxis

Sleutelkoppelingen:

Slag

Voorwaarden

Azure-abonnement en Cosmos DB SQL API-account

U moet beschikken over een Azure-abonnementen een Cosmos DB-account (SQL API) om dit pakket te kunnen gebruiken.

Als u een Cosmos DB SQL API-account nodig hebt, kunt u de Azure Cloud Shell- gebruiken om er een te maken met deze Azure CLI-opdracht:

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

U kunt ook een account maken in de Azure Portal

NodeJS

Dit pakket wordt gedistribueerd via npm- die vooraf is geïnstalleerd met NodeJS- met behulp van een LTS-versie.

CORS

U moet CORS-regels (Cross-Origin Resource Sharing) instellen regels voor uw Cosmos DB-account als u voor browsers moet ontwikkelen. Volg de instructies in het gekoppelde document om nieuwe CORS-regels voor uw Cosmos DB te maken.

Dit pakket installeren

npm install @azure/cosmos

Accountreferenties ophalen

U hebt het eindpunt van uw Cosmos DB--account nodig en Key. U vindt deze in de Azure Portal of gebruik het onderstaande Azure CLI codefragment. Het codefragment is opgemaakt voor de Bash-shell.

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

Een exemplaar van `CosmosClient` maken

Interactie met Cosmos DB begint met een exemplaar van de klasse 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);
});

Ter vereenvoudiging hebben we de key en endpoint rechtstreeks in de code opgenomen, maar u wilt deze waarschijnlijk laden vanuit een bestand dat niet in broncodebeheer is met behulp van een project zoals dotenv- of laden vanuit omgevingsvariabelen

In productieomgevingen moeten geheimen zoals sleutels worden opgeslagen in Azure Key Vault-

Sleutelbegrippen

Nadat u een CosmosClient-hebt geïnitialiseerd, kunt u communiceren met de primaire resourcetypen in Cosmos DB:

Database: een Cosmos DB-account kan meerdere databases bevatten. Wanneer u een database maakt, geeft u de API op die u wilt gebruiken bij interactie met de bijbehorende documenten: SQL, MongoDB, Gremlin, Cassandra of Azure Table. Gebruik het Database-object om de containers te beheren.
Container: een container is een verzameling JSON-documenten. U maakt (invoegen), leest, bijwerkt en verwijdert items in een container met behulp van methoden op het Container-object.
Item: Een item is een JSON-document dat is opgeslagen in een container. Elk item moet een id sleutel bevatten met een waarde waarmee het item in de container uniek wordt geïdentificeerd. Als u geen idopgeeft, genereert de SDK er automatisch een.

Zie Werken met Azure Cosmos-databases, -containers en -itemsvoor meer informatie over deze resources.

Voorbeelden

De volgende secties bevatten verschillende codefragmenten die betrekking hebben op enkele van de meest voorkomende Cosmos DB-taken, waaronder:

Een database maken
Een container maken
partitiesleutels gebruiken
Items invoegen
query's uitvoeren op documenten
een item lezen
Een item verwijderen
CRUD op container met hiërarchische partitiesleutel

Een database maken

Nadat u uw CosmosClient-hebt geverifieerd, kunt u met elke resource in het account werken. Met het onderstaande codefragment wordt een NOSQL API-database gemaakt.

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

Een container maken

In dit voorbeeld wordt een container met standaardinstellingen gemaakt

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

Partitiesleutels gebruiken

In dit voorbeeld ziet u verschillende typen partitiesleutels die worden ondersteund.

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

Als de partitiesleutel uit één waarde bestaat, kan deze worden opgegeven als een letterlijke waarde of een matrix.

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

Als de partitiesleutel uit meer dan één waarde bestaat, moet deze worden opgegeven als een matrix.

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

Items invoegen

Als u items in een container wilt invoegen, geeft u een object met uw gegevens door aan Items.upsert. Voor de Azure Cosmos DB-service is een id sleutel vereist. Als u er geen opgeeft, genereert de SDK automatisch een id.

In dit voorbeeld worden verschillende items in de container ingevoegd

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);
}

Een item lezen

Als u één item uit een container wilt lezen, gebruikt u Item.read. Dit is een goedkopere bewerking dan het gebruik van SQL om query's uit te voeren door id.

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

CRUD op container met hiërarchische partitiesleutel

Een container maken met een hiërarchische partitiesleutel

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

Een item invoegen met een hiërarchische partitiesleutel die is gedefinieerd als - ["/name", "/address/zip"]

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

Als u één item uit een container wilt lezen met een hiërarchische partitiesleutel die is gedefinieerd als - ["/name", "/address/zip"],

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

Een query uitvoeren op een item met een hiërarchische partitiesleutel met een hiërarchische partitiesleutel die is gedefinieerd als - ["/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} `);
}

Een item verwijderen

Als u items uit een container wilt verwijderen, gebruikt u Item.delete.

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

Query's uitvoeren op de database

Een Cosmos DB SQL API-database ondersteunt het uitvoeren van query's op de items in een container met Items.query met behulp van sql-achtige syntaxis:

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 `);
}

Voer geparameteriseerde query's uit door een object met de parameters en de bijbehorende waarden door te geven aan 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 `);
}

Zie Query's uitvoeren op Azure Cosmos DB-gegevens met SQL-query'svoor meer informatie over het uitvoeren van query's op Cosmos DB-databases met behulp van de SQL-API.

Pull-model voor wijzigingenfeed

Wijzigingenfeed kan worden opgehaald voor een partitiesleutel, een feedbereik of een hele container.

Als u de wijzigingenfeed wilt verwerken, maakt u een exemplaar van ChangeFeedPullModelIterator. Wanneer u in eerste instantie ChangeFeedPullModelIteratormaakt, moet u een vereiste changeFeedStartFrom waarde opgeven in de ChangeFeedIteratorOptions die bestaat uit zowel de beginpositie voor het lezen van wijzigingen als de resource (een partitiesleutel of een FeedRange) waarvoor wijzigingen moeten worden opgehaald. U kunt desgewenst maxItemCount in ChangeFeedIteratorOptions gebruiken om het maximum aantal ontvangen items per pagina in te stellen.

Opmerking: Als er geen changeFeedStartFrom waarde is opgegeven, wordt changefeed opgehaald voor een hele container van Now().

Er zijn vier beginposities voor wijzigingenfeed:

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),
};

Hier volgt een voorbeeld van het ophalen van de wijzigingenfeed voor een partitiesleutel

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
}

Omdat de wijzigingenfeed effectief een oneindige lijst met items is die alle toekomstige schrijf- en updates omvat, is de waarde van hasMoreResults altijd true. Wanneer u de wijzigingenfeed probeert te lezen en er geen nieuwe wijzigingen beschikbaar zijn, ontvangt u een antwoord met NotModified status.

Meer gedetailleerde gebruiksrichtlijnen en voorbeelden van wijzigingenfeeds vindt u hier .

Foutafhandeling

De SDK genereert verschillende soorten fouten die kunnen optreden tijdens een bewerking.

ErrorResponse wordt gegenereerd als het antwoord van een bewerking een foutcode van >=400 retourneert.
TimeoutError wordt gegenereerd als Abort intern wordt aangeroepen vanwege een time-out.
AbortError wordt gegenereerd als een door een gebruiker doorgegeven signaal de afgebroken.
RestError wordt gegenereerd in het geval van een storing in de onderliggende systeemoproep vanwege netwerkproblemen.
Fouten die worden gegenereerd door devDependencies. Voor Bijvoorbeeld. @azure/identity pakket kan CredentialUnavailableErrorgooien.

Hieronder volgt een voorbeeld voor het afhandelen van fouten van het type ErrorResponse, TimeoutError, AbortErroren 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.
  }
}

Het is belangrijk om deze fouten correct af te handelen om ervoor te zorgen dat uw toepassing probleemloos kan herstellen na fouten en naar verwachting kan blijven functioneren. Meer informatie over sommige van deze fouten en hun mogelijke oplossingen vindt u hier .

Probleemoplossing

Algemeen

Wanneer u communiceert met Cosmos DB-fouten die door de service worden geretourneerd, komen overeen met dezelfde HTTP-statuscodes die worden geretourneerd voor REST API-aanvragen:

HTTP-statuscodes voor Azure Cosmos DB-

Conflicten

Als u bijvoorbeeld probeert een item te maken met behulp van een id die al in uw Cosmos DB-database wordt gebruikt, wordt een 409 fout geretourneerd, waarmee het conflict wordt aangegeven. In het volgende codefragment wordt de fout correct verwerkt door de uitzondering te ondervangen en aanvullende informatie over de fout weer te geven.

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

Transpiling

De Azure SDK's zijn ontworpen ter ondersteuning van ES5 JavaScript-syntaxis en LTS-versies van Node.js. Als u ondersteuning nodig hebt voor eerdere JavaScript-runtimes, zoals Internet Explorer of Node 6, moet u de SDK-code transpileren als onderdeel van uw buildproces.

Tijdelijke fouten verwerken met nieuwe pogingen

Tijdens het werken met Cosmos DB kunnen tijdelijke fouten optreden die worden veroorzaakt door frequentielimieten afgedwongen door de service of andere tijdelijke problemen, zoals netwerkstoringen. Zie Patroon opnieuw proberen in de handleiding Cloudontwerppatronen en het bijbehorende circuitonderbrekerpatroonvoor informatie over het afhandelen van deze typen fouten.

Logboekregistratie

Het inschakelen van logboekregistratie kan helpen nuttige informatie over fouten te ontdekken. Als u een logboek met HTTP-aanvragen en -antwoorden wilt zien, stelt u de omgevingsvariabele AZURE_LOG_LEVEL in op info. U kunt logboekregistratie ook tijdens runtime inschakelen door setLogLevel aan te roepen in de @azure/logger. Terwijl u AZURE_LOG_LEVEL gebruikt, moet u deze instellen voordat de logboekregistratiebibliotheek wordt geïnitialiseerd. Geef deze in het ideale geval door via de opdrachtregel als u bibliotheken zoals dotenv ervoor zorgt dat dergelijke bibliotheken worden geïnitialiseerd voordat u een logboekbibliotheek opgeeft.

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

Voor meer gedetailleerde instructies over het inschakelen van logboeken, kunt u de @azure/logger pakketdocumentenbekijken.

Diagnostiek

De functie Cosmos Diagnostics biedt uitgebreide inzichten in al uw clientbewerkingen. Er wordt een CosmosDiagnostics-object toegevoegd aan de reactie van alle clientbewerkingen. zoals

Herstelbewerking van puntzoekbewerking - item.read(), container.create(), database.delete()
Querybewerkingsreponse -queryIterator.fetchAll(),
Bulk- en Batch-bewerkingen -item.batch().
Fout-/uitzonderingsantwoordobjecten.

Er wordt een CosmosDiagnostics-object toegevoegd aan de reactie van alle clientbewerkingen. Er zijn drie diagnostische cosmos-niveaus, informatie, foutopsporing en foutopsporing onveilig. Waar alleen informatie is bedoeld voor productiesystemen en foutopsporing en foutopsporing onveilig zijn bedoeld om te worden gebruikt tijdens de ontwikkeling en foutopsporing, omdat ze aanzienlijk hogere resources verbruiken. Diagnostisch niveau van Cosmos kan op twee manieren worden ingesteld

Programmatisch

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

Omgevingsvariabelen gebruiken. (Diagnostisch niveau dat is ingesteld door de omgevingsvariabele heeft een hogere prioriteit dan het instellen ervan via clientopties.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic heeft drie leden

ClientSideRequestStatistics Type: Bevat statistische diagnostische gegevens, waaronder zoekopdrachten voor metagegevens, nieuwe pogingen, eindpunten die contact hebben opgenomen en statistieken over aanvragen en antwoorden, zoals de grootte en duur van de nettolading. (wordt altijd verzameld, kan worden gebruikt in productiesystemen.)
DiagnosticNode: is een structuur die een structuur is die gedetailleerde diagnostische gegevens vastlegt. Vergelijkbaar met har opname in browsers. Deze functie is standaard uitgeschakeld en is alleen bedoeld voor het opsporen van fouten in niet-productieomgevingen. (verzameld op diagnoseniveau foutopsporing en foutopsporing onveilig)
ClientConfig: legt essentiële informatie vast met betrekking tot de configuratie-instellingen van de client tijdens de initialisatie van de client. (verzameld op diagnoseniveau foutopsporing en foutopsporing onveilig)

Zorg ervoor dat u het diagnostische niveau nooit instelt op debug-unsafe in de productieomgeving, omdat dit niveau CosmosDiagnostics nettoladingen voor aanvragen en antwoorden vastlegt en als u ervoor kiest om het te registreren (het wordt standaard geregistreerd door @azure/logger op verbose niveau). Deze nettoladingen worden mogelijk vastgelegd in uw logboeksinks.

Diagnostische gegevens gebruiken

Omdat diagnostics wordt toegevoegd aan alle antwoordobjecten. U kunt als volgt programmatisch toegang krijgen tot CosmosDiagnostic.

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

U kunt ook diagnostics vastleggen met @azure/logger, diagnostische gegevens worden altijd geregistreerd met @azure/logger op verbose niveau. Dus als u diagnostisch niveau instelt op debug of debug-unsafe en @azure/logger niveau op verbose, wordt diagnostics geregistreerd.

Volgende stappen

Meer voorbeeldcode

Verschillende voorbeelden beschikbaar zijn in de GitHub-opslagplaats van de SDK. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak worden aangetroffen tijdens het werken met Cosmos DB:

Databasebewerkingen
Containerbewerkingen
Itembewerkingen
Indexering configureren
Een containerwijzigingsfeed lezen
Opgeslagen procedures
Instellingen voor database-/containerdoorvoer wijzigen
Schrijfbewerkingen voor meerdere regio's

Beperkingen

Momenteel worden de onderstaande functies niet ondersteund. Raadpleeg de onderstaande sectie Tijdelijke oplossingen voor alternatieven.

Beperkingen voor gegevensvlak:

Query's met COUNT uit een DISTINCT-subquery
Directe TCP-modustoegang
Statistische query's voor meerdere partities, zoals sorteren, tellen en uniek, bieden geen ondersteuning voor vervolgtokens. Streambare query's, zoals SELECT * FROM WHERE, ondersteuning voor vervolgtokens. Zie de sectie Tijdelijke oplossing voor het uitvoeren van niet-streambare query's zonder vervolgtoken.
Wijzigingenfeed: Processor
Wijzigingenfeed: sleutelwaarden voor meerdere partities lezen
Ondersteuning voor pull-model voor wijzigingenfeed voor gedeeltelijke hiërarchische partitiesleutels #27059
ORDER BY voor meerdere partities voor gemengde typen

Beperkingen van besturingsvlak:

Metrische gegevens CollectionSizeUsage, DatabaseUsage en DocumentUsage ophalen
Georuimtelijke index maken
Doorvoer automatisch schalen bijwerken

Tijdelijke oplossingen

Vervolgtoken voor query's voor meerdere partities

U kunt query's voor meerdere partities bereiken met vervolgtokenondersteuning met behulp van Car-patroon. Met dit patroon kunnen toepassingen ook bestaan uit heterogene onderdelen en technologieën.

Niet-stremable query voor meerdere partities uitvoeren

Als u niet-streambare query's wilt uitvoeren zonder vervolgtokens te gebruiken, kunt u een query-iterator maken met de vereiste queryspecificatie en -opties. De volgende voorbeeldcode laat zien hoe u een query-iterator gebruikt om alle resultaten op te halen zonder dat u een vervolgtoken nodig hebt:

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
}

Deze benadering kan ook worden gebruikt voor streambare query's.

Besturingsvlakbewerkingen

Doorgaans kunt u Azure Portal, AZURE Cosmos DB Resource Provider REST API, Azure CLI of PowerShell- gebruiken voor niet-ondersteunde beperkingen voor het besturingsvlak.

Aanvullende documentatie

Zie de Azure Cosmos DB-documentatie op docs.microsoft.com voor uitgebreidere documentatie over de Cosmos DB-service.

Nuttige koppelingen

Bijdragen

Als u een bijdrage wilt leveren aan deze bibliotheek, leest u de gids voor bijdragen voor meer informatie over het bouwen en testen van de code.

indrukken

Delen via