Azure Cosmos DB client library for JavaScript - version 4.9.0

/Maszynopis

Azure Cosmos DB to globalnie rozproszona, wielomodelowa usługa bazy danych, która obsługuje bazy danych dokumentów, klucz-wartość, szeroką kolumnę i grafowe bazy danych. Ten pakiet jest przeznaczony dla aplikacji JavaScript/TypeScript do interakcji z bazami danych interfejsu API SQL oraz dokumentami JSON, które zawierają:

• Tworzenie baz danych usługi Cosmos DB i modyfikowanie ich ustawień
• Tworzenie i modyfikowanie kontenerów w celu przechowywania kolekcji dokumentów JSON
• Tworzenie, odczytywanie, aktualizowanie i usuwanie elementów (dokumentów JSON) w kontenerach
• Wykonywanie zapytań dotyczących dokumentów w bazie danych przy użyciu składni podobnej do języka SQL

Kluczowe linki:

• pakiet (npm)
• Dokumentacja referencyjna interfejs u API
• dokumentacja produktu

Wprowadzenie

Warunki wstępne

Subskrypcja platformy Azure i konto interfejsu API SQL usługi Cosmos DB

Aby używać tego pakietu, musisz mieć subskrypcji platformy Azureoraz konto usługi Cosmos DB (interfejs API SQL).

Jeśli potrzebujesz konta interfejsu API SQL usługi Cosmos DB, możesz użyć usługi Azure Cloud Shell, aby utworzyć je za pomocą tego polecenia interfejsu wiersza polecenia platformy Azure:

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

Możesz też utworzyć konto w witrynie Azure Portal

Węzeł JS

Ten pakiet jest dystrybuowany za pośrednictwem npm, który jest wstępnie zainstalowany z NodeJS przy użyciu wersji LTS.

CORS

Musisz skonfigurować współużytkowanie zasobów między źródłami (CORS) reguł dla konta usługi Cosmos DB, jeśli musisz utworzyć aplikacje dla przeglądarek. Postępuj zgodnie z instrukcjami w połączonym dokumencie, aby utworzyć nowe reguły CORS dla usługi Cosmos DB.

Zainstaluj ten pakiet

npm install @azure/cosmos

Uzyskiwanie poświadczeń konta

Potrzebujesz punktu końcowego konta usługi Cosmos DB i klucza . Te informacje można znaleźć w Azure Portal lub użyć poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure . Fragment kodu jest sformatowany dla powłoki Bash.

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

Tworzenie wystąpienia CosmosClient

Interakcja z usługą Cosmos DB rozpoczyna się od wystąpienia klasy CosmosClient

import { CosmosClient } from "@azure/cosmos";

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

Dla uproszczenia dołączyliśmy key i endpoint bezpośrednio w kodzie, ale prawdopodobnie zechcesz załadować je z pliku, który nie znajduje się w kontroli źródła przy użyciu projektu, takiego jak dotenv lub ładowanie ze zmiennych środowiskowych

W środowiskach produkcyjnych wpisy tajne, takie jak klucze, powinny być przechowywane w usłudze Azure Key Vault

Kluczowe pojęcia

Po zainicjowaniu CosmosClientmożna wchodzić w interakcje z podstawowymi typami zasobów w usłudze Cosmos DB:

• Database: konto usługi Cosmos DB może zawierać wiele baz danych. Podczas tworzenia bazy danych należy określić interfejs API, którego chcesz użyć podczas interakcji z jego dokumentami: SQL, MongoDB, Gremlin, Cassandra lub Azure Table. Użyj obiektu Database do zarządzania kontenerami.

• Container: kontener jest kolekcją dokumentów JSON. Tworzenie (wstawianie), odczytywanie, aktualizowanie i usuwanie elementów w kontenerze przy użyciu metod w obiekcie kontenera .

• item: Element jest dokumentem JSON przechowywanym w kontenerze. Każdy element musi zawierać klucz id z wartością, która jednoznacznie identyfikuje element w kontenerze. Jeśli nie podasz id, zestaw SDK wygeneruje go automatycznie.

Aby uzyskać więcej informacji na temat tych zasobów, zobacz Praca z bazami danych, kontenerami i elementami usługi Azure Cosmos.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań usługi Cosmos DB, w tym:

• Tworzenie bazy danych
• Tworzenie kontenera
• przy użyciu kluczy partycji
• Wstaw elementy
• Wykonywanie zapytań dotyczących dokumentów
• Odczytywanie elementu
• Usuwanie elementu
• CRUD w kontenerze z hierarchicznym kluczem partycji
• Korzystanie z wykluczonych lokalizacji

Tworzenie bazy danych

Po uwierzytelnieniu CosmosClientmożesz pracować z dowolnym zasobem na koncie. Poniższy fragment kodu tworzy bazę danych interfejsu API NOSQL.

import { CosmosClient } from "@azure/cosmos";

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

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

Tworzenie kontenera

W tym przykładzie zostanie utworzony kontener z ustawieniami domyślnymi

import { CosmosClient } from "@azure/cosmos";

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

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
const { container } = await database.containers.createIfNotExists({ id: "Test Container" });

Używanie kluczy partycji

W tym przykładzie przedstawiono różne typy obsługiwanych kluczy partycji.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

Jeśli klucz partycji składa się z jednej wartości, może zostać podany jako wartość literału lub tablica.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

Jeśli klucz partycji składa się z więcej niż jednej wartości, powinien zostać podany jako tablica.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

Wstaw elementy

Aby wstawić elementy do kontenera, przekaż obiekt zawierający dane do Items.upsert. Usługa Azure Cosmos DB wymaga, aby każdy element miał klucz id. Jeśli go nie podasz, zestaw SDK automatycznie wygeneruje id.

W tym przykładzie wstawia kilka elementów do kontenera

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

Odczytywanie elementu

Aby odczytać pojedynczy element z kontenera, użyj Item.read. Jest to mniej kosztowna operacja niż używanie języka SQL do wykonywania zapytań przez id.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

CRUD w kontenerze z hierarchicznym kluczem partycji

Tworzenie kontenera z hierarchicznym kluczem partycji

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

Wstaw element z hierarchicznym kluczem partycji zdefiniowanym jako — ["/name", "/address/zip"]

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

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

Aby odczytać pojedynczy element z kontenera z hierarchicznym kluczem partycji zdefiniowanym jako — ["/name", "/address/zip"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

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

Wykonywanie zapytań o element z hierarchicznym kluczem partycji z hierarchicznym kluczem partycji zdefiniowanym jako — ["/name", "/address/zip"],

import { CosmosClient, PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
    partitionKey: ["foo", 100],
  })
  .fetchAll();

Usuwanie elementu

Aby usunąć elementy z kontenera, użyj Item.delete.

import { CosmosClient } from "@azure/cosmos";

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

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

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

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

Wykonywanie zapytań względem bazy danych

Baza danych interfejsu API SQL usługi Cosmos DB obsługuje wykonywanie zapytań dotyczących elementów w kontenerze przy użyciu Items.query przy użyciu składni podobnej do języka SQL:

import { CosmosClient } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();

Wykonywanie zapytań sparametryzowanych przez przekazanie obiektu zawierającego parametry i ich wartości do Items.query:

import { CosmosClient } from "@azure/cosmos";

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

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

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

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }],
  })
  .fetchAll();

Aby uzyskać więcej informacji na temat wykonywania zapytań dotyczących baz danych usługi Cosmos DB przy użyciu interfejsu API SQL, zobacz Query Azure Cosmos DB data with SQL query with SQL query (Wykonywanie zapytań w usłudze Azure Cosmos DB przy użyciu zapytań SQL).

Model ściągania zestawienia zmian

Źródło zmian można pobrać dla klucza partycji, zakresu kanału informacyjnego lub całego kontenera.

Aby przetworzyć zestawienie zmian, utwórz wystąpienie ChangeFeedPullModelIterator. Podczas początkowego tworzenia ChangeFeedPullModelIteratornależy określić wymaganą wartość changeFeedStartFrom wewnątrz ChangeFeedIteratorOptions, która składa się zarówno z pozycji początkowej do odczytywania zmian, jak i zasobu (klucza partycji lub elementu FeedRange), dla którego mają zostać pobrane zmiany. Opcjonalnie możesz użyć maxItemCount w ChangeFeedIteratorOptions, aby ustawić maksymalną liczbę odebranych elementów na stronę.

Uwaga: Jeśli nie zostanie określona żadna wartość changeFeedStartFrom, zostanie pobrana zmiana kanału dla całego kontenera z Now().

Istnieją cztery pozycje początkowe dla zestawienia zmian:

• Beginning

import { ChangeFeedStartFrom } from "@azure/cosmos";

const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};

• Time

import { ChangeFeedStartFrom } from "@azure/cosmos";

const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

• Now

import { ChangeFeedStartFrom } from "@azure/cosmos";

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

• Continuation

import { ChangeFeedStartFrom } from "@azure/cosmos";

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

Oto przykład pobierania zestawienia zmian dla klucza partycji

import {
  CosmosClient,
  PartitionKeyDefinitionVersion,
  PartitionKeyKind,
  ChangeFeedStartFrom,
} from "@azure/cosmos";

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

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

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

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
}

Ponieważ kanał informacyjny zmian jest w rzeczywistości nieskończoną listą elementów obejmujących wszystkie przyszłe zapisy i aktualizacje, wartość hasMoreResults jest zawsze true. Podczas próby odczytania zestawienia zmian i braku dostępnych nowych zmian otrzymasz odpowiedź ze stanem NotModified.

Bardziej szczegółowe wskazówki dotyczące użycia i przykłady zestawienia zmian można znaleźć tutaj.

Korzystanie z wykluczonych lokalizacji

Opcja excludedLocations na poziomie żądania umożliwia użytkownikowi określenie co najmniej jednego regionu świadczenia usługi Azure, który powinien zostać wykluczony z obsługi żądania. Jest to przydatne w scenariuszach, w których użytkownik chce uniknąć niektórych regionów ze względu na problemy ze zgodnością, opóźnieniami lub dostępnością. Po ustawieniu usługa Cosmos DB przekieruje żądanie do innych dostępnych regionów, poprawiając kontrolę nad rezydencją danych i zachowaniem trybu failover.

excludedLocations jest stosowany tylko wtedy, gdy enableEndPointDiscovery jest ustawiony na wartość true.

W tym przykładzie przedstawiono różne interfejsy API obsługujące wykluczone lokalizacje.

import { CosmosClient, ChangeFeedStartFrom } from "@azure/cosmos";

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

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

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

const city = { id: "1", name: "Olympia", state: "WA" };
await container.items.upsert(city, { excludedLocations: ["Test Region"] });

const iterator = container.items.getChangeFeedIterator({
  excludedLocations: ["Test Region"],
  maxItemCount: 1,
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
});

const response = await iterator.readNext();

Obsługa błędów

Zestaw SDK generuje różne typy błędów, które mogą wystąpić podczas operacji.

1. ErrorResponse jest zgłaszany, jeśli odpowiedź operacji zwraca kod błędu >=400.
2. TimeoutError jest zgłaszany, jeśli abort jest wywoływany wewnętrznie z powodu przekroczenia limitu czasu.
3. AbortError jest zgłaszany, jeśli jakikolwiek użytkownik przeszedł sygnał spowodował przerwanie.
4. RestError jest zgłaszany w przypadku awarii bazowego wywołania systemu z powodu problemów z siecią.
5. Błędy generowane przez wszystkie metodyki devDependencies. Na przykład @azure/identity pakiet może zgłaszać CredentialUnavailableError.

Poniżej przedstawiono przykład obsługi błędów typu ErrorResponse, TimeoutError, AbortErrori RestError.

import { ErrorResponse, RestError } from "@azure/cosmos";

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

Ważne jest, aby prawidłowo obsługiwać te błędy, aby upewnić się, że aplikacja może bezpiecznie odzyskać sprawność po wszelkich awariach i kontynuować działanie zgodnie z oczekiwaniami. Więcej szczegółów na temat niektórych z tych błędów i ich możliwych rozwiązań można znaleźć tutaj.

Rozwiązywanie problemów

Ogólne

W przypadku interakcji z błędami usługi Cosmos DB zwracanymi przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST:

kody stanu HTTP dla usługi Azure Cosmos DB

Konflikty

Jeśli na przykład spróbujesz utworzyć element przy użyciu id, który jest już używany w bazie danych usługi Cosmos DB, zostanie zwrócony błąd 409 wskazujący konflikt. W poniższym fragmencie kodu błąd jest obsługiwany bezpiecznie przez przechwycenie wyjątku i wyświetlenie dodatkowych informacji o błędzie.

import { CosmosClient, ErrorResponse, RestError } from "@azure/cosmos";

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

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

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

try {
  await container.items.create({ id: "existing-item-id" });
} catch (error) {
  const err = error as ErrorResponse | RestError;
  if (err.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Transpilowanie

Zestawy SDK platformy Azure są przeznaczone do obsługi składni języka JavaScript w wersji ES5 i LTS Node.js. Jeśli potrzebujesz obsługi wcześniejszych środowisk uruchomieniowych języka JavaScript, takich jak Internet Explorer lub Node 6, konieczne będzie transpilowanie kodu zestawu SDK w ramach procesu kompilacji.

Obsługa błędów przejściowych przy użyciu ponownych prób

Podczas pracy z usługą Cosmos DB mogą wystąpić przejściowe błędy spowodowane przez limity szybkości wymuszone przez usługę lub inne przejściowe problemy, takie jak awarie sieci. Aby uzyskać informacje na temat obsługi tego typu błędów, zobacz Wzorzec ponawiania prób w przewodniku Wzorce projektowania chmury oraz powiązany wzorzec wyłącznika .

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując setLogLevel w @azure/logger. Podczas korzystania z AZURE_LOG_LEVEL przed zainicjowaniem biblioteki rejestrowania upewnij się, że została ustawiona. Najlepiej przekazać go za pośrednictwem wiersza polecenia, jeśli używasz bibliotek, takich jak dotenv upewnij się, że takie biblioteki są inicjowane przed biblioteką rejestrowania.

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Diagnostyka

Funkcja diagnostyki cosmos zapewnia ulepszony wgląd we wszystkie operacje klienta. Obiekt CosmosDiagnostics jest dodawany do odpowiedzi na wszystkie operacje klienta. jak

• Reponse operacji wyszukiwania punktów — item.read(), container.create(), database.delete()
• Reponse operacji kwerendy —queryIterator.fetchAll(),
• Operacje zbiorcze i wsadowe —item.batch().
• Obiekty odpowiedzi błędów/wyjątków.

Obiekt CosmosDiagnostics jest dodawany do odpowiedzi na wszystkie operacje klienta. Istnieją 3 poziomy diagnostyki cosmos, informacje, debugowanie i debugowanie niebezpieczne. Jeśli tylko informacje są przeznaczone dla systemów produkcyjnych, a debugowanie i debugowanie niebezpieczne są przeznaczone do użycia podczas programowania i debugowania, ponieważ zużywają znacznie wyższe zasoby. Poziom diagnostyki usługi Cosmos można ustawić na 2 sposoby

• Programowo

import { CosmosClient, CosmosDbDiagnosticLevel } from "@azure/cosmos";

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

• Używanie zmiennych środowiskowych. (Poziom diagnostyczny ustawiony przez zmienną środowiskową ma wyższy priorytet niż ustawienie go za pośrednictwem opcji klienta).

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

Diagnostyka cosmos ma trzy elementy członkowskie

• Typ ClientSideRequestStatistics: zawiera zagregowane szczegóły diagnostyczne, w tym wyszukiwania metadanych, ponawiania prób, kontaktowanych punktów końcowych oraz statystyk żądania i odpowiedzi, takich jak rozmiar ładunku i czas trwania. (jest zawsze zbierane, można ich używać w systemach produkcyjnych).

• DiagnosticNode: to struktura podobna do drzewa, która przechwytuje szczegółowe informacje diagnostyczne. Podobnie jak rejestrowanie har obecne w przeglądarkach. Ta funkcja jest domyślnie wyłączona i jest przeznaczona tylko do debugowania środowisk nieprodukcyjnych. (zbierane na poziomie diagnostyki — debugowanie i debugowanie niebezpieczne)

• ClientConfig: przechwytuje podstawowe informacje związane z ustawieniami konfiguracji klienta podczas inicjowania klienta. (zbierane na poziomie diagnostyki — debugowanie i debugowanie niebezpieczne)

Pamiętaj, aby nigdy nie ustawić poziomu diagnostyki na debug-unsafe w środowisku produkcyjnym, ponieważ ten poziom CosmosDiagnostics przechwytuje ładunki żądań i odpowiedzi, a jeśli zdecydujesz się go zarejestrować (domyślnie jest rejestrowany przez @azure/logger na poziomie verbose). Te ładunki mogą zostać przechwycone w ujściach dziennika.

Korzystanie z diagnostyki

• Ponieważ diagnostics jest dodawany do wszystkich obiektów Odpowiedzi. Można programowo uzyskać dostęp do CosmosDiagnostic w następujący sposób.

import {
  CosmosClient,
  CosmosDbDiagnosticLevel,
  OperationInput,
  BulkOperationType,
} from "@azure/cosmos";

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

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
// For point look up operations

const { container, diagnostics: containerCreateDiagnostic } =
  await database.containers.createIfNotExists({
    id: "<container-id>",
    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;
}

• Można również rejestrować diagnostics przy użyciu @azure/logger, diagnostyka jest zawsze rejestrowana przy użyciu @azure/logger na poziomie verbose. Dlatego jeśli ustawisz poziom diagnostyki na debug lub debug-unsafe i @azure/logger na verbose, diagnostics zostaną zarejestrowane.

Następne kroki

Więcej przykładowego kodu

Kilka przykładów jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy, które często występują podczas pracy z usługą Cosmos DB:

• Operacje bazy danych
• Operacje kontenera
• Operacje na elementach
• Konfigurowanie indeksowania
• Odczytywanie zestawienia zmian kontenera
• Procedury składowane
• Zmienianie ustawień przepływności bazy danych/kontenera
• Operacje zapisu w wielu regionach

Ograniczenia

Obecnie poniższe funkcje są nieobsługiwane. Aby zapoznać się z opcjami alternatywnymi, zapoznaj się z sekcją Obejścia poniżej.

• Szyfrowanie po stronie klienta nie jest obecnie obsługiwane w środowisku przeglądarki.

Ograniczenia płaszczyzny danych:

• Zapytania z licznikiem liczby z podzapytania DISTINCT
• Bezpośredni dostęp do trybu TCP
• Agregowanie zapytań między partycjami, takich jak sortowanie, liczenie i unikatowe, nie obsługują tokenów kontynuacji. Zapytania przesyłane strumieniowo, takie jak SELECT * FROM Warunek< WHERE>, tokeny kontynuacji obsługi. Zobacz sekcję "Obejście", aby wykonać zapytania niezwiązane z przesyłaniem strumieniowym bez tokenu kontynuacji.
• Zestawienie zmian: procesor
• Zestawienie zmian: odczytywanie wielu wartości klucza partycji
• Funkcja ORDER BY między partycjami dla typów mieszanych

Ograniczenia płaszczyzny sterowania:

• Pobieranie metryk CollectionSizeUsage, DatabaseUsage i DocumentUsage
• Tworzenie indeksu geoprzestrzennych
• Aktualizowanie przepływności autoskalowania

Obejścia

Token kontynuacji dla zapytań obejmujących wiele partycji

Zapytania między partycjami można uzyskać z obsługą tokenów kontynuacji przy użyciu wzorca samochodu Side. Ten wzorzec może również umożliwić aplikacjom tworzenie heterogenicznych składników i technologii.

Wykonywanie zapytania między partycjami, które nie można przesyłać strumieniowo

Aby wykonywać zapytania niezwiązane ze strumieniem bez użycia tokenów kontynuacji, można utworzyć iterator zapytań z wymaganą specyfikacją i opcjami zapytania. Poniższy przykładowy kod pokazuje, jak używać iteratora zapytań do pobierania wszystkich wyników bez konieczności użycia tokenu kontynuacji:

import { CosmosClient } from "@azure/cosmos";

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

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

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

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 queryIterator = container.items.query(querySpec, queryOptions);
while (queryIterator.hasMoreResults()) {
  const { resources: result } = await queryIterator.fetchNext();
  // process results
}

Takie podejście może być również używane w przypadku zapytań przesyłanych strumieniowo.

Operacje płaszczyzny sterowania

Zazwyczaj można użyć witryny Azure Portal, interfejsu API REST dostawcy zasobów usługi Azure Cosmos DB, interfejsu wiersza polecenia platformy Azure lub programu PowerShell dla nieobsługiwanych ograniczeń płaszczyzny sterowania.

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Cosmos DB, zobacz dokumentację usługi Azure Cosmos DB w systemie learn.microsoft.com.

Przydatne linki

• Witamy w usłudze Azure Cosmos DB
• Szybki start
• Samouczek
• przykładów
• wprowadzenie do modelu zasobów usługi Azure Cosmos DB
• Wprowadzenie do interfejsu API SQL usługi Azure Cosmos DB
• partycjonowanie
• dokumentacja interfejsu API

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.