Compartilhar via

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

  • Artigo

de Tabelas do Azure é um serviço baseado em nuvem que armazena dados estruturados do NoSQL, 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
  • Consultar/criar/ler/atualizar/excluir entidades

O Azure Cosmos DB fornece uma API de Tabela para aplicativos 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 milissegundos de dígito único no percentil 99.
  • Alta disponibilidade garantida.
  • Indexação secundária automática.
  • 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 de chave:

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 um de assinatura do Azure e um de 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 de 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 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 no 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. Acesse o portal do Azure e o 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 às 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:

  • Armazenar TBs de dados estruturados capazes de atender aplicativos de escala 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
  • Consultando rapidamente 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 parâmetro options.

TableServiceClient com AzureNamedKeyCredential

Você pode criar uma instância de um TableServiceClient com uma AzureNamedKeyCredential passando o nome da conta e a chave da conta 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)

O Azure Tables fornece integração com o Azure AD (Azure Active Directory) 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 "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o pacote @azure/identity, você pode autorizar diretamente 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 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 com o token SAS

Além disso, você pode criar uma instância de 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 instância TableServiceClient chamando a função listTables. 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() {
  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 de TableServiceClient chamando a função createTable. 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 de tabela

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

TableClient com AzureNamedKeyCredential

Você pode criar uma instância de um TableClient com uma AzureNamedKeyCredential passando o nome da conta e a chave da conta 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)

O Azure Tables fornece integração com o Azure AD (Azure Active Directory) 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 "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o pacote @azure/identity, você pode autorizar diretamente 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 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 com o token SAS

Você pode criar uma instância de 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)

O Azure Tables fornece integração com o Azure AD (Azure Active Directory) 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 "Colaborador de Dados da Tabela de Armazenamento" ou "Leitor de Dados da Tabela de Armazenamento".

Com o pacote @azure/identity, você pode autorizar diretamente 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 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
);

Listar entidades em uma tabela

Você pode listar entidades em uma tabela por meio de uma instância de TableClient chamando a função listEntities. 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() {
  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. 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();

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 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 cadeia de conexão

A maneira mais fácil de se conectar ao Azurite 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 do 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 das 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 de serviço e AzureNamedKeyCredential ou uma cadeia de conexão personalizada. No entanto, allowInsecureConnection precisarão ser definidos 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 }
);

Solucionando 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 da API REST: códigos de erro do Serviço de Tabela de Armazenamento

Log

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 runtime chamando setLogLevel no @azure/logger:

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

setLogLevel("info");

Próximas etapas

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

Contribuindo

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

Ao enviar uma solicitação de pull, um CLA-bot determinará automaticamente se você precisa fornecer um CLA e decorar a 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 oCódigo de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as perguntas frequentes sobre o Código de Conduta ou entre em contato com opencode@microsoft.com com perguntas ou comentários adicionais.

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

impressões