Jak používat Azure Table Storage nebo Azure Cosmos DB pro tabulku z Node.js
PLATÍ PRO: Stůl
Tip
Obsah v tomto článku se týká služby Azure Table Storage a Azure Cosmos DB for Table. Rozhraní API pro tabulku je prémiová nabídka pro úložiště tabulek, která nabízí tabulky optimalizované pro propustnost, globální distribuci a automatické sekundární indexy.
V tomto článku se dozvíte, jak vytvářet tabulky, ukládat data a provádět operace CRUD na uvedených datech. Ukázky jsou napsané v Node.js.
Vytvoření účtu služby Azure
S tabulkami můžete pracovat pomocí služby Azure Table Storage nebo Azure Cosmos DB. Další informace o rozdílech mezi nabídkami tabulek v těchto dvou službách najdete v přehledu rozhraní API pro tabulky. U služby, kterou budete používat, si budete muset vytvořit účet. Následující části ukazují, jak vytvořit úložiště Azure Table Storage i účet služby Azure Cosmos DB, ale můžete použít jenom jednu z nich.
Vytvoření účtu úložiště Azure
Nejjednodušší způsob, jak vytvořit účet úložiště Azure, je použití webu Azure Portal. Další informace naleznete v tématu Vytvoření účtu úložiště
Účet úložiště Azure můžete vytvořit také pomocí Azure PowerShellu nebo Azure CLI.
Pokud v tuto chvíli nechcete vytvořit účet úložiště, můžete také pomocí emulátoru úložiště Azure spustit a otestovat kód v místním prostředí. Další informace najdete v tématu Použití emulátoru úložiště Azure pro vývoj a testování.
Vytvoření účtu služby Azure Cosmos DB for Table
Pokyny k vytvoření účtu tabulky služby Azure Cosmos DB najdete v tématu Vytvoření databázového účtu.
Konfigurace aplikace pro přístup ke službě Table Storage
Pokud chcete používat Službu Azure Storage nebo Azure Cosmos DB, potřebujete sadu Azure Tables SDK pro Node.js, která obsahuje sadu praktických knihoven, které komunikují se službami REST služby Storage.
Instalace balíčku pomocí Node Package Manageru (NPM)
- Použijte rozhraní příkazového řádku, jako je PowerShell (Windows), Terminál (Mac) nebo Bash (Unix), a přejděte do složky, ve které jste vytvořili svou aplikaci.
- Do příkazového okna zadejte následující:
npm install @azure/data-tables
- Můžete ručně spustit příkaz ls a ověřit, že se vytvořila složka node_modules. Uvnitř této složky najdete balíček @azure/tabulky dat , který obsahuje knihovny, které potřebujete pro přístup k tabulkám.
Import balíčku
Na začátek souboru server.js ve vaší aplikaci přidejte následující kód:
const { TableServiceClient, TableClient, AzureNamedKeyCredential, odata } = require("@azure/data-tables");
Připojení ke službě Azure Table Storage
Můžete se buď připojit k účtu úložiště Azure, nebo k účtu služby Azure Cosmos DB for Table. Získejte sdílený klíč nebo připojovací řetězec na základě typu účtu, který používáte.
Vytvoření klienta služby Table Service ze sdíleného klíče
Modul Azure čte proměnné prostředí AZURE_ACCOUNT a AZURE_ACCESS_KEY a AZURE_TABLES_ENDPOINT, kde najdete informace potřebné pro připojení k účtu služby Azure Storage nebo ke službě Azure Cosmos DB. Pokud tyto proměnné prostředí nejsou nastaveny, je nutné při volání TableServiceClient
zadat informace o účtu . Například následující kód vytvoří TableServiceClient
objekt:
const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
"<account-name>",
"<account-key>"
);
const tableService = new TableServiceClient(
endpoint,
credential
);
Vytvoření klienta služby Table Service z připojovací řetězec
Pokud chcete přidat připojení účtu služby Azure Cosmos DB nebo úložiště, vytvořte TableServiceClient
objekt a zadejte název účtu, primární klíč a koncový bod. Tyto hodnoty můžete zkopírovat z připojovacího řetězce nastavení>na webu Azure Portal pro účet služby Azure Cosmos DB nebo účet úložiště. Příklad:
const tableService = TableServiceClient.fromConnectionString("<connection-string>");
Vytvoření tabulky
Volání pro createTable
vytvoření nové tabulky se zadaným názvem, pokud ještě neexistuje. Následující příklad vytvoří novou tabulku mytable, pokud ještě neexistuje:
await tableService.createTable('<table-name>');
Vytvoření klienta tabulky
Pokud chcete pracovat s tabulkou, měli byste vytvořit TableClient
objekt pomocí stejných přihlašovacích údajů, které jste použili TableServiceClient
k vytvoření . Vyžaduje TableClient
také název cílové tabulky.
const tableClient = new TableClient(
endpoint,
'<table-name>',
credential
);
Přidání entity do tabulky
Pokud chcete přidat entitu, nejprve vytvořte objekt definující vlastnosti entity. Všechny entity musí obsahovat partitionKey a rowKey, což jsou jedinečné identifikátory entity.
- partitionKey – určuje oddíl, ve kterém je entita uložená.
- rowKey – jedinečně identifikuje entitu v rámci oddílu.
PartitionKey i rowKey musí být řetězcové hodnoty.
Následuje příklad definice entity. DueDate je definován jako typ Date
. Zadání typu je volitelné. Pokud typ není zadaný, odvodí se.
const task = {
partitionKey: "hometasks",
rowKey: "1",
description: "take out the trash",
dueDate: new Date(2015, 6, 20)
};
Poznámka:
Pro každý záznam je také Timestamp
pole, které azure nastaví při vložení nebo aktualizaci entity.
Pokud chcete do tabulky přidat entitu, předejte objekt entity metodě createEntity
.
let result = await tableClient.createEntity(task);
// Entity create
Pokud je operace úspěšná, result
obsahuje značku ETag a informace o operaci.
Příklad odpovědi:
{
clientRequestId: '94d8e2aa-5e02-47e7-830c-258e050c4c63',
requestId: '08963b85-1002-001b-6d8c-12ae5d000000',
version: '2019-02-02',
date: 2022-01-26T08:12:32.000Z,
etag: `W/"datetime'2022-01-26T08%3A12%3A33.0180348Z'"`,
preferenceApplied: 'return-no-content',
'cache-control': 'no-cache',
'content-length': '0'
}
Aktualizace entity
Různé režimy a updateEntity
upsertEntity
metody
- Sloučení: Aktualizuje entitu aktualizací vlastností entity bez nahrazení existující entity.
- Nahradit: Aktualizuje existující entitu nahrazením celé entity.
Následující příklad ukazuje aktualizaci entity pomocí upsertEntity
:
// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");
Pokud entita, která se aktualizuje, neexistuje, operace aktualizace selže. proto pokud chcete uložit entitu bez ohledu na to, zda již existuje, použijte upsertEntity
.
result
pro úspěšné operace aktualizace obsahuje značku entity aktualizované entity.
Práce se skupinami entit
Někdy má smysl odeslat více operací společně v dávce, aby se zajistilo jejich atomické zpracování serverem. Chcete-li toho dosáhnout, vytvořte pole operací a předejte ji submitTransaction
metodě on TableClient
.
Následující příklad ukazuje odeslání dvou entit v dávce:
const task1 = {
partitionKey: "hometasks",
rowKey: "1",
description: "Take out the trash",
dueDate: new Date(2015, 6, 20)
};
const task2 = {
partitionKey: "hometasks",
rowKey: "2",
description: "Wash the dishes",
dueDate: new Date(2015, 6, 20)
};
const tableActions = [
["create", task1],
["create", task2]
];
let result = await tableClient.submitTransaction(tableActions);
// Batch completed
V případě úspěšných dávkových operací obsahuje result
informace o jednotlivých operacích v dávce.
Načtení entity podle klíče
Pokud chcete vrátit konkrétní entitu založenou na PartitionKey a RowKey, použijte metodu getEntity .
let result = await tableClient.getEntity("hometasks", "1")
.catch((error) => {
// handle any errors
});
// result contains the entity
Po dokončení operace bude result
obsahovat příslušnou entitu.
Dotaz na sadu entit
Následující příklad vytvoří dotaz, který vrátí prvních pět položek s PartitionKey "hometasks" a zobrazí seznam všech entit v tabulce.
const topN = 5;
const partitionKey = "hometasks";
const entities = tableClient.listEntities({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});
let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });
for await (const page of iterator) {
topEntities = page;
break;
}
// Top entities: 5
console.log(`Top entities: ${topEntities.length}`);
// List all the entities in the table
for await (const entity of entities) {
console.log(entity);
}
Dotaz na podmnožinu vlastností entity
Dotaz na tabulku dokáže z entity načíst pouze několik polí. Díky tomu se snižuje šířka pásma a může se zlepšit výkon dotazů, zejména u velkých entit. Použijte klauzuli select a předejte názvy polí, které se mají vrátit. Například následující dotaz vrátí pouze pole description a dueDate.
const topN = 5;
const partitionKey = "hometasks";
const entities = tableClient.listEntities({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}`,
select: ["description", "dueDate"] }
});
let topEntities = [];
const iterator = entities.byPage({ maxPageSize: topN });
for await (const page of iterator) {
topEntities = page;
break;
}
Odstranění entity
Entitu můžete odstranit pomocí jejího klíče oddílu a řádku. V tomto příkladu obsahuje objekt task1 hodnoty rowKey a partitionKey entity k odstranění. Objekt se pak předá do metody deleteEntity.
const tableClient = new TableClient(
tablesEndpoint,
tableName,
new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);
await tableClient.deleteEntity("hometasks", "1");
// Entity deleted
Poznámka:
Při odstraňování položek zvažte použití značek entit, abyste zajistili, že položku neupravil jiný proces. Informace o použití značek entit najdete v části Aktualizace entity.
Odstraní tabulku
Následující kód odstraní tabulku z účtu úložiště.
await tableClient.deleteTable(mytable);
// Table deleted
Použití tokenů pro pokračování
Pokud z tabulek dotazujete velké množství výsledků, hledejte tokeny pro pokračování. Pro váš dotaz může být k dispozici velké množství dat, kterých si nemusíte všimnout, pokud v rámci sestavování nezajistíte rozpoznání, jestli je přítomný token pro pokračování.
Pokud je takový token přítomný, v objektu results vraceném během dotazování entit se nastaví vlastnost continuationToken
. Tuto vlastnost pak můžete při provádění dotazu použít k pohybu mezi oddíly a entitami tabulky.
Při dotazování můžete zadat parametr continuationToken
mezi instanci objektu dotazu a funkci zpětného volání:
let iterator = tableClient.listEntities().byPage({ maxPageSize: 2 });
let interestingPage;
const page = await tableClient
.listEntities()
.byPage({ maxPageSize: 2, continuationToken: interestingPage })
.next();
if (!page.done) {
for (const entity of page.value) {
console.log(entity.rowKey);
}
}
Práce se sdílenými přístupovými podpisy
Sdílené přístupové podpisy (SAS) představují bezpečný způsob zajištění podrobného přístupu k tabulkám bez nutnosti zadávat název nebo klíče vašeho účtu služby Storage. SAS se často používá k zajištění omezeného přístupu k datům, jako je například povolení dotazování záznamů pro mobilní aplikaci.
Důvěryhodná aplikace, jako je cloudová služba, generuje SAS pomocí generateTableSastableClient a poskytuje ji nedůvěryhodné nebo částečně důvěryhodné aplikaci, jako je mobilní aplikace. SAS se generuje pomocí zásady, která popisuje počáteční a koncové datum platnosti SAS a také úroveň přístupu udělenou držiteli SAS.
Následující příklad vygeneruje novou zásadu sdíleného přístupu, která umožní držiteli SAS dotazovat ('r') tabulku.
const tablePermissions = {
query: true
// Allows querying entities
};
// Create the table SAS token
const tableSAS = generateTableSas('mytable', cred, {
expiresOn: new Date("2022-12-12"),
permissions: tablePermissions
});
Klientská aplikace pak použije SAS s AzureSASCredential k provádění operací s tabulkou. Následující příklad se připojí k tabulce a provede dotaz. Informace o formátu tableSAS najdete v článku Udělení omezeného přístupu k prostředkům Azure Storage pomocí sdílených přístupových podpisů (SAS ).
// Note in the following command, tablesUrl is in the format: `https://<your_storage_account_name>.table.core.windows.net` and the tableSAS is in the format: `sv=2018-03-28&si=saspolicy&tn=mytable&sig=9aCzs76n0E7y5BpEi2GvsSv433BZa22leDOZXX%2BXXIU%3D`;
const tableService = new TableServiceClient(tablesUrl, new AzureSASCredential(tableSAS));
const partitionKey = "hometasks";
const entities = tableService.listTables({
queryOptions: { filter: odata`PartitionKey eq ${partitionKey}` }
});
Vzhledem k tomu, že se SAS vygeneroval pouze s přístupem k dotazům, při pokusu o vložení, aktualizaci nebo odstranění entit se vrátí chyba.
Seznamy řízení přístupu
K nastavení zásad přístupu pro SAS můžete použít také seznam řízení přístupu (ACL). To je užitečné, pokud chcete umožnit přístup k tabulce několika klientům, ale pro každého klienta chcete zajistit jiné zásady přístupu.
Seznam ACL se implementuje pomocí pole zásad přístupu, z nichž každá zásada má přidružené ID. Následující příklad definuje dvě zásady, jednu pro uživatele user1 a druhou pro uživatele user2:
var sharedAccessPolicy = [{
id:"user1",
accessPolicy:{
permission: "r" ,
Start: startsOn,
Expiry: expiresOn,
}},
{
id:"user2",
accessPolicy:{
permissions: "a",
Start: startsOn,
Expiry: expiresOn,
}},
]
Následující příklad získá aktuální seznam ACL pro tabulku hometasks a pak přidá nové zásady pomocí setAccessPolicy. Tento přístup umožňuje:
tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);
Po nastavení seznamu ACL pak můžete pro zásadu vytvořit SAS založený na ID. Následující příklad vytvoří nový SAS pro uživatele user2:
tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});
Další kroky
Další informace najdete v následujících materiálech.
- Microsoft Azure Storage Explorer je bezplatná samostatná aplikace od Microsoftu, která umožňuje vizuálně pracovat s daty Azure Storage ve Windows, macOS a Linuxu.
- Azure Data Tables SDK pro úložiště Node.js na GitHubu
- Vytvoření webové aplikace Node.js v Azure
- Sestavení a nasazení aplikace Node.js v cloudové službě Azure (pomocí Windows PowerShellu)
Váš názor
https://aka.ms/ContentUserFeedback.
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:Odeslat a zobrazit názory pro