Szybki start: tworzenie interfejsu API dla aplikacji tabel przy użyciu Node.js i usługi Azure Cosmos DB
DOTYCZY:
Tabeli
W tym przewodniku Szybki start utworzysz konto usługi Azure Cosmos DB dla tabel i użyjesz Data Explorer i aplikacji Node.js sklonowanej z usługi GitHub, aby utworzyć tabele i jednostki. Azure Cosmos DB to wielomodelowa usługa bazy danych, która umożliwia szybkie tworzenie i wykonywanie zapytań dotyczących dokumentów, tabel, klucz-wartość i grafowych baz danych z globalną dystrybucją i możliwościami skalowania w poziomie.
Wymagania wstępne
- Konto platformy Azure z aktywną subskrypcją. Utwórz go bezpłatnie.
- Node.js 0.10.29+ .
- Git.
Przykładowa aplikacja
Przykładowa aplikacja dla tego samouczka może zostać sklonowana lub pobrana z repozytorium https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. Zarówno początkowa, jak i ukończona aplikacja są uwzględniane w przykładowym repozytorium.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Przykładowa aplikacja używa danych pogodowych jako przykładu, aby zademonstrować możliwości interfejsu API dla tabeli. Obiekty reprezentujące obserwacje pogodowe są przechowywane i pobierane przy użyciu interfejsu API dla tabeli, w tym przechowywania obiektów z dodatkowymi właściwościami w celu zademonstrowania możliwości bez schematu interfejsu API dla tabeli.
1 — Tworzenie konta usługi Azure Cosmos DB
Najpierw musisz utworzyć konto interfejsu API tabel usługi Azure Cosmos DB, które będzie zawierać tabele używane w aplikacji. Można to zrobić przy użyciu Azure Portal, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell.
Zaloguj się do Azure Portal i wykonaj następujące kroki, aby utworzyć konto usługi Azure Cosmos DB.
| Instrukcje | Zrzut ekranu |
|---|---|
W witrynie Azure Portal:
|
|
| Na stronie usługi Azure Cosmos DB wybierz pozycję +Utwórz. | 
|
| Na stronie Wybierz interfejs API wybierz opcję Tabela platformy Azure . | 
|
Na stronie Tworzenie konta usługi Azure Cosmos DB — tabela platformy Azure wypełnij formularz w następujący sposób.
|
|
2 — Tworzenie tabeli
Następnie należy utworzyć tabelę na koncie usługi Azure Cosmos DB, aby aplikacja mogła jej używać. W przeciwieństwie do tradycyjnej bazy danych wystarczy określić nazwę tabeli, a nie właściwości (kolumny) w tabeli. Gdy dane zostaną załadowane do tabeli, właściwości (kolumny) zostaną automatycznie utworzone zgodnie z potrzebami.
W Azure Portal wykonaj następujące kroki, aby utworzyć tabelę na koncie usługi Azure Cosmos DB.
| Instrukcje | Zrzut ekranu |
|---|---|
| W Azure Portal przejdź do strony przeglądu konta usługi Azure Cosmos DB. Możesz przejść do strony przeglądu konta usługi Azure Cosmos DB, wpisując nazwę (cosmos-msdocs-tables-sdk-demo-XYZ) konta usługi Azure Cosmos DB na górnym pasku wyszukiwania i patrząc pod nagłówkiem zasobów. Wybierz nazwę konta usługi Azure Cosmos DB, aby przejść do strony przeglądu. | 
|
| Na stronie przeglądu wybierz pozycję +Dodaj tabelę. Okno dialogowe Nowa tabela zostanie wyświetlone z prawej strony. | 
|
W oknie dialogowym Nowa tabela wypełnij formularz w następujący sposób.
|
|
3 — Pobieranie parametrów połączenia usługi Azure Cosmos DB
Aby uzyskać dostęp do tabel w usłudze Azure Cosmos DB, aplikacja będzie potrzebować parametrów połączenia tabeli dla konta usługi CosmosDB Storage. Parametry połączenia można pobrać przy użyciu Azure Portal, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell.
| Instrukcje | Zrzut ekranu |
|---|---|
| Po lewej stronie strony konta usługi Azure Cosmos DB znajdź element menu o nazwie Parametry połączenia w nagłówku Ustawienia i wybierz go. Nastąpi przekierowanie do strony, na której można pobrać parametry połączenia dla konta usługi Azure Cosmos DB. | 
|
| Skopiuj wartość PODSTAWOWE PARAMETRY POŁĄCZENIA do użycia w aplikacji. | 
|
4 — Instalowanie zestawu SDK tabel danych platformy Azure dla środowiska JS
Aby uzyskać dostęp do usługi Azure Cosmos DB for Table z poziomu aplikacji nodejs, zainstaluj pakiet zestawu SDK tabel danych platformy Azure .
npm install @azure/data-tables
5 — Konfigurowanie klienta tabeli w pliku env.js
Skopiuj parametry połączenia konta usługi Azure Cosmos DB lub magazynu z Azure Portal i utwórz obiekt TableServiceClient przy użyciu skopiowanych parametrów połączenia. Przejdź do folderu 1-strater-app lub 2-completed-app. Następnie dodaj wartość odpowiednich zmiennych środowiskowych w configure/env.js pliku.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Zestaw Azure SDK komunikuje się z platformą Azure przy użyciu obiektów klienta w celu wykonywania różnych operacji na platformie Azure. Klasa TableClient jest klasą używaną do komunikowania się z usługą Azure Cosmos DB for Table. Aplikacja zazwyczaj tworzy pojedynczy serviceClient obiekt na tabelę do użycia w całej aplikacji.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 — Implementowanie operacji tabeli usługi Azure Cosmos DB
Wszystkie operacje tabeli usługi Azure Cosmos DB dla przykładowej aplikacji są implementowane w serviceClient obiekcie znajdującym się w pliku w tableClient.js katalogu usługi .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Pobieranie wierszy z tabeli
Obiekt serviceClient zawiera metodę o nazwie listEntities , która umożliwia wybieranie wierszy z tabeli. W tym przykładzie, ponieważ żadne parametry nie są przekazywane do metody, wszystkie wiersze zostaną wybrane z tabeli.
const allRowsEntities = serviceClient.listEntities();
Filtrowanie wierszy zwracanych z tabeli
Aby filtrować wiersze zwracane z tabeli, możesz przekazać ciąg filtru stylu OData do listEntities metody . Jeśli na przykład chcesz uzyskać wszystkie odczyty pogodowe dla Chicago między północą 1 lipca 2021 r. a północą 2 lipca 2021 r. (włącznie), przekaż następujący ciąg filtru.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Wszystkie operatory filtrów OData można wyświetlić w witrynie internetowej OData w sekcji Filtruj opcję zapytania systemowego.
Gdy parametr request.args jest przekazywany do listEntities metody w serviceClient klasie, tworzy ciąg filtru dla każdej wartości właściwości innej niż null. Następnie tworzy połączony ciąg filtru, łącząc wszystkie wartości z klauzulą "and". Ten połączony ciąg filtru jest przekazywany do metody w serviceClient obiekcie i zwracane będą tylko wiersze pasujące do listEntities ciągu filtru. Możesz użyć podobnej metody w kodzie, aby utworzyć odpowiednie ciągi filtru zgodnie z wymaganiami aplikacji.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
Wstawianie danych przy użyciu obiektu TableEntity
Najprostszym sposobem dodawania danych do tabeli jest użycie TableEntity obiektu. W tym przykładzie dane są mapowane z obiektu modelu wejściowego TableEntity na obiekt. Właściwości obiektu wejściowego reprezentującego nazwę stacji pogodowej i datę/godzinę obserwacji są mapowane odpowiednio na PartitionKey właściwości i RowKey , które razem tworzą unikatowy klucz dla wiersza w tabeli. Następnie dodatkowe właściwości obiektu modelu wejściowego są mapowane na właściwości słownika w obiekcie TableEntity. createEntity Na koniec metoda obiektu serviceClient służy do wstawiania danych do tabeli.
Zmodyfikuj insertEntity funkcję w przykładowej aplikacji, aby zawierała następujący kod.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Dane upsert używające obiektu TableEntity
Jeśli spróbujesz wstawić wiersz do tabeli z kombinacją klucza partycji/klucza wiersza, która już istnieje w tej tabeli, zostanie wyświetlony błąd. Z tego powodu często zaleca się użycie upsertEntity metody zamiast createEntity metody podczas dodawania wierszy do tabeli. Jeśli dana kombinacja klucza partycji/klucza wiersza już istnieje w tabeli, upsertEntity metoda zaktualizuje istniejący wiersz. W przeciwnym razie wiersz zostanie dodany do tabeli.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Wstawianie lub upsert danych z właściwościami zmiennych
Jedną z zalet korzystania z usługi Azure Cosmos DB for Table jest to, że jeśli obiekt ładowany do tabeli zawiera jakiekolwiek nowe właściwości, te właściwości są automatycznie dodawane do tabeli i wartości przechowywane w usłudze Azure Cosmos DB. Nie ma potrzeby uruchamiania instrukcji DDL, takich jak ALTER TABLE, aby dodać kolumny tak jak w tradycyjnej bazie danych.
Ten model zapewnia elastyczność aplikacji podczas pracy ze źródłami danych, które mogą dodawać lub modyfikować dane, które muszą być przechwytywane w czasie lub gdy różne dane wejściowe dostarczają różne dane do aplikacji. W przykładowej aplikacji możemy symulować stację pogodową, która wysyła nie tylko podstawowe dane pogodowe, ale także kilka dodatkowych wartości. Gdy obiekt z tymi nowymi właściwościami jest przechowywany w tabeli po raz pierwszy, odpowiednie właściwości (kolumny) zostaną automatycznie dodane do tabeli.
Aby wstawić lub upsert taki obiekt przy użyciu interfejsu API dla tabeli, zamapuj właściwości obiektu rozszerzalnego na TableEntity obiekt i użyj createEntity metod or upsertEntity w serviceClient obiekcie odpowiednio.
W przykładowej aplikacji upsertEntity funkcja może również zaimplementować funkcję wstawiania lub upsert danych z właściwościami zmiennych
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Aktualizowanie jednostki
Jednostki można zaktualizować, wywołując metodę updateEntity w serviceClient obiekcie.
W przykładowej aplikacji ten obiekt jest przekazywany do upsertEntity metody w serviceClient obiekcie. Aktualizuje ten obiekt jednostki i używa upsertEntity metody zapisywania aktualizacji w bazie danych.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 — Uruchamianie kodu
Uruchom przykładową aplikację, aby korzystać z usługi Azure Cosmos DB for Table. Przy pierwszym uruchomieniu aplikacji nie będzie żadnych danych, ponieważ tabela jest pusta. Użyj dowolnych przycisków w górnej części aplikacji, aby dodać dane do tabeli.
Wybranie przycisku Wstaw przy użyciu jednostki tabeli powoduje otwarcie okna dialogowego umożliwiającego wstawianie lub upsert nowego wiersza przy użyciu TableEntity obiektu.
Wybranie przycisku Wstaw przy użyciu danych rozwijanych powoduje wyświetlenie okna dialogowego umożliwiającego wstawianie obiektu z właściwościami niestandardowymi, co pokazuje, jak usługa Azure Cosmos DB for Table automatycznie dodaje właściwości (kolumny) do tabeli w razie potrzeby. Użyj przycisku Dodaj pole niestandardowe , aby dodać co najmniej jedną nową właściwości i zademonstrować tę możliwość.
Użyj przycisku Wstaw przykładowe dane , aby załadować przykładowe dane do tabeli usługi Azure Cosmos DB.
Wybierz element Filtruj wyniki w górnym menu, który ma zostać przeniesiony do strony Wyniki filtrowania. Na tej stronie wypełnij kryteria filtrowania, aby pokazać, jak można skompilować i przekazać klauzulę filtru do usługi Azure Cosmos DB for Table.
Czyszczenie zasobów
Po zakończeniu pracy z przykładową aplikacją należy usunąć wszystkie zasoby platformy Azure związane z tym artykułem z konta platformy Azure. Można to zrobić, usuwając grupę zasobów.
Grupę zasobów można usunąć przy użyciu Azure Portal, wykonując następujące czynności.
| Instrukcje | Zrzut ekranu |
|---|---|
| Aby przejść do grupy zasobów, na pasku wyszukiwania wpisz nazwę grupy zasobów. Następnie na karcie Grupy zasobów wybierz nazwę grupy zasobów. | 
|
| Wybierz pozycję Usuń grupę zasobów na pasku narzędzi w górnej części strony grupy zasobów. | 
|
Po prawej stronie ekranu zostanie wyświetlone okno dialogowe z prośbą o potwierdzenie usunięcia grupy zasobów.
|
|
Następne kroki
W tym przewodniku Szybki start wyjaśniono sposób tworzenia konta usługi Azure Cosmos DB, tworzenia tabeli za pomocą Eksploratora danych i uruchamiania aplikacji. Teraz możesz wykonywać zapytania dotyczące danych przy użyciu interfejsu API dla tabeli.