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