Dela via

Så här använder du Azure Table Storage eller Azure Cosmos DB for Table från Node.js

  • Artikel

GÄLLER FÖR: Bord

Dricks

Innehållet i den här artikeln gäller för Azure Table Storage och Azure Cosmos DB for Table. API för tabell är ett premiumerbjudande för tabelllagring som erbjuder dataflödesoptimerade tabeller, global distribution och automatiska sekundära index.

Den här artikeln visar hur du skapar tabeller, lagrar dina data och utför CRUD-åtgärder på dessa data. Exemplen skrivs i Node.js.

Skapa ett Azure-tjänstkonto

Du kan arbeta med tabeller med hjälp av Azure Table Storage eller Azure Cosmos DB. Mer information om skillnaderna mellan tabellerbjudanden i dessa två tjänster finns i API:et för tabellöversikt. Du måste skapa ett konto för den tjänst som du ska använda. Följande avsnitt visar hur du skapar både Azure Table Storage och Azure Cosmos DB-kontot, men du kan bara använda en av dem.

Skapa ett Azure Storage-konto

Det enklaste sättet att skapa ett Azure Storage-konto är med hjälp av Azure Portal. För mer information, se Skapa ett lagringskonto.

Du kan även skapa ett Azure-lagringskonto med hjälp av Azure PowerShell eller Azure CLI.

Om du föredrar att inte skapa ett lagringskonto just nu kan du även använda Azure Storage-emulatorn för att köra och testa koden i en lokal miljö. Mer information finns i Använda Azure Storage-emulatorn för utveckling och testning.

Skapa ett Azure Cosmos DB för tabellkonto

Anvisningar om hur du skapar ett Azure Cosmos DB för tabellkonto finns i Skapa ett databaskonto.

Konfigurera ditt program för åtkomst till Table Storage

Om du vill använda Azure Storage eller Azure Cosmos DB behöver du Azure Tables SDK för Node.js, som innehåller en uppsättning bekvämlighetsbibliotek som kommunicerar med Storage REST-tjänsterna.

Installera paketet med NPM (Node Package Manager)

  1. Använd ett kommandoradsgränssnitt som PowerShell (Windows), Terminal (Mac) eller Bash (Unix) och navigera till mappen där du skapade ditt program.
  2. Skriv följande i kommandofönstret:
   npm install @azure/data-tables
  1. Du kan kontrollera att mappen node_modules har skapats genom att köra kommandot ls manuellt. I mappen hittar du paketet @azure/datatabeller , som innehåller de bibliotek som du behöver för att komma åt tabeller.

Importera paketet

Lägg till följande kod överst i filen server.js i ditt program:

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

Ansluta till Azure Table Storage

Du kan antingen ansluta till Azure Storage-kontot eller Azure Cosmos DB för tabellkontot. Hämta autentiseringsuppgifterna baserat på vilken typ av konto du använder.

Skapa Table Service-klienten

Följande kod skapar ett TableServiceClient objekt med hjälp av en autentiseringsuppgift av typen TokenCredential. Klassen DefaultAzureCredential skapar en länkad tokenautentiseringsuppgift som fungerar för de flesta program som använder Azure SDK genom att prova flera typer av autentiseringsuppgifter. Mer information finns i DefaultAzureCredential.

const credential: TokenCredential = new DefaultAzureCredential();

const tableService = new TableServiceClient(
  new Uri("<table-endpoint>"),
  credential
);

Skapa en tabell

Anropet till createTable skapar en ny tabell med det angivna namnet om det inte redan finns. I följande exempel skapas en ny tabell med namnet ”mytable” om den inte redan finns:

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

Skapa tabellklienten

Om du vill interagera med en tabell bör du skapa ett TableClient objekt med samma autentiseringsuppgifter som du använde för att skapa TableServiceClient. Kräver TableClient även namnet på måltabellen.

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

Lägga till en entitet i en tabell

Du lägger till en entitet genom att först skapa ett objekt som definierar entitetens egenskaper. Alla entiteter måste innehålla en partitionKey och rowKey, som är unika identifierare för entiteten.

  • partitionKey – Avgör i vilken partition entiteten lagras.
  • rowKey – Identifierar entiteten unikt i partitionen.

Både partitionKey och rowKey måste vara strängvärden.

Följande är ett exempel på hur du definierar en entitet. DueDate definieras som en typ av Date. Typen är inte obligatorisk, och typer härleds om de inte anges.

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

Kommentar

Det finns också ett Timestamp fält för varje post, som anges av Azure när en entitet infogas eller uppdateras.

Om du vill lägga till en entitet i tabellen skickar du entitetsobjektet till createEntity -metoden.

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

Om åtgärden lyckas result innehåller ETag och information om åtgärden.

Exempelsvar:

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

Uppdatera en entitet

De olika lägena för updateEntity och upsertEntity metoderna

  • Sammanfoga: Uppdaterar en entitet genom att uppdatera entitetens egenskaper utan att ersätta den befintliga entiteten.
  • Ersätt: Uppdaterar en befintlig entitet genom att ersätta hela entiteten.

I följande exempel visas hur du uppdaterar en entitet med hjälp av upsertEntity:

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

Om entiteten som uppdateras inte finns misslyckas uppdateringsåtgärden. Om du vill lagra en entitet oavsett om den redan finns använder upsertEntitydu därför .

För lyckade uppdateringsåtgärder innehåller result den uppdaterade entitetens Etag.

Arbeta med grupper av entiteter

Ibland är det praktiskt att skicka flera åtgärder tillsammans i en batch för att säkerställa atomisk bearbetning av servern. Det gör du genom att skapa en matris med åtgärder och skicka den till -metoden på submitTransaction TableClient.

Exemplet nedan beskriver hur du skickar två entiteter i en batch:

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

För lyckade batchåtgärder innehåller result information om varje åtgärd i batchen.

Hämta en entitet baserat på nyckel

Om du vill returnera en specifik entitet baserat på PartitionKey och RowKey använder du metoden getEntity.

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

När den här åtgärden har slutförts innehåller result entiteten.

Fråga efter en uppsättning entiteter

I följande exempel skapas en fråga som returnerar de fem översta objekten med partitionsnyckeln "hometasks" och listar alla entiteter i tabellen.

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

Fråga en deluppsättning entitetsegenskaper

En fråga till en tabell kan bara hämta några fält från en entitet. Detta minskar bandbredden och kan förbättra frågeprestanda, särskilt för stora entiteter. Använd select-satsen och ange namnen på fälten som ska returneras. Följande fråga returnerar till exempel bara description- och dueDate-fälten.

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

Ta bort en entitet

Du kan ta bort en entitet med hjälp av dess partitions- och radnycklar. I det här exemplet innehåller objektet task1 värdena rowKey och partitionKey för den entitet som ska tas bort. Objektet skickas sedan till metoden deleteEntity.

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

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

Kommentar

Använd ETags när du tar bort objekt för att säkerställa att de inte har ändrats av en annan process. Information om hur du använder ETags finns i Uppdatera en entitet.

Ta bort en tabell

Följande kod tar bort en tabell från ett lagringskonto.

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

Använda fortsättningstoken

Leta efter en fortsättningstoken när du frågar tabeller efter stora mängder resultat. Stora mängder data kan finnas tillgängliga för din fråga, som du kanske missar om du inte uppmärksammar en fortsättningstoken.

results-objektet som returneras när du kör frågor mot entiteter anger en continuationToken-egenskap när den här typen av token finns. Du kan sedan använda denna token när du kör en fråga för att fortsätta att flytta mellan partitionen och tabellentiteterna.

När du frågar kan du lägga till en continuationToken-parameter mellan instansen av frågeobjektet och återanropsfunktionen:

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

Arbeta med signaturer för delad åtkomst

Signaturer för delad åtkomst (SAS) är ett säkert sätt att ge detaljerad åtkomst till tabeller utan att ange namnet på eller nycklarna för ditt lagringskontot. SAS används ofta för att ge begränsad åtkomst till data, till exempel om du vill tillåta att en mobilapp frågar efter poster.

Ett betrott program, till exempel en molnbaserad tjänst, genererar en SAS med hjälp av tableclientens generateTableSas och tillhandahåller den till ett icke-betrott eller halvbetrott program, till exempel en mobilapp. Signaturen för delad åtkomst genereras med hjälp av en princip, som definierar mellan vilket start- och slutdatum signaturen för delad åtkomst är giltig, samt vilken åtkomstnivå SAS-innehavaren beviljas.

I följande exempel genereras en ny princip för delad åtkomst som gör att SAS-innehavaren kan fråga ('r') tabellen.

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

Klientprogrammet använder sedan SAS med AzureSASCredential för att utföra åtgärder mot tabellen. Koden i följande exempel ansluter till tabellen och kör en fråga. Se artikeln Bevilja begränsad åtkomst till Azure Storage-resurser med hjälp av signaturer för delad åtkomst (SAS) för formatet för tableSAS.

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

Eftersom signaturen för delad åtkomst endast genererades med frågebehörighet, returneras ett fel om du försöker infoga, uppdatera eller ta bort entiteter.

Åtkomstkontrollistor

Du kan också använda en åtkomstkontrollista (ACL) för att definiera åtkomstprincipen för en signatur för delad åtkomst. Detta är användbart om du vill att flera klienter ska kunna komma åt tabellen, men du vill använda olika åtkomstprinciper för varje klient.

En åtkomstkontrollista implementeras med hjälp av en matris med åtkomstprinciper, med ett ID som associeras med varje princip. I följande exempel definieras två principer, en för ”user1” och en för ”user2”:

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

I följande exempel hämtas den aktuella ACL:en för tabellen hometasks och lägger sedan till de nya principerna med setAccessPolicy. Med den här metoden kan du göra följande:

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

När åtkomstkontrollistan har skapats kan du skapa en signatur för delad åtkomst baserat på ID:t för en princip. I följande exempel skapas en ny signatur för delad åtkomst för ”user2”:

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

Nästa steg

Mer information finns i resurserna nedan.