Partilhar via

Biblioteca de cliente do Azure Tables para JavaScript - versão 13.3.0

  • Artigo

Azure Tables é um serviço baseado em nuvem que armazena dados NoSQL estruturados, fornecendo um armazenamento 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 cliente para:

  • Criar/Excluir tabelas
  • Consulta/Criar/Ler/Atualizar/Excluir entidades

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

  • Distribuição global chave-na-mão.
  • Taxa de transferência dedicada em todo o mundo.
  • Latências de milissegundos de um dígito no percentil 99.
  • Alta disponibilidade garantida.
  • Indexação secundária automática.
  • A biblioteca de cliente do Azure Tables pode direcionar diretamente o armazenamento de tabelas do Azure ou os pontos de extremidade do serviço de tabela do Azure Cosmos DB sem alterações de código.

Ligações principais:

Primeiros passos

Pré-requisitos

Ambientes atualmente suportados:

  • Versões LTS do Node.js
  • Últimas versões do Safari, Chrome, Edge e Firefox

Você deve ter um de assinatura do Azure e uma conta de armazenamento ou um banco de dados do Azure CosmosDB para usar este pacote.

Instalar o pacote @azure/data-tables

A maneira preferida de instalar a biblioteca de cliente do Azure Tables 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 autenticação. 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. Consulte exemplos para criar o TableServiceClient para saber mais sobre autenticação.

Observação: o Azure Ative Directory (AAD) só é suportado 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 cliente no navegador, primeiro você precisa usar um bundler. Para obter detalhes sobre como fazer isso, consulte nossa documentação de agregação de .

CORS

Você precisa configurar regras de de compartilhamento de recursos entre origens (Cross-Origin Resourcesharing) para sua conta de armazenamento se precisar desenvolver para navegadores. Vá para o portal do Azure e o Gerenciador de Armazenamento do Azure, encontre 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. Mas por favor, personalize as configurações cuidadosamente de acordo com suas necessidades 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

Conceitos-chave

  • 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 - As tabelas armazenam dados como coleções de entidades.

  • Entity - As 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 de tabela incluem:

  • Armazenamento de TBs de dados estruturados capazes de servir aplicações à escala da Web
  • Armazenamento de conjuntos de dados que não exigem junções complexas, chaves estrangeiras ou procedimentos armazenados e que podem ser desnormalizados para acesso rápido
  • Consultando dados rapidamente usando um índice clusterizado
  • Acessando dados usando as expressões de filtro do 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 de serviço Tabela

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

TableServiceClient com AzureNamedKeyCredential

Você pode instanciar um TableServiceClient com um AzureNamedKeyCredential passando nome-conta e chave-conta como argumentos. (O nome da conta e a chave da conta podem ser obtidos no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO 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 com TokenCredential (AAD)

As Tabelas do Azure fornecem integração com o Azure Ative 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 o 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 "Storage Table Data Contributor" ou "Storage Table Data Reader".

Com o pacote @azure/identity, você pode autorizar perfeitamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre a integração do Azure AD no Armazenamento do Azure, consulte 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 o 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 dentro de uma conta por meio de uma instância TableServiceClient chamando a função listTables. Esta 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() {
  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();

Criar uma nova tabela

Você pode criar uma tabela por meio de uma instância TableServiceClient chamando a função createTable. Esta função usa o nome da tabela para criar como um parâmetro. Observe que createTable não lançará 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 de tabela

O TableClient é criado de forma semelhante ao TableServiceClient com a diferença de que TableClient toma um nome de tabela como parâmetro

TableClient com AzureNamedKeyCredential

Você pode instanciar um TableClient com um AzureNamedKeyCredential passando nome-conta e chave-conta como argumentos. (O nome da conta e a chave da conta podem ser obtidos no portal azure.) [DISPONÍVEL APENAS EM TEMPO DE EXECUÇÃO 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 com TokenCredential (Azure Ative Directory)

As Tabelas do Azure fornecem integração com o Azure Ative 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 o 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 "Storage Table Data Contributor" ou "Storage Table Data Reader".

Com o pacote @azure/identity, você pode autorizar perfeitamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre a integração do Azure AD no Armazenamento do Azure, consulte 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 o token SAS

Você pode instanciar um TableClient com uma 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 Ative 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 o 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 "Storage Table Data Contributor" ou "Storage Table Data Reader".

Com o pacote @azure/identity, você pode autorizar perfeitamente solicitações em ambientes de desenvolvimento e produção. Para saber mais sobre a integração do Azure AD no Armazenamento do Azure, consulte 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 instância TableClient chamando a função listEntities. Esta 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() {
  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();

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

Você pode criar uma nova Entidade em uma tabela por meio de uma instância TableClient chamando a função createEntity. Esta função leva 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();

Azurite e emulador de armazenamento

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

Conectando-se ao Azurite com o atalho da Cadeia de Conexão

A maneira mais fácil de se conectar ao Azurite a partir do seu aplicativo é configurar uma cadeia de conexão que faça referência ao atalho UseDevelopmentStorage=true. O atalho é equivalente à cadeia de conexão completa para o emulador, que especifica o nome da conta, a chave da conta e os pontos de extremidade do emulador para cada um dos serviços de Armazenamento do Azure: (ver 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 da cadeia de conexão especificando a URL e a AzureNamedKeyCredential do serviço ou uma cadeia de conexão personalizada. No entanto, allowInsecureConnection precisará ser definido manualmente caso o Azurite seja executado em um ponto de extremidade 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 }
);

Solução de problemas

Geral

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

Registo

Habilitar o registro em 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 registro em log pode ser habilitado em tempo de execução chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximos passos

Mais exemplos de código em breve Issue#10531

Contribuição

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

Quando você envia uma solicitação pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar o PR adequadamente (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 usando nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct. Para obter mais informações, consulte o de perguntas frequentes sobre o Código de Conduta ou entre em contato com para obter perguntas ou comentários adicionais.

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

Impressões