Biblioteka klienta usługi Azure Cosmos DB dla języka JavaScript — wersja 4.2.0

Artykuł
11/20/2024

/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

NodeJS

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

MECHANIZM 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

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

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

Tworzenie bazy danych

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

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

Tworzenie kontenera

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

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

Używanie kluczy partycji

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

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.

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.

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

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.

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

CRUD w kontenerze z hierarchicznym kluczem partycji

Tworzenie kontenera z hierarchicznym kluczem partycji

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

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

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"],

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

Wykonywanie zapytań o element z hierarchicznym kluczem partycji z hierarchicznym kluczem partycji zdefiniowanym jako — ["/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} `);
}

Usuwanie elementu

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

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

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

Wykonywanie zapytań sparametryzowanych przez przekazanie obiektu zawierającego parametry i ich wartości do 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 `);
}

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

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

Oto przykład pobierania zestawienia zmian dla klucza partycji

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.

Obsługa błędów

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

ErrorResponse jest zgłaszany, jeśli odpowiedź operacji zwraca kod błędu >=400.
TimeoutError jest zgłaszany, jeśli abort jest wywoływany wewnętrznie z powodu przekroczenia limitu czasu.
AbortError jest zgłaszany, jeśli jakikolwiek użytkownik przeszedł sygnał spowodował przerwanie.
RestError jest zgłaszany w przypadku awarii bazowego wywołania systemu z powodu problemów z siecią.
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.

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.

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

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.

const { setLogLevel } = require("@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

  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.

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

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.

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 WHERE , obsługują tokeny kontynuacji. 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
Obsługa modelu ściągania zestawienia zmian dla częściowych hierarchicznych kluczy partycji #27059
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 obejmującego niezrównywalne z podziałem na partycje

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:

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
}

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

wrażenia

Udostępnij za pośrednictwem