Az Azure Table Storage vagy az Azure Cosmos DB for Table használata Node.js

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: Táblázat

Tipp.

A cikk tartalma az Azure Table Storage-ra és az Azure Cosmos DB for Tablere vonatkozik. A Table API egy prémium szintű ajánlat a table storage számára, amely átviteli sebességre optimalizált táblákat, globális eloszlást és automatikus másodlagos indexeket kínál.

Ez a cikk bemutatja, hogyan hozhat létre táblákat, tárolhatja az adatokat, és hogyan hajthat végre CRUD-műveleteket az említett adatokon. A minták Node.js vannak megírva.

Azure-szolgáltatásfiók létrehozása

A táblákat az Azure Table Storage vagy az Azure Cosmos DB használatával használhatja. Ha többet szeretne megtudni a táblaajánlatok közötti különbségekről ebben a két szolgáltatásban, tekintse meg az API for Table áttekintését. Az Ön által kiválasztott szolgáltatás használatához hozzon létre egy fiókot. Az alábbi szakaszok bemutatják, hogyan hozható létre az Azure Table Storage és az Azure Cosmos DB-fiók is, de csak az egyiket használhatja.

Azure Storage-fiók létrehozása

Az Azure Storage-fiók létrehozásának legegyszerűbb módja az Azure Portal használata. További tudnivalókért lásd: Create a storage account (Tárfiók létrehozása).

Ezenkívül az Azure PowerShell vagy az Azure CLI használatával is létrehozhat egy Azure-tárfiókot.

Ha jelenleg nem szeretne tárfiókot létrehozni, az Azure Storage Emulator használatával helyi környezetben is futtathatja és tesztelheti a kódot. További információ: Az Azure Storage Emulator használata fejlesztéshez és teszteléshez.

Azure Cosmos DB for Table-fiók létrehozása

Az Azure Cosmos DB táblafiókhoz való létrehozásával kapcsolatos utasításokért lásd : Adatbázisfiók létrehozása.

Az alkalmazás konfigurálása a Table Storage eléréséhez

Az Azure Storage vagy az Azure Cosmos DB használatához szüksége van a Node.js-hez készült Azure Tables SDK-ra, amely olyan kényelmi kódtárakat tartalmaz, amelyek kommunikálnak a Storage REST-szolgáltatásokkal.

Csomag telepítése a Node Package Manager (NPM) használatával

  1. Használjon egy parancssori felületet, amilyen például a PowerShell (Windows), a Terminal (Mac) vagy a Bash (Unix), és keresse meg azt a mappát, amelyben létrehozta az alkalmazást.
  2. Írja be a következőt a parancsablakba:
   npm install @azure/data-tables
  1. A node_modules mappa létrehozásának ellenőrzéséhez manuálisan is futtathatja az ls parancsot. A mappában megtalálja a @azure/adattáblák csomagot, amely tartalmazza a táblák eléréséhez szükséges kódtárakat.

A csomag importálása

Adja hozzá a következő kódot a server.js fájl elejéhez az alkalmazásban:

const { TableServiceClient, TableClient, AzureNamedKeyCredential, odata } = require("@azure/data-tables");

Csatlakozás az Azure Table Service-hez

Csatlakozhat az Azure Storage-fiókhoz vagy az Azure Cosmos DB táblafiókhoz. Kérje le a megosztott kulcsot vagy kapcsolati sztring a használt fiók típusától függően.

A Table service-ügyfél létrehozása megosztott kulcsból

Az Azure-modul beolvassa a környezeti változókat AZURE_ACCOUNT, AZURE_ACCESS_KEY és AZURE_TABLES_ENDPOINT az Azure Storage-fiókhoz vagy az Azure Cosmos DB-hez való csatlakozáshoz szükséges információkért. Ha ezek a környezeti változók nincsenek beállítva, híváskor TableServiceClientmeg kell adnia a fiók adatait. A következő kód például létrehoz egy objektumot TableServiceClient :

const endpoint = "<table-endpoint-uri>";
const credential = new AzureNamedKeyCredential(
  "<account-name>",
  "<account-key>"
);

const tableService = new TableServiceClient(
  endpoint,
  credential
);

A Table service-ügyfél létrehozása egy kapcsolati sztring

Azure Cosmos DB- vagy Storage-fiókkapcsolat hozzáadásához hozzon létre egy TableServiceClient objektumot, és adja meg a fiók nevét, elsődleges kulcsát és végpontját. Ezeket az értékeket a Gépház> Csatlakozás ion-sztringből másolhatja az Azure Portalon az Azure Cosmos DB-fiókhoz vagy a Storage-fiókhoz. Példa:

const tableService = TableServiceClient.fromConnectionString("<connection-string>");

Tábla létrehozása

A hívás egy új táblát createTable hoz létre a megadott névvel, ha még nem létezik. Az alábbi példában létrehozunk egy új, „mytable” nevű táblát, ha még nem létezik ilyen:

await tableService.createTable('<table-name>');

A Táblaügyfél létrehozása

A táblák használatához létre kell hoznia egy TableClient objektumot ugyanazokkal a hitelesítő adatokkal, amelyeket a TableServiceClienttábla létrehozásához használt. Ehhez TableClient a céltábla nevét is meg kell követelni.

const tableClient = new TableClient(
  endpoint,
  '<table-name>',
  credential
);

Entitás hozzáadása a táblához

Entitás hozzáadásához először hozzon létre egy objektumot, amely meghatározza az entitástulajdonságokat. Minden entitásnak tartalmaznia kell egy partitionKey és rowKey azonosítót, amelyek az entitás egyedi azonosítói.

  • partitionKey – Meghatározza azt a partíciót, amelyben az entitást tárolja.
  • rowKey – Egyedileg azonosítja a partíción belüli entitást.

Mind a partitionKey, mind a rowKey értéknek sztringértéknek kell lennie.

Az alábbi egy entitás meghatározására szolgál példaként. A dueDate típusként Datevan definiálva. A típus meghatározása nem kötelező, és a rendszer kikövetkezteti a nem meghatározott típusokat.

const task = {
  partitionKey: "hometasks",
  rowKey: "1",
  description: "take out the trash",
  dueDate: new Date(2015, 6, 20)
};

Feljegyzés

Minden rekordhoz tartozik egy Timestamp mező is, amelyet az Azure állít be egy entitás beszúrásakor vagy frissítésekor.

Ha egy entitást szeretne hozzáadni a táblához, adja át az entitásobjektumot a createEntity metódusnak.

let result = await tableClient.createEntity(task);
    // Entity create

Ha a művelet sikeres, result tartalmazza az ETaget és a művelettel kapcsolatos információkat.

Példaválasz:

{ 
  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'
}

Entitás frissítése

A különböző módok updateEntity és upsertEntity módszerek

  • Egyesítés: egy entitás Frissítések az entitás tulajdonságainak frissítésével a meglévő entitás cseréje nélkül.
  • Csere: meglévő entitás Frissítések a teljes entitás lecserélésével.

Az alábbi példa egy entitás frissítését mutatja be a következő használatával upsertEntity:

// Entity doesn't exist in table, so calling upsertEntity will simply insert the entity.
let result = await tableClient.upsertEntity(task, "Replace");

Ha a frissíteni kívánt entitás nem létezik, a frissítési művelet meghiúsul; ezért, ha egy entitást szeretne tárolni, függetlenül attól, hogy már létezik-e, használja a következőt upsertEntity: .

Sikeres frissítés esetén a frissített entitás resultETagje a részét képezi.

Entitáscsoportok használata

Annak biztosításához, hogy a kiszolgáló elvégezze a kérés elemi feldolgozását, néha érdemes több műveletet egyszerre, egy kötegben elküldeni. Ehhez hozzon létre egy műveleti tömböt, és adja át a submitTransaction metódusnak.TableClient

Az alábbi példa két entitás egy kötegben való elküldését mutatja be:

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

Sikeres kötegműveletek esetén a result a kötegben lévő minden egyes műveletről tartalmaz információkat.

Entitás lekérése kulcs alapján

Ha egy adott entitást szeretne visszaadni a PartitionKey és a RowKey alapján, használja a getEntity metódust.

let result = await tableClient.getEntity("hometasks", "1")
  .catch((error) => {
    // handle any errors
  });
  // result contains the entity

A művelet végrehajtása után a result tartalmazza az entitást.

Több entitás lekérdezése

Az alábbi példa létrehoz egy lekérdezést, amely az első öt elemet adja vissza a "hometasks" PartitionKey elemével, és felsorolja a tábla összes entitását.

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);
}

Az entitástulajdonságok egy részének lekérdezése

Egy táblalekérdezéssel egy entitásnak csak bizonyos mezőit is lekérdezheti. Ez csökkenti a sávszélesség felhasználását, és javíthatja a lekérdezési teljesítményt, főleg a nagy entitások esetében. Használja a select záradékot, és adja át a visszaadni kívánt mezők nevét. A következő lekérdezés például csak a description és dueDate mezőket adja vissza.

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;
}

Entitás törlése

Entitásokat a partíció- és a sorkulcsokkal törölhet. Ebben a példában az 1 . feladatobjektum tartalmazza a törölni kívánt entitás rowKey és partitionKey értékeit. Ezután a rendszer a deleteEntity metódusba továbbítja az objektumot.

const tableClient = new TableClient(
  tablesEndpoint,
  tableName,
  new AzureNamedKeyCredential("<accountName>", "<accountKey>")
);

await tableClient.deleteEntity("hometasks", "1");
    // Entity deleted

Feljegyzés

Elemek törlésekor érdemes használni az ETageket, mert így meg tud győződni róla, hogy az elemet nem módosították korábbi folyamatok. Az ETagek használatával kapcsolatos további információkért lásd az entitások frissítésével foglalkozó szakaszt.

Tábla törlése

Az alábbi kóddal törölhető egy tábla egy tárfiókból.

await tableClient.deleteTable(mytable);
        // Table deleted

Folytatási tokenek használata

Ha nagy mennyiségű találatot eredményez egy tábla lekérdezése, fontolja meg a folytatási tokenek használatát. Előfordulhat, hogy nagy mennyiségű lekérdezhető adat áll rendelkezésre, amelyet nem feltétlenül fog észrevenni, ha az összeállítás nem teszi lehetővé a folytatási token jelenlétének a felismerését.

Ha jelen van ilyen token, az entitások lekérdezésekor visszaadott results objektum beállít egy continuationToken tulajdonságot. Ezt lekérdezések végrehajtásakor használhatja, hogy továbbléphessen a partíciók és táblaentitások között.

Lekérdezés végrehajtásakor megadhat egy continuationToken paramétert a lekérdezésiobjektum-példány és a visszahívási függvény között:

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);
   }
 }

Közös hozzáférésű jogosultságkódok használata

A közös hozzáférésű jogosultságkódokkal (Shared access signatures, SAS) biztonságos és részletes hozzáférést biztosíthat a táblákhoz anélkül, hogy megadná Storage-fiókjának nevét vagy kulcsait. Az SAS-t gyakran használják az adatokhoz való korlátozott hozzáférés biztosítására, például arra, hogy a mobilalkalmazások hozzáférhessenek a lekérdezésrekordokhoz.

Egy megbízható alkalmazás, például egy felhőalapú szolgáltatás létrehoz egy SAS-t a TableClient generateTableSas használatával, és egy nem megbízható vagy félig megbízható alkalmazásnak, például mobilalkalmazásnak biztosítja azt. A rendszer egy szabályzat segítségével hozza létre az SAS-eket, amely meghatározza az SAS érvényességének kezdő és befejező dátumát, valamint az SAS tulajdonosának biztosított hozzáférési szintet.

Az alábbi példa egy új megosztott hozzáférési szabályzatot hoz létre, amely lehetővé teszi, hogy az SAS-tulajdonos lekérdezhesse a táblát ('r').

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
});

Az ügyfélalkalmazás ezután az SAS és az AzureSASCredential használatával hajt végre műveleteket a táblán. A következő példa csatlakozik a táblához, és végrehajt egy lekérdezést. A tableSAS formátumáról lásd: Korlátozott hozzáférés biztosítása az Azure Storage-erőforrásokhoz közös hozzáférésű jogosultságkódok (SAS) használatával.

// 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}` }
});

Mivel az SAS csak lekérdezési hozzáféréssel lett létrehozva, a rendszert hibát jelez, amennyiben megkísérel entitásokat beszúrni, frissíteni vagy törölni.

Hozzáférés-vezérlési listák

Hozzáférés-vezérlési listát (Access Control List, ACL) is használhat az SAS hozzáférési szabályzatának beállítására. Ez akkor hasznos, ha több ügyfélnek is lehetővé kívánja tenni a tábla elérését úgy, hogy az egyes ügyfelekre más-más hozzáférési szabályzat vonatkozik.

A rendszer ACL-eket implementál egy hozzáférésiszabályzat-tömbbel, és minden szabályzathoz azonosító van társítva. Az alábbi példa két szabályzatot határoz meg, egyet „user1”, egy másikat pedig „user2” részére:

var sharedAccessPolicy = [{
  id:"user1",
  accessPolicy:{
    permission: "r" ,
    Start: startsOn,
    Expiry: expiresOn,
  }},
  {
  id:"user2",
  accessPolicy:{
    permissions: "a",
    Start: startsOn,
    Expiry: expiresOn,
  }},
]

Az alábbi példa lekéri a hometasks tábla aktuális ACL-ét, majd hozzáadja az új szabályzatokat a setAccessPolicy használatával. Ez a megközelítés lehetővé teszi, hogy:

tableClient.getAccessPolicy();
tableClient.setAccessPolicy(sharedAccessPolicy);

Miután beállította az ACL-t, létrehozzon egy SAS-t egy szabályzat azonosítója alapján. Az alábbi példa egy új SAS-t hoz létre „user2” számára:

tableSAS = generateTableSas("hometasks",cred,{identifier:'user2'});

Következő lépések

További információkért lásd a következő forrásanyagokat.