Rychlý start: Vytvoření aplikace API pro tabulky pomocí Node.js a Azure Cosmos DB
PLATÍ PRO: 
Stůl
V tomto rychlém startu vytvoříte účet Služby Azure Cosmos DB pro tabulky a použijete Průzkumník dat a Node.js aplikaci klonovanou z GitHubu k vytváření tabulek a entit. Azure Cosmos DB je databázová služba s více modely, která umožňuje rychle vytvářet a dotazovat dokumenty, tabulky, klíč-hodnota a grafové databáze s funkcemi 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ázková aplikace pro tento kurz může být naklonována nebo stažena z úložiště https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js. Součástí ukázkového úložiště je úvodní i dokončená aplikace.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
Ukázková aplikace používá jako příklad data o počasí k předvedení možností rozhraní API pro tabulku. 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 for Table bez schématu.
1. Vytvoření účtu služby Azure Cosmos DB
Nejprve musíte vytvořit účet rozhraní API pro tabulky azure Cosmos DB, který bude obsahovat tabulky použité ve vaší aplikaci. Můžete to provést pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu.
Přihlaste se k webu Azure Portal a následujícím postupem 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 s možností Vybrat rozhraní API zvolte možnost Azure Table. | 
|
Na stránce Vytvořit účet 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. Při načítání dat do tabulky se vlastnosti (sloupce) automaticky vytvoří podle potřeby.
Na webu Azure Portal proveďte následující kroky a vytvořte tabulku uvnitř účtu služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
| Na webu Azure Portal přejděte na stránku přehledu účtu služby Azure Cosmos DB. Na stránku přehledu účtu služby Azure Cosmos DB můžete přejít zadáním názvu (cosmos-msdocs-tables-sdk-demo-XYZ) účtu služby Azure Cosmos DB na horním panelu hledání a zobrazením pod nadpisem prostředků. 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 posune z pravé strany stránky. | 
|
V dialogovém okně Nová tabulka vyplňte formulář následujícím způsobem.
|
|
3. Získání služby Azure Cosmos DB připojovací řetězec
Pro přístup k tabulce ve službě Azure Cosmos DB bude vaše aplikace potřebovat tabulku připojovací řetězec pro účet služby CosmosDB Storage. Připojovací řetězec je možné načíst pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu.
| 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, která se má použít ve vaší aplikaci. | 
|
4. Instalace sady Azure Data Tables SDK pro JS
Pokud chcete získat přístup ke službě Azure Cosmos DB for Table z aplikace nodejs, nainstalujte balíček sady Azure Data Tables SDK .
npm install @azure/data-tables
5. Konfigurace klienta tabulky v souboru env.js
Zkopírujte svůj účet služby Azure Cosmos DB nebo storage připojovací řetězec z webu Azure Portal a pomocí zkopírovaného připojovací řetězec vytvořte objekt TableServiceClient. Přepněte do složky 1-strater-app nebo 2-completed-app. Pak přidejte hodnotu odpovídajících proměnných prostředí v configure/env.js souboru.
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ů ke spouště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ří jeden serviceClient objekt na tabulku, která se použije 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í tabulek Azure Cosmos DB
Všechny operace tabulek Azure Cosmos DB pro ukázkovou aplikaci se implementují v objektu serviceClient umístěném v tableClient.jsadresář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, protože metodě nejsou předány žádné parametry, budou vybrány všechny řádky z tabulky.
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šechna čtení počasí pro Chicago 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 můžete zobrazit na webu OData v části Filtrovat možnost systémového dotazu.
Pokud 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ří sloučený filtrovací řetězec spojením všech hodnot společně s klauzulí "and". 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 v kódu můžete použít k vytvoření vhodných řetězců filtru podle potřeby 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žití objektu TableEntity . 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 vlastnosti, které společně tvoří jedinečný klíč pro řádek v tabulce. Další vlastnosti vstupního objektu modelu se pak mapují na vlastnosti slovníku v objektu TableEntity. Nakonec se createEntity metoda objektu serviceClient používá 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);
};
Upsert data pomocí objektu TableEntity
Pokud se pokusíte vložit řádek do tabulky s kombinací klíče oddílu nebo řádku, která už v této tabulce existuje, zobrazí se chyba. Z tohoto důvodu je často vhodnější použít upsertEntity místo createEntity metody při přidávání řádků do tabulky. Pokud daná kombinace klíče oddílu nebo řádku již v tabulce existuje, upsertEntity metoda aktualizuje existující řádek. 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 pro tabulku je, že pokud objekt načtený do tabulky obsahuje jakékoli nové vlastnosti, tyto vlastnosti se 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, aby bylo možné přidávat sloupce jako v tradiční databázi.
Tento model dává vaší aplikaci flexibilitu při práci se zdroji dat, které můžou přidávat nebo upravovat data, která je potřeba zachytávat v průběhu času nebo když různé vstupy poskytují různým datům vaší aplikaci. 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 přenést takový objekt pomocí rozhraní API pro tabulku, namapujte vlastnosti rozbalitelného objektu TableEntity na objekt a podle potřeby použijte createEntity nebo upsertEntity metody objektu serviceClient .
V ukázkové aplikaci upsertEntity může funkce také implementovat funkci vložení nebo upsert dat s proměnnými vlastnostmi.
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 objektu serviceClient .
V ukázkové aplikaci se tento objekt předá upsertEntity metodě v objektu serviceClient . Aktualizuje objekt entity a pomocí upsertEntity metody uloží aktualizace 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 vložit nový řádek pomocí objektu TableEntity .
Když vyberete tlačítko Vložit pomocí rozbalitelného data , zobrazí se dialogové okno, které umožňuje vložit objekt s vlastními vlastnostmi a ukazuje, jak Azure Cosmos DB pro tabulku v případě potřeby automaticky přidá do tabulky 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 do tabulky Azure Cosmos DB ukázková data.
V horní nabídce vyberte položku Filtrovat výsledky, která se má přesunout na stránku Filtrovat výsledky. Na této stránce vyplňte kritéria filtru, abyste ukázali, jak lze vytvořit a předat klauzuli filtru do služby Azure Cosmos DB for Table.
Vyčištění prostředků
Až ukázkovou aplikaci dokončíte, měli byste ze svého účtu Azure odebrat všechny prostředky Azure související s tímto článkem. Můžete to provést odstraněním skupiny prostředků.
Skupinu prostředků můžete odstranit pomocí webu Azure Portal následujícím způsobem.
| Pokyny | Snímek obrazovky |
|---|---|
| Pokud chcete přejít do skupiny prostředků, zadejte na panelu hledání název skupiny prostředků. Potom 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ů. | 
|
V pravé části obrazovky 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ď se můžete dotazovat na data pomocí rozhraní API pro tabulku.
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro