Rychlý start: Vytvoření rozhraní API pro aplikaci Table pomocí Node.js a Azure Cosmos DB
PLATÍ PRO:
Tabulka
V tomto rychlém startu vytvoříte účet Azure Cosmos DB for Table a použijete Data Explorer a aplikaci Node.js naklonovanou z GitHubu k vytváření tabulek a entit. Azure Cosmos DB je vícemodelová databázová služba, která umožňuje rychle vytvářet a dotazovat databáze dokumentů, tabulek, klíč-hodnota a grafů s možnostmi globální distribuce a horizontálního škálování.
Požadavky
- Účet Azure s aktivním předplatným. Vytvořte si ho zdarma.
- Node.js 0.10.29+ .
- Git.
Ukázková aplikace
Ukázkovou aplikaci pro tento kurz můžete naklonovat nebo stáhnout z úložiště https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. Úvodní i dokončená aplikace jsou součástí ukázkového úložiště.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Ukázková aplikace používá data o počasí jako příklad k předvedení možností rozhraní API pro Table. Objekty představující pozorování počasí se ukládají a načítají pomocí rozhraní API pro tabulku, včetně ukládání objektů s dalšími vlastnostmi, které demonstrují možnosti rozhraní API pro table bez schémat.
1. Vytvoření účtu služby Azure Cosmos DB
Nejprve musíte vytvořit účet rozhraní API tabulek služby Azure Cosmos DB, který bude obsahovat tabulky použité ve vaší aplikaci. Můžete to provést pomocí Azure Portal, Azure CLI nebo Azure PowerShell.
Přihlaste se k Azure Portal a pomocí těchto kroků vytvořte účet služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
Na webu Azure Portal:
|
|
| Na stránce Azure Cosmos DB vyberte +Vytvořit. | 
|
| Na stránce Vybrat možnost rozhraní API zvolte možnost Azure Table . | 
|
Na stránce Vytvoření účtu služby Azure Cosmos DB – tabulka Azure vyplňte formulář následujícím způsobem.
|
|
2. Vytvoření tabulky
Dále musíte vytvořit tabulku v rámci účtu služby Azure Cosmos DB, kterou bude vaše aplikace používat. Na rozdíl od tradiční databáze stačí zadat pouze název tabulky, nikoli vlastnosti (sloupce) v tabulce. Po načtení dat do tabulky se vlastnosti (sloupce) automaticky vytvoří podle potřeby.
V Azure Portal proveďte následující kroky a vytvořte tabulku uvnitř účtu služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
| V Azure Portal přejděte na stránku přehledu účtu služby Azure Cosmos DB. Na stránku s přehledem účtu služby Azure Cosmos DB můžete přejít tak, že do horního panelu hledání zadáte název (cosmos-msdocs-tables-sdk-demo-XYZ) vašeho účtu služby Azure Cosmos DB a podíváte se pod nadpis prostředky. Výběrem názvu účtu služby Azure Cosmos DB přejděte na stránku přehledu. | 
|
| Na stránce přehledu vyberte +Přidat tabulku. Dialogové okno Nová tabulka se vysune z pravé strany stránky. | 
|
V dialogovém okně Nová tabulka vyplňte formulář následujícím způsobem.
|
|
3. Získání připojovacího řetězce služby Azure Cosmos DB
Pro přístup k tabulce ve službě Azure Cosmos DB bude vaše aplikace potřebovat připojovací řetězec tabulky pro účet služby CosmosDB Storage. Připojovací řetězec je možné načíst pomocí Azure Portal, Azure CLI nebo Azure PowerShell.
| Pokyny | Snímek obrazovky |
|---|---|
| Na levé straně stránky účtu služby Azure Cosmos DB vyhledejte položku nabídky s názvem Připojovací řetězec pod záhlavím Nastavení a vyberte ji. Přejdete na stránku, kde můžete načíst připojovací řetězec pro účet služby Azure Cosmos DB. | 
|
| Zkopírujte hodnotu PRIMARY CONNECTION STRING (PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC ), kterou chcete použít ve své aplikaci. | 
|
4. Instalace sady SDK pro tabulky dat Azure pro JS
Pokud chcete získat přístup ke službě Azure Cosmos DB for Table z aplikace nodejs, nainstalujte balíček Azure Data Tables SDK .
npm install @azure/data-tables
5 – Konfigurace klienta tabulky v souboru env.js
Zkopírujte připojovací řetězec účtu služby Azure Cosmos DB nebo účtu úložiště z Azure Portal a pomocí zkopírovaného připojovacího řetězce vytvořte objekt TableServiceClient. Přepněte do složky 1-strater-app nebo 2-completed-app. Pak do souboru přidejte hodnotu odpovídajících proměnných configure/env.js prostředí.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Sada Azure SDK komunikuje s Azure pomocí klientských objektů za účelem provádění různých operací v Azure. Třída TableClient je třída, která se používá ke komunikaci se službou Azure Cosmos DB for Table. Aplikace obvykle vytvoří pro každou tabulku jeden serviceClient objekt, který se bude používat v celé aplikaci.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6. Implementace operací s tabulkami Azure Cosmos DB
Všechny operace tabulek Azure Cosmos DB pro ukázkovou aplikaci se implementují v objektu umístěném serviceClient v souboru v tableClient.js adresáři služby .
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Získání řádků z tabulky
Objekt serviceClient obsahuje metodu s názvem listEntities , která umožňuje vybrat řádky z tabulky. V tomto příkladu se metodě nepředávají žádné parametry, a proto se z tabulky vyberou všechny řádky.
const allRowsEntities = serviceClient.listEntities();
Filtrování řádků vrácených z tabulky
Pokud chcete filtrovat řádky vrácené z tabulky, můžete metodě listEntities předat řetězec filtru stylu OData. Pokud byste například chtěli získat všechny údaje o počasí v Chicagu mezi půlnocí 1. července 2021 a půlnocí 2. července 2021 (včetně), předali byste následující řetězec filtru.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00' and RowKey le '2021-07-02 12:00'
Všechny operátory filtru OData na webu OData si můžete prohlédnout v části Filtrování systémového dotazu.
Když je parametr request.args předán listEntities metodě ve serviceClient třídě , vytvoří řetězec filtru pro každou hodnotu vlastnosti, která není null. Potom vytvoří kombinovaný řetězec filtru spojením všech hodnot do klauzule "a". Tento kombinovaný řetězec filtru se předá listEntities metodě objektu serviceClient a vrátí se pouze řádky odpovídající řetězci filtru. Podobnou metodu můžete použít v kódu k vytvoření vhodných řetězců filtru podle požadavků vaší aplikace.
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;
};
Vložení dat pomocí objektu TableEntity
Nejjednodušší způsob, jak přidat data do tabulky, je použít TableEntity objekt. V tomto příkladu se data mapují ze vstupního objektu TableEntity modelu na objekt. Vlastnosti vstupního objektu představující název meteorologické stanice a datum a čas pozorování jsou mapovány na PartitionKey vlastnosti a , RowKey které společně tvoří jedinečný klíč pro řádek v tabulce. Další vlastnosti vstupního modelu objektu jsou mapovány na vlastnosti slovníku v objektu TableEntity. Nakonec metoda createEntity objektu serviceClient slouží k vložení dat do tabulky.
insertEntity Upravte funkci v ukázkové aplikaci tak, aby obsahovala následující kód.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
Upsertování dat pomocí objektu TableEntity
Pokud se pokusíte vložit řádek do tabulky s kombinací klíče oddílu a klíče řádku, která už v této tabulce existuje, zobrazí se chyba. Z tohoto důvodu je při přidávání řádků do tabulky často vhodnější použít metodu upsertEntitycreateEntity místo metody . Pokud daná kombinace klíče oddílu a klíče řádku již v tabulce existuje, upsertEntity metoda existující řádek aktualizuje. V opačném případě se řádek přidá do tabulky.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Vložení nebo upsertování dat s vlastnostmi proměnné
Jednou z výhod použití služby Azure Cosmos DB for Table je to, že pokud objekt načítaný do tabulky obsahuje nové vlastnosti, pak se tyto vlastnosti automaticky přidají do tabulky a hodnoty uložené ve službě Azure Cosmos DB. Není nutné spouštět příkazy DDL, jako je ALTER TABLE, abyste mohli přidávat sloupce jako v tradiční databázi.
Tento model poskytuje vaší aplikaci flexibilitu při práci se zdroji dat, které můžou přidávat nebo upravovat data, která je potřeba zachytit v průběhu času, nebo když různé vstupy poskytují aplikaci různá data. V ukázkové aplikaci můžeme simulovat meteorologická stanice, která odesílá nejen základní data o počasí, ale také některé další hodnoty. Když je objekt s těmito novými vlastnostmi poprvé uložen v tabulce, odpovídající vlastnosti (sloupce) se automaticky přidají do tabulky.
Chcete-li vložit nebo upsertovat takový objekt pomocí rozhraní API pro tabulku, namapujte vlastnosti rozbalitelného objektu na TableEntity objekt a použijte createEntity metody nebo upsertEntity u objektu serviceClient podle potřeby.
V ukázkové aplikaci upsertEntity může funkce také implementovat funkci vkládání nebo upsertování dat s vlastnostmi proměnné.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Aktualizace entity
Entity lze aktualizovat voláním updateEntity metody u objektu serviceClient .
V ukázkové aplikaci se tento objekt předá upsertEntity metodě v objektu serviceClient . Aktualizuje objekt entity a použije metodu upsertEntity uložení aktualizací do databáze.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 – Spuštění kódu
Spusťte ukázkovou aplikaci pro interakci se službou Azure Cosmos DB for Table. Při prvním spuštění aplikace nebudou k dispozici žádná data, protože tabulka je prázdná. Pomocí libovolného tlačítka v horní části aplikace přidejte data do tabulky.
Výběrem tlačítka Vložit pomocí entity tabulky se otevře dialogové okno, ve kterém můžete vložit nebo upsertovat nový řádek pomocí objektu TableEntity .
Když vyberete tlačítko Vložit pomocí rozbalitelných dat , zobrazí se dialogové okno, které vám umožní vložit objekt s vlastními vlastnostmi, které demonstruje, jak Služba Azure Cosmos DB pro tabulku v případě potřeby automaticky přidává vlastnosti (sloupce). Pomocí tlačítka Přidat vlastní pole přidejte jednu nebo více nových vlastností a předveďte tuto funkci.
Pomocí tlačítka Vložit ukázková data načtěte ukázková data do tabulky Azure Cosmos DB.
V horní nabídce vyberte položku Filtrovat výsledky a přejděte na stránku Filtrovat výsledky. Na této stránce vyplňte kritéria filtru, abyste si ukázali, jak lze sestavit klauzuli filtru a předat ji do služby Azure Cosmos DB for Table.
Vyčištění prostředků
Po dokončení práce s ukázkovou aplikací byste měli ze svého účtu Azure odebrat všechny prostředky Azure související s tímto článkem. Můžete to udělat odstraněním skupiny prostředků.
Skupinu prostředků je možné odstranit pomocí Azure Portal následujícím způsobem.
| Pokyny | Snímek obrazovky |
|---|---|
| Do skupiny prostředků přejdete tak, že do panelu hledání zadáte název skupiny prostředků. Pak na kartě Skupiny prostředků vyberte název skupiny prostředků. | 
|
| Na panelu nástrojů v horní části stránky skupiny prostředků vyberte Odstranit skupinu prostředků. | 
|
Napravo na obrazovce se zobrazí dialogové okno s žádostí o potvrzení odstranění skupiny prostředků.
|
|
Další kroky
V tomto rychlém startu jste se seznámili s postupem vytvoření databázového účtu Azure Cosmos DB, vytvoření tabulky pomocí Průzkumníka dat a spuštění aplikace. Teď můžete data dotazovat pomocí rozhraní API pro tabulku.