Biblioteca de clientes das Tabelas do Azure para JavaScript – versão 13.2.2

  • Artigo

O Azure Tables é um serviço baseado em nuvem que armazena dados NoSQL estruturados, fornecendo um repositório de chave/atributo com um design sem esquema. O armazenamento de tabelas oferece aos desenvolvedores flexibilidade e escalabilidade com todas as melhores partes da nuvem do Azure.

Use a biblioteca de clientes para:

  • Criar/excluir tabelas
  • Entidades query/Create/Read/Update/Delete

O Azure Cosmos DB fornece uma API de Tabela para aplicativos que são gravados para o Armazenamento de Tabelas do Azure e que precisam de recursos premium como:

  • Distribuição global turnkey.
  • Taxa de transferência dedicada em todo o mundo.
  • Latências de dígito único em milissegundos no percentil 99.
  • Alta disponibilidade garantia.
  • Indexação automática secundária.
  • A biblioteca de clientes das Tabelas do Azure pode direcionar diretamente o armazenamento de tabelas do Azure ou os pontos de extremidade de serviço de tabela do Azure Cosmos DB sem alterações de código.

Links principais:

Introdução

Pré-requisitos

Ambientes com suporte no momento:

  • Versões lts de Node.js
  • Versões mais recentes do Safari, Chrome, Edge e Firefox

Você deve ter uma assinatura do Azure e uma Conta de Armazenamento ou um banco de dados do Azure CosmosDB para usar esse pacote.

Instalar o pacote @azure/data-tables

A maneira preferida de instalar a biblioteca de clientes das Tabelas do Azure para JavaScript é usar o gerenciador de pacotes npm. Digite o seguinte em uma janela do terminal:

npm install @azure/data-tables

Autenticar um TableServiceClient

As Tabelas do Azure dão suporte a várias maneiras de autenticar. Para interagir com o serviço Tabelas do Azure, você precisará criar uma instância de um cliente de Tabelas – TableServiceClient ou TableClient por exemplo. Confira exemplos para criar o TableServiceClient para saber mais sobre a autenticação.

Observação: o AAD (Azure Active Directory) só tem suporte para contas de Armazenamento do Azure.

Os seguintes recursos, interfaces, classes ou funções só estão disponíveis em Node.js

  • Autorização de chave compartilhada com base no nome da conta e na chave da conta
    • AzureNamedKeyCredential
    • Cadeia de conexão da conta.

Pacote JavaScript

Para usar essa biblioteca de clientes no navegador, primeiro você precisa usar um empacotador. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agrupamento.

CORS

Você precisa configurar regras de CORS (Compartilhamento de Recursos entre Origens) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para portal do Azure e Gerenciador de Armazenamento do Azure, localize sua conta de armazenamento, crie novas regras CORS para serviços de blob/fila/arquivo/tabela.

Por exemplo, você pode criar as seguintes configurações de CORS para depuração. Porém, personalize as configurações cuidadosamente de acordo com seus requisitos no ambiente de produção.

  • Origens permitidas: *
  • Verbos permitidos: DELETE, GET, HEAD,MERGE,POST,OPTIONS,PUT
  • Cabeçalhos permitidos: *
  • Cabeçalhos expostos: *
  • Idade máxima (segundos): 86400

Principais conceitos

  • TableServiceClient - Cliente que fornece funções para interagir em um nível de Serviço de Tabela, como criar, listar e excluir tabelas

  • TableClient – Cliente que fornece funções para interagir em um nível de entidade, como criar, listar e excluir entidades dentro de uma tabela.

  • Table - Tabelas armazenam dados como coleções de entidades.

  • Entity – Entidades são semelhantes a linhas. Uma entidade tem uma chave primária e um conjunto de propriedades. Uma propriedade é um nome, par de valor digitado, semelhante a uma coluna.

Os usos comuns do serviço Tabela incluem:

  • Armazenamento de TBs de dados estruturados capazes de atender a aplicativos de dimensionamento da Web
  • Armazenar conjuntos de dados que não exigem junções complexas, chaves estrangeiras ou procedimentos armazenados e podem ser des normalizados para acesso rápido
  • Consulta rápida de dados usando um índice clusterizado
  • Acessando dados usando as expressões de filtro de protocolo OData

Exemplos

Importar o pacote

Para usar os clientes, importe o pacote em seu arquivo:

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

Como alternativa, importe seletivamente apenas os tipos necessários:

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

Criar o cliente do serviço Tabela

O TableServiceClient requer uma URL para o serviço de tabela e uma credencial de acesso. Opcionalmente, ele também aceita algumas configurações no options parâmetro .

TableServiceClient com AzureNamedKeyCredential

Você pode instanciar um TableServiceClient com um AzureNamedKeyCredential passando account-name e account-key como argumentos. (O nome da conta e a chave de conta podem ser obtidos no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

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 com TokenCredential (AAD)

As Tabelas do Azure fornecem integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de solicitações para o serviço Tabela ao direcionar um ponto de extremidade de Armazenamento. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos da Tabela do Azure a usuários, grupos ou aplicativos.

Para acessar um recurso de tabela com um TokenCredential, a identidade autenticada deve ter a função "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o @azure/identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, confira o LEIAME do Azure.Identity

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 com token SAS

Além disso, você pode instanciar um TableServiceClient com uma SAS (assinaturas de acesso compartilhado). Você pode obter o token SAS no Portal do Azure.

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

Listar tabelas na conta

Você pode listar tabelas em uma conta por meio de uma TableServiceClient instância que chama a listTables função. Essa função retorna um PageableAsyncIterator que você pode consumir usando 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() {
  let 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();

Criar uma nova tabela

Você pode criar uma tabela por meio de uma TableServiceClient instância que chama a createTable função. Essa função usa o nome da tabela para criar como um parâmetro. Observe que createTable não gerará um erro quando a tabela já existir.

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

Aqui está um exemplo que demonstra como testar se a tabela já existe ao tentar criá-la:

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

Criar o cliente da tabela

O TableClient é criado de maneira semelhante à com a TableServiceClient diferença que TableClient usa um nome de tabela como um parâmetro

TableClient com AzureNamedKeyCredential

Você pode instanciar um TableClient com um AzureNamedKeyCredential passando account-name e account-key como argumentos. (O nome da conta e a chave de conta podem ser obtidos no portal do azure.) [DISPONÍVEL APENAS EM NODE.JS RUNTIME]

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 com TokenCredential (Azure Active Directory)

As Tabelas do Azure fornecem integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de solicitações para o serviço Tabela ao direcionar um ponto de extremidade de Armazenamento. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos da Tabela do Azure a usuários, grupos ou aplicativos.

Para acessar um recurso de tabela com um TokenCredential, a identidade autenticada deve ter a função "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o @azure/identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, confira o LEIAME do Azure.Identity

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 com token SAS

Você pode criar uma instância de um TableClient com sas (assinaturas de acesso compartilhado). Você pode obter o token SAS no Portal do Azure.

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 com TokenCredential (AAD)

As Tabelas do Azure fornecem integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de solicitações para o serviço Tabela ao direcionar um ponto de extremidade de Armazenamento. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos da Tabela do Azure a usuários, grupos ou aplicativos.

Para acessar um recurso de tabela com um TokenCredential, a identidade autenticada deve ter a função "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o @azure/identity pacote, você pode autorizar diretamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, confira o LEIAME do Azure.Identity

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

Listar entidades em uma tabela

Você pode listar entidades dentro de uma tabela por meio de uma TableClient instância que chama a listEntities função. Essa função retorna um PageableAsyncIterator que você pode consumir usando 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() {
  let 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();

Criar uma nova entidade e adicioná-la a uma tabela

Você pode criar uma nova Entidade em uma tabela por meio de uma TableClient instância que chama a createEntity função. Essa função usa a entidade para inserir como um parâmetro. A entidade deve conter partitionKey e 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();

Emulador de Armazenamento e Azurite

O SDK do Cliente de Tabelas do Azure também funciona com o Azurite, um emulador de servidor compatível com a API de Armazenamento e Tabelas do Azure. Consulte o (repositório do Azurite) sobre como começar a usá-lo.

Conectando-se ao Azurite com o atalho de cadeia de conexão

A maneira mais fácil de se conectar ao Azurite do seu aplicativo é configurar uma cadeia de conexão que referencie o atalho UseDevelopmentStorage=true. O atalho é equivalente à cadeia de conexão completa do emulador, que especifica o nome da conta, a chave de conta e os pontos de extremidade do emulador para cada um dos serviços de Armazenamento do Azure: (veja mais). Usando esse atalho, o SDK do Cliente de Tabelas do Azure configuraria a cadeia de conexão padrão e allowInsecureConnection nas opções do cliente.

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

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

Conectando-se ao Azurite sem atalho de cadeia de conexão

Você pode se conectar ao azurite manualmente sem usar o atalho de cadeia de conexão especificando a URL do serviço e AzureNamedKeyCredential ou uma cadeia de conexão personalizada. No entanto, allowInsecureConnection precisará ser definido manualmente caso o Azurite seja executado em um http ponto de extremidade.

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

Solução de problemas

Geral

Quando você interage com o serviço Tabelas usando o SDK do Javascript/Typescript, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações da API REST: Códigos de erro do Serviço tabela de armazenamento

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Próximas etapas

Mais exemplos de código em breve Problema nº 10531

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões