Biblioteca de clientes do Azure Cosmos DB para JavaScript – versão 4.2.0

/Máquina

de status de build

O Azure Cosmos DB é um serviço de banco de dados multimodelo distribuído globalmente que dá suporte a bancos de dados de documento, chave-valor, coluna larga e grafo. Esse pacote destina-se a aplicativos JavaScript/TypeScript para interagir com bancos de dados da API SQL e os documentos JSON que eles contêm:

• Criar bancos de dados do Cosmos DB e modificar suas configurações
• Criar e modificar contêineres para armazenar coleções de documentos JSON
• Criar, ler, atualizar e excluir os itens (documentos JSON) em seus contêineres
• Consultar os documentos em seu banco de dados usando a sintaxe semelhante a SQL

Links de chave:

• do pacote (npm)
• documentação de referência da API
• documentação do produto

Introdução

Pré-requisitos

Assinatura do Azure e conta da API SQL do Cosmos DB

Você deve ter um de Assinatura do Azure e uma conta do Cosmos DB (API do SQL) para usar esse pacote.

Se você precisar de uma conta da API sql do Cosmos DB, poderá usar o do Azure Cloud Shell para criar uma com este comando da CLI do Azure:

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-database-account-name>

Ou você pode criar uma conta no portal do Azure

NodeJS

Esse pacote é distribuído por meio de npm que vem pré-instalado com nodeJS usando uma versão LTS.

CORS

Você precisa configurar cors (compartilhamento de recursos entre origens) regras para sua conta do Cosmos DB se precisar desenvolver para navegadores. Siga as instruções no documento vinculado para criar novas regras CORS para o Cosmos DB.

Instalar este pacote

npm install @azure/cosmos

Obter credenciais de conta

Você precisará do do ponto de extremidade da conta do Cosmos DB e key. Você pode encontrá-los no do Portal do Azure ou usar o snippet de da CLI do Azure abaixo. O snippet é formatado para o shell do Bash.

az cosmosdb show --resource-group <your-resource-group> --name <your-account-name> --query documentEndpoint --output tsv
az cosmosdb keys list --resource-group <your-resource-group> --name <your-account-name> --query primaryMasterKey --output tsv

Criar uma instância de CosmosClient

A interação com o Cosmos DB começa com uma instância da classe CosmosClient

const { CosmosClient } = require("@azure/cosmos");

const endpoint = "https://your-account.documents.azure.com";
const key = "<database account masterkey>";
const client = new CosmosClient({ endpoint, key });

async function main() {
  // The rest of the README samples are designed to be pasted into this function body
}

main().catch((error) => {
  console.error(error);
});

Para simplificar, incluímos o key e endpoint diretamente no código, mas você provavelmente desejará carregá-los de um arquivo que não está no controle do código-fonte usando um projeto como dotenv ou carregamento de variáveis de ambiente

Em ambientes de produção, segredos como chaves devem ser armazenados no Azure Key Vault

Principais conceitos

Depois de inicializar umdo CosmosClient , você poderá interagir com os principais tipos de recursos no Cosmos DB:

• Banco de Dados: uma conta do Cosmos DB pode conter vários bancos de dados. Ao criar um banco de dados, especifique a API que deseja usar ao interagir com seus documentos: SQL, MongoDB, Gremlin, Cassandra ou Tabela do Azure. Use o objeto Database para gerenciar seus contêineres.

• contêiner: um contêiner é uma coleção de documentos JSON. Você cria (inserir), lê, atualiza e exclui itens em um contêiner usando métodos no objeto contêiner .

• Item: Um Item é um documento JSON armazenado em um contêiner. Cada Item deve incluir uma chave id com um valor que identifique exclusivamente o item dentro do contêiner. Se você não fornecer um id, o SDK gerará um automaticamente.

Para obter mais informações sobre esses recursos, consulte Trabalhando com bancos de dados, contêineres e itens do Azure Cosmos.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Cosmos DB, incluindo:

• criar um banco de dados
• Criar um contêiner
• usando chaves de partição
• inserir itens
• documentos de consulta
• ler um item
• Excluir um item
• CRUD no Contêiner com chave de partição hierárquica

Criar um banco de dados

Depois de autenticar seu do CosmosClient, você pode trabalhar com qualquer recurso na conta. O snippet de código abaixo cria um banco de dados da API NOSQL.

const { database } = await client.databases.createIfNotExists({ id: "Test Database" });
console.log(database.id);

Criar um contêiner

Este exemplo cria um contêiner com configurações padrão

const { container } = await database.containers.createIfNotExists({ id: "Test Database" });
console.log(container.id);

Usando chaves de partição

Este exemplo mostra vários tipos de chaves de partição com suporte.

await container.item("id", "1").read();        // string type
await container.item("id", 2).read();          // number type
await container.item("id", true).read();       // boolean type
await container.item("id", {}).read();         // None type
await container.item("id", undefined).read();  // None type
await container.item("id", null).read();       // null type

Se a Chave de Partição consistir em um único valor, ela poderá ser fornecida como um valor literal ou uma matriz.

await container.item("id", "1").read();
await container.item("id", ["1"]).read();

Se a Chave de Partição consistir em mais de um valor, ela deverá ser fornecida como uma matriz.

await container.item("id", ["a", "b"]).read();
await container.item("id", ["a", 2]).read();
await container.item("id", [{}, {}]).read();
await container.item("id", ["a", {}]).read();
await container.item("id", [2, null]).read();

Inserir itens

Para inserir itens em um contêiner, passe um objeto que contém seus dados para Items.upsert. O serviço do Azure Cosmos DB requer que cada item tenha uma chave de id. Se você não fornecer um, o SDK gerará um id automaticamente.

Este exemplo insere vários itens no contêiner

const cities = [
  { id: "1", name: "Olympia", state: "WA", isCapitol: true },
  { id: "2", name: "Redmond", state: "WA", isCapitol: false },
  { id: "3", name: "Chicago", state: "IL", isCapitol: false }
];
for (const city of cities) {
  await container.items.create(city);
}

Ler um item

Para ler um único item de um contêiner, use Item.read. Essa é uma operação mais barata do que usar o SQL para consultar por id.

await container.item("1", "1").read();

CRUD no Contêiner com chave de partição hierárquica

Criar um contêiner com chave de partição hierárquica

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

Inserir um item com chave de partição hierárquica definida como - ["/name", "/address/zip"]

const item = {
  id: "1",
  name: 'foo',
  address: {
    zip: 100
  },
  active: true
}
await container.items.create(item);

Para ler um único item de um contêiner com chave de partição hierárquica definida como - ["/name", "/address/zip"],

await container.item("1", ["foo", 100]).read();

Consultar um item com chave de partição hierárquica com chave de partição hierárquica definida como - ["/name", "/address/zip"],

const { resources } = await container.items
  .query("SELECT * from c WHERE c.active = true", {
          partitionKey: ["foo", 100],
        })
  .fetchAll();
for (const item of resources) {
  console.log(`${item.name}, ${item.address.zip} `);
}

Excluir um item

Para excluir itens de um contêiner, use Item.delete.

// Delete the first item returned by the query above
await container.item("1").delete();

Consultar o banco de dados

Um banco de dados da API SQL do Cosmos DB dá suporte à consulta dos itens em um contêiner com Items.query usando a sintaxe semelhante a SQL:

const { resources } = await container.items
  .query("SELECT * from c WHERE c.isCapitol = true")
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

Execute consultas parametrizadas passando um objeto que contém os parâmetros e seus valores para Items.query:

const { resources } = await container.items
  .query({
    query: "SELECT * from c WHERE c.isCapitol = @isCapitol",
    parameters: [{ name: "@isCapitol", value: true }]
  })
  .fetchAll();
for (const city of resources) {
  console.log(`${city.name}, ${city.state} is a capitol `);
}

Para obter mais informações sobre como consultar bancos de dados do Cosmos DB usando a API do SQL, consulte Consultar dados do Azure Cosmos DB com consultas SQL.

Alterar o modelo de pull do feed

O feed de alterações pode ser buscado para uma chave de partição, um intervalo de feeds ou um contêiner inteiro.

Para processar o feed de alterações, crie uma instância de ChangeFeedPullModelIterator. Ao criar inicialmente ChangeFeedPullModelIterator, você deve especificar um valor de changeFeedStartFrom necessário dentro do ChangeFeedIteratorOptions que consiste na posição inicial para ler as alterações e o recurso (uma chave de partição ou um FeedRange) para o qual as alterações devem ser buscadas. Opcionalmente, você pode usar maxItemCount em ChangeFeedIteratorOptions para definir o número máximo de itens recebidos por página.

Observação: se nenhum valor de changeFeedStartFrom for especificado, o changefeed será buscado para um contêiner inteiro de Now().

Há quatro posições iniciais para o feed de alterações:

• Beginning

// Signals the iterator to read changefeed from the beginning of time.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(),
};
const iterator = container.getChangeFeedIterator(options);

• Time

// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11"); // some sample date
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Time(time),
};

• Now

// Signals the iterator to read changefeed from this moment onward.
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Now(),
};

• Continuation

// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken),
};

Aqui está um exemplo de busca de feed de alterações para uma chave de partição

const partitionKey = "some-partition-Key-value";
const options = {
  changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
  const response = await iterator.readNext();
  // process this response
}

Como o feed de alterações é efetivamente uma lista infinita de itens que abrange todas as gravações e atualizações futuras, o valor de hasMoreResults é sempre true. Quando você tenta ler o feed de alterações e não há novas alterações disponíveis, recebe uma resposta com NotModified status.

Diretrizes de uso mais detalhadas e exemplos de feed de alterações podem ser encontrados aqui.

Tratamento de erros

O SDK gera vários tipos de erros que podem ocorrer durante uma operação.

1. ErrorResponse será gerada se a resposta de uma operação retornar um código de erro de >=400.
2. TimeoutError será gerada se Abortar for chamado internamente devido ao tempo limite.
3. AbortError será gerada se qualquer sinal passado pelo usuário causou a anulação.
4. RestError é gerada em caso de falha na chamada do sistema subjacente devido a problemas de rede.
5. Erros gerados por qualquer devDependencies. Por exemplo, @azure/identity pacote pode gerar CredentialUnavailableError.

Veja a seguir um exemplo para lidar com erros de tipo ErrorResponse, TimeoutError, AbortErrore RestError.

try {
  // some code
} catch (err) {
  if (err instanceof ErrorResponse) {
    // some specific error handling.
  } else if (err instanceof RestError) {
    // some specific error handling.
  }
  // handle other type of errors in similar way.
  else {
    // for any other error.
  }
}

É importante lidar corretamente com esses erros para garantir que seu aplicativo possa se recuperar normalmente de quaisquer falhas e continuar funcionando conforme o esperado. Mais detalhes sobre alguns desses erros e suas possíveis soluções podem ser encontrados aqui.

Solucionando problemas

Geral

Quando você interage com erros do Cosmos DB retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST:

códigos de status HTTP para do Azure Cosmos DB

Conflitos

Por exemplo, se você tentar criar um item usando um id que já está em uso no banco de dados do Cosmos DB, um erro 409 será retornado, indicando o conflito. No snippet a seguir, o erro é tratado normalmente capturando a exceção e exibindo informações adicionais sobre o erro.

try {
  await containers.items.create({ id: "existing-item-id" });
} catch (error) {
  if (error.code === 409) {
    console.log("There was a conflict with an existing item");
  }
}

Transpilação

Os SDKs do Azure foram projetados para dar suporte à sintaxe ES5 JavaScript e versões LTS do Node.js. Se você precisar de suporte para runtimes JavaScript anteriores, como o Internet Explorer ou o Node 6, será necessário transpilar o código do SDK como parte do processo de build.

Manipular erros transitórios com novas tentativas

Ao trabalhar com o Cosmos DB, você pode encontrar falhas transitórias causadas por limites de taxa impostas pelo serviço ou outros problemas transitórios, como interrupções de rede. Para obter informações sobre como lidar com esses tipos de falhas, consulte padrão de repetição no guia Padrões de Design de Nuvem e o padrão disjuntor relacionado.

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. Ao usar AZURE_LOG_LEVEL certifique-se de defini-la antes que a biblioteca de log seja inicializada. O ideal é passá-la pela linha de comando, se estiver usando bibliotecas como dotenv verifique se essas bibliotecas são inicializadas antes da biblioteca de registro em log.

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

Para obter instruções mais detalhadas sobre como habilitar logs, você pode examinar os documentos do pacote @azure/agente.

Diagnostics

O recurso de Diagnóstico do Cosmos fornece insights aprimorados sobre todas as operações do cliente. Um objeto CosmosDiagnostics é adicionado à resposta de todas as operações do cliente. como

• Reponse de operação de pesquisa de ponto – item.read(), container.create(), database.delete()
• Reponse de operação de consulta –queryIterator.fetchAll(),
• Operações em massa e lote –item.batch().
• Objetos de resposta de erro/exceção.

Um objeto CosmosDiagnostics é adicionado à resposta de todas as operações do cliente. Há 3 níveis de Diagnóstico do Cosmos, informações, depuração e depuração não seguras. Onde apenas as informações são destinadas a sistemas de produção e depuração e depuração não segura devem ser usadas durante o desenvolvimento e a depuração, pois consomem recursos significativamente mais altos. O nível de Diagnóstico do Cosmos pode ser definido de duas maneiras

• Programaticamente

  const client = new CosmosClient({ endpoint, key, diagnosticLevel: CosmosDbDiagnosticLevel.debug });

• Usando variáveis de ambiente. (O nível de diagnóstico definido pela variável De ambiente tem prioridade mais alta em relação à configuração por meio de opções de cliente.)

  export AZURE_COSMOSDB_DIAGNOSTICS_LEVEL="debug"

O Diagnóstico do Cosmos tem três membros

• Tipo ClientSideRequestStatistics: contém detalhes de diagnóstico de agregações, incluindo pesquisas de metadados, repetições, pontos de extremidade contatados e estatísticas de solicitação e resposta, como tamanho e duração da carga. (é sempre coletado, pode ser usado em sistemas de produção.)

• DiagnosticNode: é uma estrutura semelhante a uma árvore que captura informações detalhadas de diagnóstico. Semelhante ao har gravação presente em navegadores. Esse recurso é desabilitado por padrão e destina-se apenas à depuração de ambientes de não produção. (coletado no nível de diagnóstico depuração e depuração não seguro)

• ClientConfig: captura informações essenciais relacionadas às configurações do cliente durante a inicialização do cliente. (coletado no nível de diagnóstico depuração e depuração não seguro)

Certifique-se de nunca definir o nível de diagnóstico como debug-unsafe no ambiente de produção, pois esse nível CosmosDiagnostics captura os conteúdos de solicitação e resposta e se você optar por registrá-lo (por padrão, é registrado por @azure/logger no nível verbose). Essas cargas podem ser capturadas em seus coletores de log.

Consumindo diagnósticos

• Como diagnostics é adicionado a todos os objetos response. Você pode acessar programaticamente CosmosDiagnostic da seguinte maneira.

  // For point look up operations
  const { container, diagnostics: containerCreateDiagnostic } =
    await database.containers.createIfNotExists({
      id: containerId,
      partitionKey: {
        paths: ["/key1"],
      },
  });

  // For Batch operations
   const operations: OperationInput[] = [
    {
      operationType: BulkOperationType.Create,
      resourceBody: { id: 'A', key: "A", school: "high" },
    },
  ];
  const response = await container.items.batch(operations, "A"); 
  
  // For query operations
  const queryIterator = container.items.query("select * from c");
  const { resources, diagnostics } = await queryIterator.fetchAll();

  // While error handling
  try {
    // Some operation that might fail
  } catch (err) {
    const diagnostics = err.diagnostics
  }

• Você também pode registrar diagnostics usando @azure/logger, o diagnóstico é sempre registrado usando @azure/logger no nível verbose. Portanto, se você definir o nível de diagnóstico como debug ou debug-unsafe e @azure/logger nível como verbose, diagnostics será registrado.

Próximas etapas

Mais código de exemplo

Vários exemplos estão disponíveis para você no repositório GitHub do SDK. Esses exemplos fornecem código de exemplo para cenários adicionais comumente encontrados ao trabalhar com o Cosmos DB:

• Operações de banco de dados
• Operações de contêiner
• Operações de item
• Configurando a indexação
• Lendo um feed de alterações de contêiner
• Procedimentos armazenados
• Alterando as configurações de taxa de transferência de banco de dados/contêiner
• Operações de gravação de várias regiões

Limitações

Atualmente, os recursos abaixo não têm suporte. Para obter opções alternativas, verifique a seção Soluções alternativas abaixo.

Limitações do plano de dados:

• Consultas com COUNT de uma subconsulta DISTINCT
• Acesso direto ao modo TCP
• As consultas de partição cruzada agregadas, como classificação, contagem e distintas, não dão suporte a tokens de continuação. Consultas que podem ser transmitidas, como SELECT * FROM WHERE, suporte a tokens de continuação. Consulte a seção "Solução alternativa" para executar consultas não transmitiveis sem um token de continuação.
• Feed de Alterações: Processador
• Feed de Alterações: Ler valores de chave de várias partições
• Suporte ao modelo de pull do Feed de Alterações para chaves de partição hierárquicas parciais nº 27059
• ORDER BY de partição cruzada para tipos mistos

Limitações do plano de controle:

• Obter métricas CollectionSizeUsage, DatabaseUsage e DocumentUsage
• Criar índice geoespacial
• Atualizar taxa de transferência de Dimensionamento Automático

Soluções alternativas

Token de continuação para consultas de partições cruzadas

Você pode obter consultas de partição cruzada com suporte de token de continuação usando padrão de carro lateral. Esse padrão também pode permitir que os aplicativos sejam compostos por componentes heterogêneos e tecnologias.

Executando uma consulta de partição cruzada não extenuável

Para executar consultas não transmitiveis sem o uso de tokens de continuação, você pode criar um iterador de consulta com a especificação e as opções de consulta necessárias. O código de exemplo a seguir demonstra como usar um iterador de consulta para buscar todos os resultados sem a necessidade de um token de continuação:

const querySpec = {
  query: "SELECT c.status, COUNT(c.id) AS count FROM c GROUP BY c.status",
};
const queryOptions = {
  maxItemCount: 10, // maximum number of items to return per page
  enableCrossPartitionQuery: true,
};
const querIterator = await container.items.query(querySpec, queryOptions);
while (querIterator.hasMoreResults()) {
  const { resources: result } = await querIterator.fetchNext();
  //Do something with result
}

Essa abordagem também pode ser usada para consultas que podem ser transmitidas.

Operações do Plano de Controle

Normalmente, você pode usar do Portal do Azure, da API REST do Provedor de Recursos do Azure Cosmos DB, CLI do Azure ou do PowerShell para as limitações sem suporte do painel de controle.

Documentação adicional

Para obter uma documentação mais abrangente sobre o serviço do Cosmos DB, consulte a documentação do Azure Cosmos DB no docs.microsoft.com.

Links úteis

• bem-vindo ao do Azure Cosmos DB
• início rápido
• do Tutorial do
• exemplos de
• introdução ao modelo de recurso do serviço do Azure Cosmos DB
• introdução à API do SQL do Serviço do Azure Cosmos DB
• de particionamento
• documentação da API

Contribuindo

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