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

  • Artigo

As Tabelas do Azure são um serviço baseado na cloud que armazena dados NoSQL estruturados, fornecendo um arquivo de chaves/atributos com um design sem esquema. O armazenamento de tabelas proporciona flexibilidade e escalabilidade aos programadores com todas as melhores partes da cloud do Azure.

Utilize a biblioteca de cliente para:

  • Criar/Eliminar Tabelas
  • Consultar/Criar/Ler/Atualizar/Eliminar Entidades

O Azure Cosmos DB fornece uma API de Tabela para aplicações escritas para o armazenamento de Tabelas do Azure e que precisam de capacidades premium como:

  • Distribuição global chave na mão.
  • Débito dedicado em todo o mundo.
  • Latências de milissegundos na ordem de um dígito no percentil 99.º.
  • Elevada disponibilidade garantida.
  • Indexação secundária automática.
  • A biblioteca de cliente tabelas do Azure pode direcionar de forma totalmente integrada o armazenamento de tabelas do Azure ou os pontos finais de serviço de tabela do Azure Cosmos DB sem alterações de código.

Ligações principais:

Introdução

Pré-requisitos

Ambientes atualmente suportados:

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

Tem de ter uma subscrição do Azure e uma Conta de Armazenamento ou uma base de dados do Azure CosmosDB para utilizar este pacote.

Instalar o pacote @azure/data-tables

A forma preferencial de instalar a biblioteca de cliente das Tabelas do Azure para JavaScript é utilizar o gestor de pacotes npm. Escreva o seguinte numa janela de terminal:

npm install @azure/data-tables

Autenticar um TableServiceClient

As Tabelas do Azure suportam várias formas de autenticação. Para interagir com o serviço Tabelas do Azure, terá de criar uma instância de um cliente TableServiceClient tabelas ou TableClient , por exemplo. Veja exemplos para criar o TableServiceClient para saber mais sobre a autenticação.

Nota: o Azure Active Directory (AAD) só é suportado para contas de Armazenamento do Azure.

As seguintes funcionalidades, interfaces, classes ou funções só estão disponíveis no Node.js

  • Autorização de Chave Partilhada com base no nome da conta e na chave de conta
    • AzureNamedKeyCredential
    • Cadeia de ligação de conta.

Pacote JavaScript

Para utilizar esta biblioteca de cliente no browser, primeiro tem de utilizar um bundler. Para obter detalhes sobre como fazê-lo, consulte a nossa documentação de agrupamento.

CORS

Se precisar de desenvolver para browsers, tem de configurar regras de Partilha de Recursos Entre Origens (CORS) para a sua conta de armazenamento. Aceda a portal do Azure e Explorador de Armazenamento do Azure, localize a sua conta de armazenamento, crie novas regras CORS para os serviços blob/queue/file/table.

Por exemplo, pode criar as seguintes definições CORS para depuração. Mas personalize cuidadosamente as definições de acordo com os 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

Conceitos-chave

  • TableServiceClient - Cliente que fornece funções para interagir ao nível do Serviço de Tabelas, como criar, listar e eliminar tabelas

  • TableClient - Cliente que fornece funções para interagir ao nível de uma entidade, como criar, listar e eliminar entidades numa tabela.

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

  • Entity - As entidades são semelhantes às linhas. Uma entidade tem uma chave primária e um conjunto de propriedades. Uma propriedade é um nome, par typed-value, semelhante a uma coluna.

Utilizações comuns do serviço Tabela:

  • Armazenamento de TBs de dados estruturados com capacidade para servirem aplicações de dimensionamento da Web
  • Armazenar conjuntos de dados que não necessitam de associações complexas, chaves externas ou procedimentos armazenados e que podem ser des normalizados para acesso rápido
  • Consulta rápida de dados com um índice em cluster
  • Aceder a dados com as expressões de filtro do protocolo OData

Exemplos

Importar o pacote

Para utilizar os clientes, importe o pacote no seu ficheiro:

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

Em alternativa, importe seletivamente apenas os tipos de que precisa:

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

Criar o cliente do serviço Tabela

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

TableServiceClient com o AzureNamedKeyCredential

Pode instanciar um com um TableServiceClientAzureNamedKeyCredential ao transmitir o nome da conta e a chave de conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos a partir do portal do Azure.) [APENAS DISPONÍVEL NO 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 pedidos para o serviço Tabela ao direcionar um ponto final de Armazenamento. Com Azure AD, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso aos recursos da Tabela do Azure a utilizadores, grupos ou aplicações.

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

Com o @azure/identity pacote, pode autorizar pedidos de forma totalmente integrada em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, veja O README de 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 de SAS

Além disso, pode instanciar uma TableServiceClient com assinaturas de acesso partilhado (SAS). Pode obter o token de 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

Pode listar tabelas numa conta através de uma TableServiceClient instância que chama a listTables função. Esta função devolve uma PageableAsyncIterator que pode consumir com 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

Pode criar uma tabela através de uma TableServiceClient instância que chama a createTable função. Esta função utiliza o nome da tabela para criar como um parâmetro. Tenha em atenção que createTable não emitirá 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();

Eis 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 forma semelhante à com a TableServiceClient diferença que TableClient utiliza o nome de uma tabela como parâmetro

TableClient com AzureNamedKeyCredential

Pode instanciar um com um TableClientAzureNamedKeyCredential ao transmitir o nome da conta e a chave de conta como argumentos. (O nome da conta e a chave de conta podem ser obtidos a partir do portal do Azure.) [APENAS DISPONÍVEL NO 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 o (Azure Active Directory)

As Tabelas do Azure fornecem integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de pedidos para o serviço Tabela ao direcionar um ponto final de Armazenamento. Com Azure AD, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso aos recursos da Tabela do Azure a utilizadores, grupos ou aplicações.

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

Com o @azure/identity pacote, pode autorizar pedidos de forma totalmente integrada em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, veja O README de 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 de SAS

Pode instanciar um TableClient com assinaturas de acesso partilhado (SAS). Pode obter o token de 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 pedidos para o serviço Tabela ao direcionar um ponto final de Armazenamento. Com Azure AD, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso aos recursos da Tabela do Azure a utilizadores, grupos ou aplicações.

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

Com o @azure/identity pacote, pode autorizar pedidos de forma totalmente integrada em ambientes de desenvolvimento e produção. Para saber mais sobre Azure AD integração no Armazenamento do Azure, veja O README de 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 numa tabela

Pode listar entidades numa tabela através de uma TableClient instância que chama a listEntities função. Esta função devolve uma PageableAsyncIterator que pode consumir com 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

Pode criar uma nova Entidade numa tabela através de uma TableClient instância que chama a createEntity função. Esta função utiliza a entidade para inserir como um parâmetro. A entidade tem de 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 de Cliente das Tabelas do Azure também funciona com o Azurite, um emulador de servidor compatível com a API de Armazenamento e Tabelas do Azure. Veja o (repositório Azurite) sobre como começar a utilizá-lo.

Ligar ao Azurite com o atalho cadeia de ligação

A forma mais fácil de ligar ao Azurite a partir da sua aplicação é configurar uma cadeia de ligação que faça referência ao atalho UseDevelopmentStorage=true. O atalho é equivalente à cadeia de ligação completa do emulador, que especifica o nome da conta, a chave de conta e os pontos finais do emulador para cada um dos serviços de Armazenamento do Azure: (veja mais). Com este atalho, o SDK de Cliente das Tabelas do Azure configuraria a cadeia de ligação predefinida e allowInsecureConnection as opções de cliente.

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

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

Ligar ao Azurite sem atalho de Cadeia de Ligação

Pode ligar-se manualmente ao azurite sem utilizar o atalho de cadeia de ligação ao especificar o URL do serviço e AzureNamedKeyCredential ou uma cadeia de ligação personalizada. No entanto, allowInsecureConnection terá de ser definido manualmente caso o Azurite seja executado num http ponto final.

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

Resolução de problemas

Geral

Quando interage com o serviço Tabelas com o SDK Javascript/Typescript, os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST: Códigos de Erro do Serviço de Tabela de Armazenamento

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos HTTP e respostas, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Passos seguintes

Mais exemplos de código em breve Problema#10531

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

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

Impressões