Udostępnij za pośrednictwem

Biblioteka klienta tabel platformy Azure dla języka JavaScript — wersja 13.3.0

  • Artykuł

Azure Tables to oparta na chmurze usługa, która przechowuje ustrukturyzowane dane NoSQL, zapewniając magazyn kluczy/atrybutów z projektem bez schematu. Magazyn tabel zapewnia deweloperom elastyczność i skalowalność we wszystkich najlepszych częściach chmury platformy Azure.

Użyj biblioteki klienta, aby:

  • Tworzenie/usuwanie tabel
  • Tworzenie/tworzenie/odczyt/aktualizowanie/usuwanie jednostek

Usługa Azure Cosmos DB udostępnia interfejs API tabel dla aplikacji napisanych dla usługi Azure Table Storage i wymagających możliwości premium, takich jak:

  • Gotowa do użycia dystrybucja globalna.
  • Dedykowana przepływność na całym świecie.
  • Jednocyfrowe opóźnienia milisekund na 99. percentylu.
  • Gwarantowana wysoka dostępność.
  • Automatyczne indeksowanie pomocnicze.
  • Biblioteka kliencka tabel platformy Azure może bezproblemowo kierować do usługi Azure Table Storage lub Punktów końcowych usługi tabel usługi Azure Cosmos DB bez żadnych zmian w kodzie.

Kluczowe linki:

  • kod źródłowy
  • pakietu (NPM)
  • Dokumentacja referencyjna interfejs u API
  • dokumentacja produktu
  • przykładów

Wprowadzenie

Warunki wstępne

Obecnie obsługiwane środowiska:

  • Wersje LTS Node.js
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox

Aby użyć tego pakietu, musisz mieć subskrypcji platformy Azure oraz konto magazynu lub bazy danych Azure CosmosDB.

Instalowanie pakietu @azure/data-tables

Preferowanym sposobem zainstalowania biblioteki klienta tabel platformy Azure dla języka JavaScript jest użycie menedżera pakietów npm. Wpisz następujące polecenie w oknie terminalu:

npm install @azure/data-tables

Uwierzytelnianie TableServiceClient

Usługa Azure Tables obsługuje kilka sposobów uwierzytelniania. Aby móc korzystać z usługi Azure Tables, musisz na przykład utworzyć wystąpienie klienta tabel — TableServiceClient lub TableClient. Zobacz przykłady tworzenia TableServiceClient, aby dowiedzieć się więcej na temat uwierzytelniania.

Uwaga: usługa Azure Active Directory (AAD) jest obsługiwana tylko dla kont usługi Azure Storage.

Następujące funkcje, interfejsy, klasy lub funkcje są dostępne tylko w Node.js

  • Autoryzacja klucza współużytkowanego na podstawie nazwy konta i klucza konta
    • AzureNamedKeyCredential
    • Parametry połączenia konta.

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

MECHANIZM CORS

Musisz skonfigurować współużytkowanie zasobów między źródłami (CORS) regułami dla konta magazynu, jeśli chcesz utworzyć aplikacje dla przeglądarek. Przejdź do witryny Azure Portal i Eksploratora usługi Azure Storage, znajdź konto magazynu, utwórz nowe reguły CORS dla usług blob/queue/file/table.

Można na przykład utworzyć następujące ustawienia mechanizmu CORS na potrzeby debugowania. Należy jednak dokładnie dostosować ustawienia zgodnie z wymaganiami w środowisku produkcyjnym.

  • Dozwolone źródła: *
  • Dozwolone czasowniki: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • Dozwolone nagłówki: *
  • Uwidocznione nagłówki: *
  • Maksymalny wiek (w sekundach): 86400

Kluczowe pojęcia

  • TableServiceClient — klient, który udostępnia funkcje umożliwiające interakcję na poziomie usługi tabel, takich jak tworzenie, wyświetlanie listy i usuwanie tabel

  • TableClient — klient, który udostępnia funkcje umożliwiające interakcję na poziomie jednostki, takim jak tworzenie, wyświetlanie listy i usuwanie jednostek w tabeli.

  • Table — tabele przechowują dane jako kolekcje jednostek.

  • Entity — Jednostki są podobne do wierszy. Jednostka ma klucz podstawowy i zestaw właściwości. Właściwość jest nazwą, typed-value pair, podobną do kolumny.

Typowe zastosowania usługi Table Service obejmują:

  • Przechowywanie baz danych strukturalnych obsługujących aplikacje w skali internetowej
  • Przechowywanie zestawów danych, które nie wymagają złożonych sprzężeń, kluczy obcych lub procedur składowanych i można je zdenormalizować w celu zapewnienia szybkiego dostępu
  • Szybkie wykonywanie zapytań dotyczących danych przy użyciu indeksu klastrowanego
  • Uzyskiwanie dostępu do danych przy użyciu wyrażeń filtru protokołu OData

Przykłady

Importowanie pakietu

Aby użyć klientów, zaimportuj pakiet w pliku:

const AzureTables = require("@azure/data-tables");

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

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

Tworzenie klienta usługi Table Service

TableServiceClient wymaga adresu URL usługi table i poświadczenia dostępu. Opcjonalnie akceptuje również niektóre ustawienia w parametrze options.

TableServiceClient za pomocą polecenia AzureNamedKeyCredential

Możesz utworzyć wystąpienie TableServiceClient przy użyciu AzureNamedKeyCredential, przekazując argumenty account-name i account-key. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient z tokenemCredential (AAD)

Usługa Azure Tables zapewnia integrację z usługą Azure Active Directory (Azure AD) na potrzeby uwierzytelniania opartego na tożsamościach żądań do usługi Table Service podczas określania wartości docelowej punktu końcowego usługi Storage. Za pomocą usługi Azure AD możesz użyć kontroli dostępu opartej na rolach (RBAC), aby udzielić dostępu do zasobów tabel platformy Azure użytkownikom, grupom lub aplikacjom.

Aby uzyskać dostęp do zasobu tabeli przy użyciu TokenCredential, uwierzytelniona tożsamość powinna mieć rolę "Współautor danych tabeli magazynu" lub "Czytelnik danych tabeli magazynu".

Pakiet @azure/identity umożliwia bezproblemowe autoryzowanie żądań zarówno w środowiskach deweloperskich, jak i produkcyjnych. Aby dowiedzieć się więcej na temat integracji usługi Azure AD w usłudze Azure Storage, zobacz Azure.Identity README

const { TableServiceClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";

const clientWithAAD = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

TableServiceClient z tokenem SAS

Ponadto można utworzyć wystąpienie TableServiceClient przy użyciu sygnatur dostępu współdzielonego (SAS). Token SAS można uzyskać z witryny Azure Portal.

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClientWithSAS = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  new AzureSASCredential(sas)
);

Wyświetlanie listy tabel na koncie

Tabele w ramach konta można wyświetlić za pomocą wystąpienia TableServiceClient wywołującego funkcję listTables. Ta funkcja zwraca PageableAsyncIterator, z których można korzystać przy użyciu for-await-of

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tablesIter = serviceClient.listTables();
  let i = 1;
  for await (const table of tablesIter) {
    console.log(`Table${i}: ${table.name}`);
    i++;
    // Output:
    // Table1: testTable1
    // Table1: testTable2
    // Table1: testTable3
    // Table1: testTable4
    // Table1: testTable5
  }
}

main();

Tworzenie nowej tabeli

Tabelę można utworzyć za pomocą wystąpienia TableServiceClient wywołującego funkcję createTable. Ta funkcja przyjmuje nazwę tabeli do utworzenia jako parametru. Należy pamiętać, że createTable nie zgłosi błędu, gdy tabela już istnieje.

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable`;
  // If the table 'newTable' already exists, createTable doesn't throw
  await serviceClient.createTable(tableName);
}

main();

Oto przykład, który pokazuje, jak przetestować, czy tabela już istnieje podczas próby jej utworzenia:

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

const account = "<account>";
const accountKey = "<accountkey>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const serviceClient = new TableServiceClient(
  `https://${account}.table.core.windows.net`,
  credential
);

async function main() {
  const tableName = `newtable${new Date().getTime()}`;
  await serviceClient.createTable(tableName, {
    onResponse: (response) => {
      if (response.status === 409) {
        console.log(`Table ${tableName} already exists`);
      }
    }
  });
}

main();

Tworzenie klienta tabeli

TableClient jest tworzony w podobny sposób jak TableServiceClient z różnicą, która TableClient przyjmuje nazwę tabeli jako parametr

TableClient z AzureNamedKeyCredential

Możesz utworzyć wystąpienie TableClient przy użyciu AzureNamedKeyCredential, przekazując argumenty account-name i account-key. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

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

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

// Use AzureNamedKeyCredential with storage account and account key
// AzureNamedKeyCredential is only available in Node.js runtime, not in browsers
const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

TableClient za pomocą TokenCredential (Azure Active Directory)

Usługa Azure Tables zapewnia integrację z usługą Azure Active Directory (Azure AD) na potrzeby uwierzytelniania opartego na tożsamościach żądań do usługi Table Service podczas określania wartości docelowej punktu końcowego usługi Storage. Za pomocą usługi Azure AD możesz użyć kontroli dostępu opartej na rolach (RBAC), aby udzielić dostępu do zasobów tabel platformy Azure użytkownikom, grupom lub aplikacjom.

Aby uzyskać dostęp do zasobu tabeli przy użyciu TokenCredential, uwierzytelniona tożsamość powinna mieć rolę "Współautor danych tabeli magazynu" lub "Czytelnik danych tabeli magazynu".

Pakiet @azure/identity umożliwia bezproblemowe autoryzowanie żądań zarówno w środowiskach deweloperskich, jak i produkcyjnych. Aby dowiedzieć się więcej na temat integracji usługi Azure AD w usłudze Azure Storage, zobacz Azure.Identity README

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

TableClient z tokenem SAS

Możesz utworzyć wystąpienie TableClient przy użyciu sygnatur dostępu współdzielonego (SAS). Token SAS można uzyskać z witryny Azure Portal.

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

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const tableName = "<tableName>";

const clientWithSAS = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  new AzureSASCredential(sas)
);

TableClient z tokenemCredential (AAD)

Usługa Azure Tables zapewnia integrację z usługą Azure Active Directory (Azure AD) na potrzeby uwierzytelniania opartego na tożsamościach żądań do usługi Table Service podczas określania wartości docelowej punktu końcowego usługi Storage. Za pomocą usługi Azure AD możesz użyć kontroli dostępu opartej na rolach (RBAC), aby udzielić dostępu do zasobów tabel platformy Azure użytkownikom, grupom lub aplikacjom.

Aby uzyskać dostęp do zasobu tabeli przy użyciu TokenCredential, uwierzytelniona tożsamość powinna mieć rolę "Współautor danych tabeli magazynu" lub "Czytelnik danych tabeli magazynu".

Pakiet @azure/identity umożliwia bezproblemowe autoryzowanie żądań zarówno w środowiskach deweloperskich, jak i produkcyjnych. Aby dowiedzieć się więcej na temat integracji usługi Azure AD w usłudze Azure Storage, zobacz Azure.Identity README

const { TableClient } = require("@azure/data-tables");
const { DefaultAzureCredential } = require("@azure/identity");

// DefaultAzureCredential expects the following three environment variables:
// - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
// - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
// - AZURE_CLIENT_SECRET: The client secret for the registered application
const credential = new DefaultAzureCredential();
const account = "<account name>";
const tableName = "<tableName>";

const clientWithAAD = new TableClient(
  `https://${account}.table.core.windows.net`,
  tableName,
  credential
);

Wyświetlanie listy jednostek w tabeli

Jednostki w tabeli można wyświetlić za pomocą wystąpienia TableClient wywołującego funkcję listEntities. Ta funkcja zwraca PageableAsyncIterator, z których można korzystać przy użyciu for-await-of

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

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const entitiesIter = client.listEntities();
  let i = 1;
  for await (const entity of entitiesIter) {
    console.log(`Entity${i}: PartitionKey: ${entity.partitionKey} RowKey: ${entity.rowKey}`);
    i++;
    // Output:
    // Entity1: PartitionKey: P1 RowKey: R1
    // Entity2: PartitionKey: P2 RowKey: R2
    // Entity3: PartitionKey: P3 RowKey: R3
    // Entity4: PartitionKey: P4 RowKey: R4
  }
}

main();

Tworzenie nowej jednostki i dodawanie jej do tabeli

Nową jednostkę w tabeli można utworzyć za pomocą wystąpienia TableClient wywołującego funkcję createEntity. Ta funkcja pobiera jednostkę do wstawienia jako parametru. Jednostka musi zawierać partitionKey i rowKey.

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

const account = "<account>";
const accountKey = "<accountkey>";
const tableName = "<tableName>";

const credential = new AzureNamedKeyCredential(account, accountKey);
const client = new TableClient(`https://${account}.table.core.windows.net`, tableName, credential);

async function main() {
  const testEntity = {
    partitionKey: "P1",
    rowKey: "R1",
    foo: "foo",
    bar: 123
  };
  await client.createEntity(testEntity);
}

main();

Azurite i Emulator magazynu

Zestaw SDK klienta tabel platformy Azure współpracuje również z emulatorem serwera zgodnym z usługą Azurite, usługą Azure Storage i interfejsem API tabel. Zapoznaj się zrepozytorium Azurite), aby dowiedzieć się, jak rozpocząć korzystanie z niego.

Nawiązywanie połączenia z usługą Azurite za pomocą skrótu parametrów połączenia

Najprostszym sposobem nawiązywania połączenia z usługą Azurite z aplikacji jest skonfigurowanie parametrów połączenia odwołujących się do skrótu UseDevelopmentStorage=true. Skrót jest odpowiednikiem pełnych parametrów połączenia emulatora, który określa nazwę konta, klucz konta i punkty końcowe emulatora dla każdej z usług Azure Storage: (zobacz więcej). Za pomocą tego skrótu zestaw SDK klienta tabel platformy Azure skonfiguruje domyślne parametry połączenia i allowInsecureConnection w opcjach klienta.

import { TableClient } from "@azure/data-tables";

const connectionString = "UseDevelopmentStorage=true";
const client = TableClient.fromConnectionString(connectionString, "myTable");

Nawiązywanie połączenia z usługą Azurite bez skrótu parametrów połączenia

Możesz nawiązać połączenie z azurite ręcznie bez użycia skrótu parametrów połączenia, określając adres URL usługi i AzureNamedKeyCredential lub niestandardowe parametry połączenia. Jednak allowInsecureConnection należy ustawić ręcznie w przypadku uruchomienia Azurite w punkcie końcowym http.

import { TableClient, AzureNamedKeyCredential } from "@azure/data-tables";

const client = new TableClient(
  "<Azurite-http-table-endpoint>",
  "myTable",
  new AzureNamedKeyCredential("<Azurite-account-name>", "<Azurite-account-key>"),
  { allowInsecureConnection: true }
);

Rozwiązywanie problemów

Ogólne

W przypadku interakcji z usługą Tables przy użyciu zestawu SDK javascript/Typescript błędy zwracane przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST: kody błędów usługi Table Service

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Następne kroki

Wkrótce pojawi się więcej przykładów kodu: Problem#10531

Przyczyniając się

Ten projekt z zadowoleniem przyjmuje wkład i sugestie. Większość kontrybucja wymaga zgody na umowę licencyjną współautora (CLA), deklarując, że masz prawo, a w rzeczywistości przyznaj nam prawa do korzystania z twojego wkładu. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia bot CLA automatycznie określi, czy musisz podać cla i odpowiednio ozdobić żądanie ściągnięcia (np. etykieta, komentarz). Po prostu postępuj zgodnie z instrukcjami dostarczonymi przez bota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego CLA.

Ten projekt przyjął kodeks postępowania firmy Microsoft typu open source. Aby uzyskać więcej informacji, zobacz Kodeks postępowania — często zadawane pytania lub skontaktuj się z opencode@microsoft.com z dodatkowymi pytaniami lub komentarzami.

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik dotyczący współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

wrażenia