Freigeben über

Azure Cosmos DB-Clientbibliothek für JavaScript – Version 4.2.0

  • Artikel

/Maschinenschrift

neuesten npm-Badge Buildstatus

Azure Cosmos DB ist ein global verteilter, multimodellbasierter Datenbankdienst, der Dokument-, Schlüsselwert-, Spalten- und Diagrammdatenbanken unterstützt. Dieses Paket ist für JavaScript-/TypeScript-Anwendungen vorgesehen, um mit SQL-API Datenbanken und den darin enthaltenen JSON-Dokumenten zu interagieren:

  • Erstellen von Cosmos DB-Datenbanken und Ändern ihrer Einstellungen
  • Erstellen und Ändern von Containern zum Speichern von Sammlungen von JSON-Dokumenten
  • Erstellen, Lesen, Aktualisieren und Löschen der Elemente (JSON-Dokumente) in Ihren Containern
  • Abfragen der Dokumente in Ihrer Datenbank mithilfe einer SQL-ähnlichen Syntax

Wichtige Links:

Erste Schritte

Voraussetzungen

Azure-Abonnement und Cosmos DB SQL-API-Konto

Sie müssen über ein Azure-Abonnement-verfügen, und ein Cosmos DB-Konto (SQL-API) für die Verwendung dieses Pakets.

Wenn Sie ein Cosmos DB SQL-API-Konto benötigen, können Sie die Azure Cloud Shell verwenden, um ein Konto mit diesem Azure CLI-Befehl zu erstellen:

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

Oder Sie können ein Konto im Azure Portal

NodeJS

Dieses Paket wird über npm verteilt, das mit NodeJS mit einer LTS-Version vorinstalliert ist.

CORS

Sie müssen Cross-Origin Resource Sharing (CORS) Regeln für Ihr Cosmos DB-Konto einrichten, wenn Sie für Browser entwickeln müssen. Befolgen Sie die Anweisungen im verknüpften Dokument, um neue CORS-Regeln für Ihre Cosmos DB zu erstellen.

Installieren dieses Pakets

npm install @azure/cosmos

Kontoanmeldeinformationen abrufen

Sie benötigen Ihren Cosmos DB Account Endpoint und Key. Sie finden diese im Azure Portal- oder verwenden sie den folgenden Azure CLI Codeausschnitt. Der Codeausschnitt ist für die Bash-Shell formatiert.

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

Erstellen einer Instanz von CosmosClient

Interaktion mit Cosmos DB beginnt mit einer Instanz der 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);
});

Aus Gründen der Einfachheit haben wir die key und endpoint direkt im Code eingeschlossen, aber Sie möchten diese wahrscheinlich aus einer Datei laden, die sich nicht in der Quellcodeverwaltung befindet, indem Sie ein Projekt wie dotenv- oder das Laden aus Umgebungsvariablen verwenden.

In Produktionsumgebungen sollten geheime Schlüssel wie Schlüssel in Azure Key Vault- gespeichert werden.

Schlüsselkonzepte

Nachdem Sie ein CosmosClient-initialisiert haben, können Sie mit den primären Ressourcentypen in Cosmos DB interagieren:

  • Datenbank-: Ein Cosmos DB-Konto kann mehrere Datenbanken enthalten. Wenn Sie eine Datenbank erstellen, geben Sie die API an, die Sie bei der Interaktion mit ihren Dokumenten verwenden möchten: SQL, MongoDB, Gremlin, Cassandra oder Azure Table. Verwenden Sie das Database-Objekt, um ihre Container zu verwalten.

  • Container-: Ein Container ist eine Sammlung von JSON-Dokumenten. Sie erstellen (einfügen), lesen, aktualisieren und löschen Elemente in einem Container mithilfe von Methoden für das Container--Objekt.

  • Element-: Ein Element ist ein JSON-Dokument, das in einem Container gespeichert ist. Jedes Element muss einen id Schlüssel mit einem Wert enthalten, der das Element innerhalb des Containers eindeutig identifiziert. Wenn Sie keine idbereitstellen, generiert das SDK automatisch eins.

Weitere Informationen zu diesen Ressourcen finden Sie unter Arbeiten mit Azure Cosmos-Datenbanken, -Containern und -Elementen.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der am häufigsten verwendeten Cosmos DB-Aufgaben abdecken, darunter:

Erstellen einer Datenbank

Nachdem Sie Ihre CosmosClient-authentifiziert haben, können Sie mit jeder Ressource im Konto arbeiten. Der folgende Codeausschnitt erstellt eine NOSQL-API-Datenbank.

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

Erstellen eines Containers

In diesem Beispiel wird ein Container mit Standardeinstellungen erstellt.

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

Verwenden von Partitionsschlüsseln

Dieses Beispiel zeigt verschiedene Typen von Partitionsschlüsseln, die unterstützt werden.

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

Wenn der Partitionsschlüssel aus einem einzelnen Wert besteht, kann er entweder als Literalwert oder als Array bereitgestellt werden.

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

Wenn der Partitionsschlüssel aus mehr als einem Wert besteht, sollte er als Array bereitgestellt werden.

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

Elemente einfügen

Um Elemente in einen Container einzufügen, übergeben Sie ein Objekt, das Ihre Daten enthält, an Items.upsert. Der Azure Cosmos DB-Dienst erfordert, dass jedes Element über einen id Schlüssel verfügt. Wenn Sie keins bereitstellen, generiert das SDK automatisch eine id.

In diesem Beispiel werden mehrere Elemente in den Container eingefügt.

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

Lesen eines Elements

Verwenden Sie Item.read, um ein einzelnes Element aus einem Container zu lesen. Dies ist ein kostengünstigerer Vorgang als die Verwendung von SQL zum Abfragen durch id.

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

CRUD für Container mit hierarchischem Partitionsschlüssel

Erstellen eines Containers mit hierarchischem Partitionsschlüssel

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

Einfügen eines Elements mit hierarchischem Partitionsschlüssel, definiert als - ["/name", "/address/zip"]

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

So lesen Sie ein einzelnes Element aus einem Container mit hierarchischem Partitionsschlüssel: ["/name", "/address/zip"],

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

Abfragen eines Elements mit hierarchischem Partitionsschlüssel mit hierarchischem Partitionsschlüssel, definiert 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} `);
}

Löschen eines Elements

Verwenden Sie Item.delete, um Elemente aus einem Container zu löschen.

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

Abfragen der Datenbank

Eine Cosmos DB SQL-API-Datenbank unterstützt das Abfragen der Elemente in einem Container mit Items.query- mithilfe von SQL-like-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 `);
}

Führen Sie parametrisierte Abfragen aus, indem Sie ein Objekt, das die Parameter und deren Werte enthält, an Items.queryübergeben:

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

Weitere Informationen zum Abfragen von Cosmos DB-Datenbanken mithilfe der SQL-API finden Sie unter Abfrage von Azure Cosmos DB-Daten mit SQL-Abfragen.

Feed-Pullmodell ändern

Der Änderungsfeed kann für einen Partitionsschlüssel, einen Feedbereich oder einen gesamten Container abgerufen werden.

Um den Änderungsfeed zu verarbeiten, erstellen Sie eine Instanz von ChangeFeedPullModelIterator. Wenn Sie zunächst ChangeFeedPullModelIteratorerstellen, müssen Sie einen erforderlichen changeFeedStartFrom Wert innerhalb der ChangeFeedIteratorOptions angeben, der sowohl aus der Startposition zum Lesen von Änderungen als auch aus der Ressource(einem Partitionsschlüssel oder einem FeedRange) besteht, für den Änderungen abgerufen werden sollen. Optional können Sie maxItemCount in ChangeFeedIteratorOptions verwenden, um die maximale Anzahl der pro Seite empfangenen Elemente festzulegen.

Hinweis: Wenn kein changeFeedStartFrom Wert angegeben ist, wird der Änderungsfeed für einen gesamten Container von Now() abgerufen.

Es gibt vier Startpositionen für den Änderungsfeed:

  • 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 ist ein Beispiel für das Abrufen des Änderungsfeeds für einen Partitionsschlüssel.

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
}

Da der Änderungsfeed effektiv eine unendliche Liste von Elementen ist, die alle zukünftigen Schreibvorgänge und Aktualisierungen umfasst, wird der Wert von hasMoreResults immer true. Wenn Sie versuchen, den Änderungsfeed zu lesen, und es sind keine neuen Änderungen verfügbar, erhalten Sie eine Antwort mit NotModified Status.

Detailliertere Nutzungsrichtlinien und Beispiele für Änderungsfeeds finden Sie hier.

Fehlerbehandlung

Das SDK generiert verschiedene Arten von Fehlern, die während eines Vorgangs auftreten können.

  1. ErrorResponse wird ausgelöst, wenn die Antwort eines Vorgangs einen Fehlercode von >=400 zurückgibt.
  2. TimeoutError wird ausgelöst, wenn "Abort" aufgrund eines Timeouts intern aufgerufen wird.
  3. AbortError wird ausgelöst, wenn der Abbruch durch einen Benutzer ausgelöst wurde.
  4. RestError wird bei Einem Ausfall des zugrunde liegenden Systemaufrufs aufgrund von Netzwerkproblemen ausgelöst.
  5. Von devDependencies generierte Fehler. Für z. B. @azure/identity Paket könnte CredentialUnavailableErrorauslösen.

Nachfolgend sehen Sie ein Beispiel für die Behandlung von Fehlern vom Typ ErrorResponse, TimeoutError, AbortErrorund 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.
  }
}

Es ist wichtig, diese Fehler ordnungsgemäß zu behandeln, um sicherzustellen, dass Ihre Anwendung problemlos von Fehlern wiederhergestellt und wie erwartet funktioniert. Weitere Details zu einigen dieser Fehler und deren mögliche Lösungen finden Sie hier .

Fehlerbehebung

Allgemein

Wenn Sie mit Cosmos DB-Fehlern interagieren, die vom Dienst zurückgegeben werden, entsprechen den gleichen HTTP-Statuscodes, die für REST-API-Anforderungen zurückgegeben werden:

HTTP-Statuscodes für Azure Cosmos DB-

Konflikte

Wenn Sie beispielsweise versuchen, ein Element mithilfe einer id zu erstellen, die bereits in Ihrer Cosmos DB-Datenbank verwendet wird, wird ein 409 Fehler zurückgegeben, der den Konflikt angibt. Im folgenden Codeausschnitt wird der Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen und zusätzliche Informationen zum Fehler angezeigt werden.

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

Transpilieren

Die Azure-SDKs sind für die Unterstützung von ES5 JavaScript-Syntax und LTS-Versionen von Node.jskonzipiert. Wenn Sie Unterstützung für frühere JavaScript-Runtimes wie Internet Explorer oder Node 6 benötigen, müssen Sie den SDK-Code als Teil Ihres Buildprozesses transpilieren.

Behandeln vorübergehender Fehler mit Wiederholungen

Während Sie mit Cosmos DB arbeiten, treten möglicherweise vorübergehende Fehler auf, die durch Ratelimits verursacht werden, vom Dienst erzwungen werden, oder andere vorübergehende Probleme wie Netzwerkausfälle. Informationen zum Behandeln dieser Arten von Fehlern finden Sie unter Wiederholungsmuster im Leitfaden für Cloudentwurfsmuster und das zugehörige Schaltkreisumbruchmuster.

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden. Stellen Sie bei der Verwendung von AZURE_LOG_LEVEL sicher, dass sie vor der Initialisierung der Protokollierungsbibliothek festgelegt wird. Übergeben Sie sie ideal über die Befehlszeile, wenn Sie Bibliotheken wie dotenv verwenden, stellen Sie sicher, dass diese Bibliotheken vor der Protokollierungsbibliothek initialisiert werden.

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

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in den @azure/Logger-Paketdokumenten.

Diagnostik

Cosmos Diagnostics-Feature bietet erweiterte Einblicke in alle Ihre Kundenvorgänge. Ein CosmosDiagnostics-Objekt wird zur Antwort aller Clientvorgänge hinzugefügt. wie

  • Punkt-Nachschlagevorgang : item.read(), container.create(), database.delete()
  • Abfragevorgang reponse -queryIterator.fetchAll(),
  • Massen- und Batchvorgänge -item.batch().
  • Fehler-/Ausnahmeantwortobjekte.

Ein CosmosDiagnostics-Objekt wird zur Antwort aller Clientvorgänge hinzugefügt. Es gibt 3 Cosmos-Diagnosestufen, Informationen, Debug und Debug-unsicher. Wenn nur Informationen für Produktionssysteme vorgesehen sind und Debug- und Debug-unsichere Daten während der Entwicklung und beim Debuggen verwendet werden sollen, da sie deutlich höhere Ressourcen verbrauchen. Cosmos Diagnostic Level kann auf 2 Arten festgelegt werden

  • Programmgesteuert
  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });
  • Verwenden von Umgebungsvariablen. (Die von umgebungsvariablen Variable festgelegte Diagnosestufe hat eine höhere Priorität, wenn sie über Clientoptionen festgelegt wird.)
  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Cosmos Diagnostic hat drei Mitglieder

  • ClientSideRequestStatistics-Typ: Enthält Aggregierte Diagnosedetails, einschließlich Metadatensuche, Wiederholungen, kontaktierte Endpunkte und Anforderungs- und Antwortstatistiken wie Nutzlastgröße und Dauer. (wird immer gesammelt, kann in Produktionssystemen verwendet werden.)

  • DiagnosticNode: Ist eine strukturähnliche Struktur, die detaillierte Diagnoseinformationen erfasst. Ähnlich wie har Aufzeichnung in Browsern. Dieses Feature ist standardmäßig deaktiviert und nur für das Debuggen von Nichtproduktionsumgebungen vorgesehen. (gesammelt auf Diagnoseebene debug- und debugunsicher)

  • ClientConfig: Erfasst wichtige Informationen im Zusammenhang mit den Konfigurationseinstellungen des Clients während der Clientinitialisierung. (gesammelt auf Diagnoseebene debug- und debugunsicher)

Stellen Sie sicher, dass Sie die Diagnosestufe niemals auf debug-unsafe in der Produktionsumgebung festlegen, da diese Ebene CosmosDiagnostics Anforderungs- und Antwortnutzlasten erfasst und wenn Sie dies protokollieren möchten (standardmäßig von @azure/logger auf verbose Ebene protokolliert). Diese Nutzlasten werden möglicherweise in Ihren Protokollsenken erfasst.

Verwenden von Diagnosen

  • Da diagnostics allen Antwortobjekten hinzugefügt wird. Sie können programmgesteuert wie folgt auf CosmosDiagnostic zugreifen.
  // 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
  }
  • Sie können auch diagnostics mit @azure/loggerprotokollieren, diagnose wird immer mit @azure/logger auf verbose-Ebene protokolliert. Wenn Sie also die Diagnosestufe auf debug oder debug-unsafe und @azure/logger Ebene auf verbosefestlegen, werden diagnostics protokolliert.

Nächste Schritte

Weitere Beispielcode

Mehrere Beispiele stehen Ihnen im GitHub-Repository des SDK zur Verfügung. Diese Beispiele stellen Beispielcode für zusätzliche Szenarien bereit, die beim Arbeiten mit Cosmos DB häufig auftreten:

  • Datenbankvorgänge
  • Containervorgänge
  • Elementvorgänge
  • Konfigurieren der Indizierung
  • Lesen eines Containeränderungsfeeds
  • Gespeicherte Prozeduren
  • Ändern von Datenbank-/Containerdurchsatzeinstellungen
  • Schreibvorgänge für mehrere Regionen

Begrenzungen

Derzeit werden die folgenden Features nicht unterstützt. Informationen zu alternativen Optionen finden Sie unten im Abschnitt Problemumgehungen.

Einschränkungen der Datenebene:

  • Abfragen mit COUNT aus einer DISTINCT-Unterabfrage
  • Direkter TCP-Moduszugriff
  • Aggregierte partitionsübergreifende Abfragen, z. B. Sortieren, Zählen und unterscheiden, unterstützen keine Fortsetzungstoken. Streambare Abfragen, z. B. SELECT * FROM WHERE , unterstützen Fortsetzungstoken. Informationen zum Ausführen nicht streambarer Abfragen ohne Fortsetzungstoken finden Sie im Abschnitt "Problemumgehung".
  • Feed ändern: Prozessor
  • Feed ändern: Lesen mehrerer Partitionen schlüsselwerte
  • Ändern der Feed-Pullmodellunterstützung für partielle hierarchische Partitionsschlüssel #27059
  • Partitionsübergreifende ORDER BY für gemischte Typen

    • Einschränkungen der Steuerebene:

    • Abrufen von CollectionSizeUsage-, DatabaseUsage- und DocumentUsage-Metriken
    • Geospatialindex erstellen
    • Aktualisieren des AutoScale-Durchsatzes

    Problemumgehungen

    Fortsetzungstoken für partitionsübergreifende Abfragen

    Sie können partitionsübergreifende Abfragen mit Unterstützung für Fortsetzungstoken erreichen, indem Sie Querwagenmusterverwenden. Mit diesem Muster können Anwendungen auch aus heterogenen Komponenten und Technologien bestehen.

    Ausführen einer nicht strembaren kreuzpartitionsübergreifenden Abfrage

    Um nicht streambare Abfragen ohne die Verwendung von Fortsetzungstoken auszuführen, können Sie einen Abfrage-Iterator mit der erforderlichen Abfragespezifikation und -optionen erstellen. Im folgenden Beispielcode wird veranschaulicht, wie Sie mit einem Abfrage-Iterator alle Ergebnisse abrufen können, ohne dass ein Fortsetzungstoken erforderlich ist:

    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
}

    Dieser Ansatz kann auch für streambare Abfragen verwendet werden.

    Steuern von Flugzeugvorgängen

    In der Regel können Sie Azure Portal, Azure Cosmos DB Resource Provider REST API, Azure CLI oder PowerShell- für die nicht unterstützten Einschränkungen der Steuerungsebene verwenden.

    Zusätzliche Dokumentation

    Ausführlichere Dokumentation zum Cosmos DB-Dienst finden Sie in der Azure Cosmos DB-Dokumentation zu docs.microsoft.com.

    Beitragend

    Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.

    Aufrufe