Azure Cosmos DB-clientbibliotheek voor JavaScript - versie 4.0.0

Artikel
09/13/2023

/TypeScript

Azure Cosmos DB is een wereldwijd gedistribueerde databaseservice met meerdere modellen waarmee databases voor document-, sleutelwaarde-, kolom- en grafiekdatabases worden ondersteund. 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 de instellingen ervan wijzigen
Containers maken en wijzigen voor het opslaan van verzamelingen JSON-documenten
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

Belangrijke koppelingen:

Aan de slag

Vereisten

Azure-abonnement en Cosmos DB SQL API-account

U moet een Azure-abonnement en een Cosmos DB-account (SQL API) hebben 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 Azure Portal

Node.js

Dit pakket wordt gedistribueerd via npm , dat vooraf is geïnstalleerd met NodeJS. U moet Node v10 of hoger gebruiken.

CORS

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

Dit pakket installeren

npm install @azure/cosmos

Accountreferenties ophalen

U hebt het eindpunt en de sleutel van uw Cosmos DB-account nodig. U vindt deze in de Azure-portal of gebruik het onderstaande Azure CLI-fragment . Het codefragment is geformatteerd 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 maken van `CosmosClient`

Interactie met Cosmos DB begint met een exemplaar van de CosmosClient-klasse

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

Voor het gemak hebben we de key en endpoint rechtstreeks in de code opgenomen, maar u wilt deze waarschijnlijk laden vanuit een bestand dat niet in broncodebeheer staat met behulp van een project zoals dotenv of laden vanuit omgevingsvariabelen

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

Belangrijkste concepten

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 de interactie met de bijbehorende documenten: SQL, MongoDB, Gremlin, Cassandra of Azure Table. Gebruik het databaseobject om de containers te beheren.
Container: een container is een verzameling JSON-documenten. U kunt items in een container maken (invoegen), lezen, bijwerken en verwijderen met behulp van methoden in het containerobject .
Item: Een item is een JSON-document dat is opgeslagen in een container. Elk item moet een id sleutel bevatten met een waarde die het item in de container uniek identificeert. Als u geen opgeeft, wordt er automatisch een idgegenereerd door de SDK.

Zie Werken met Azure Cosmos-databases, -containers en -items voor 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 voor documenten
Een item lezen
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 als 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 moet elk item een id sleutel hebben. 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 op 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 wilt lezen uit een container 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();

Een query 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 hun 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's voor 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 voor het eerst maakt ChangeFeedPullModelIterator, moet u een vereiste changeFeedStartFrom waarde in de ChangeFeedIteratorOptions opgeven 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 eventueel in ChangeFeedIteratorOptions gebruiken maxItemCount om het maximum aantal 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 startposities voor de 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 een 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 in feite een oneindige lijst met items is die alle toekomstige schrijfbewerkingen 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 de status.

Meer gedetailleerde gebruiksrichtlijnen en voorbeelden van wijzigingenfeed vindt u hier.

Foutafhandeling

De SDK genereert verschillende typen 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 Afbreken intern wordt aangeroepen vanwege een time-out.
AbortError wordt gegenereerd als een gebruiker een signaal heeft doorgegeven waardoor de afbreeking is veroorzaakt.
RestError wordt gegenereerd in het geval van een storing van de onderliggende systeemoproep vanwege netwerkproblemen.
Fouten die worden gegenereerd door eventuele devDependencies. Voor bijvoorbeeld @azure/identity pakket kan gooien CredentialUnavailableError.

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 van eventuele fouten en kan blijven functioneren zoals verwacht. Meer informatie over een aantal van deze fouten en de mogelijke oplossingen vindt u hier.

Problemen oplossen

Algemeen

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

HTTP-statuscodes voor Azure Cosmos DB

Conflicten

Als u bijvoorbeeld een item probeert te maken met een id dat al in gebruik is in uw Cosmos DB-database, wordt er een 409 fout geretourneerd die het conflict aangeeft. In het volgende codefragment wordt de fout mooi verwerkt door de uitzondering vast te leggen 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");
  }
}

Transpileren

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 die worden afgedwongen door de service, of andere tijdelijke problemen, zoals netwerkstoringen. Raadpleeg voor meer informatie over het verwerken van dit soort fouten Patroon voor opnieuw proberen in de handleiding Cloudontwerppatronen en de verwante Patroon Circuitonderbreker.

Logboekregistratie

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

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

Voor meer gedetailleerde instructies over het inschakelen van logboeken kunt u de @azure-/loggerpakketdocumenten bekijken.

Diagnostiek

De functie Cosmos Diagnostics biedt uitgebreide inzichten in al uw clientbewerkingen. Een CosmosDiagnostics-object wordt toegevoegd aan het antwoord van alle clientbewerkingen. Zoals

Reponse van puntzoekbewerking - item.read(), container.create(), database.delete()
Querybewerking-reponse -queryIterator.fetchAll(),
Bulk- en batchbewerkingen -item.batch().
Fout-/uitzonderingsreactieobjecten.

Een CosmosDiagnostics-object wordt toegevoegd aan het antwoord van alle clientbewerkingen. Er zijn 3 diagnostische cosmos-niveaus, info, foutopsporing en onveilige foutopsporing. Hierbij is alleen informatie bedoeld voor productiesystemen en zijn foutopsporing en foutopsporing onveilig bedoeld om te worden gebruikt tijdens ontwikkeling en foutopsporing, omdat deze aanzienlijk hogere resources verbruiken. Cosmos Diagnostic-niveau kan op 2 manieren worden ingesteld

Programmatisch

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

Omgevingsvariabelen gebruiken. (Diagnostisch niveau ingesteld door 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 metagegevenszoekacties, nieuwe pogingen, eindpunten die zijn benaderd en aanvraag- en antwoordstatistieken, zoals de grootte en duur van de nettolading. (wordt altijd verzameld, kan worden gebruikt in productiesystemen.)
DiagnosticNode: is een structuur die lijkt op een structuur die gedetailleerde diagnostische gegevens vastlegt. har Vergelijkbaar met opname die aanwezig is in browsers. Deze functie is standaard uitgeschakeld en is alleen bedoeld voor het opsporen van fouten in niet-productieomgevingen. (verzameld op diagnostisch niveau 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 diagnostisch niveau foutopsporing en foutopsporing onveilig)

Zorg ervoor dat u het diagnostische niveau debug-unsafe nooit instelt op in de productieomgeving, omdat dit niveau CosmosDiagnostics nettoladingen van 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 kunnen worden vastgelegd in uw logboeksinks.

Diagnostische gegevens gebruiken

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

  // 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 registreren diagnostics met behulp van @azure/logger, diagnostische gegevens worden altijd geregistreerd met behulp van @azure/logger niveau verbose . Dus als u diagnostisch niveau instelt op debug of debug-unsafe en @azure/logger niveau op verbose, diagnostics wordt geregistreerd.

Volgende stappen

Meer voorbeeldcode

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

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

Beperkingen

De onderstaande functies worden momenteel niet ondersteund. Raadpleeg de sectie Tijdelijke oplossingen hieronder voor alternatieve opties.

Beperkingen van gegevensvlak:

Query's met COUNT uit een DISTINCT-subquery
Toegang tot directe TCP-modus
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 een vervolgtoken.
Wijzigingenfeed: Processor
Wijzigingenfeed: sleutelwaarden voor meerdere partities lezen
Feed pull-model alle versies wijzigen en modus verwijderen #27058
Ondersteuning voor pull-model van wijzigingenfeed voor gedeeltelijke hiërarchische partitiesleutels #27059
ORDER BY voor meerdere partities voor gemengde typen

Beperkingen van besturingsvlak:

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

Tijdelijke oplossingen

Vervolgtoken voor query's tussen partities

U kunt query's voor meerdere partities bereiken met ondersteuning voor vervolgtoken met behulp van het zij-autopatroon. Met behulp van dit patroon kunnen toepassingen ook worden samengesteld met 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 * 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
}

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

Besturingsvlakbewerkingen

Normaal gesproken kunt u Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI of PowerShell gebruiken voor de niet-ondersteunde beperkingen van het besturingsvlak.

Aanvullende documentatie

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

Handige koppelingen

Bijdragen

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

Weergaven

Share via