SDK do Node.js do Azure Cosmos DB para a API do NoSQL: notas sobre a versão e recursos

  • Artigo

APLICA-SE A: NoSQL

Recurso Link
Baixar o SDK @azure/cosmos
Documentação da API Documentação de referência de SDK do JavaScript
Instruções de instalação do SDK npm install @azure/cosmos
Contribuir para o SDK Guia de contribuição para o repo do azure-sdk-for-js
Exemplos Exemplos de código do Node.js
Tutorial de introdução Introdução ao SDK do JavaScript
Tutorial do aplicativo Web Criar um aplicativo web Node.js usando o Azure Cosmos DB
Plataformas de Node.js com suporte atual Versões LTS do Node.js

Notas de versão

O histórico de versões é mantido no repositório azure-sdk-for-js. Confira a lista detalhada de versões no arquivo changelog.

Guia de migração para alterações de falhas

Se você estiver em uma versão mais antiga do SDK, é recomendável migrar para a versão 3.0. Esta seção detalha as melhorias que você obteria com essa versão e as correções de bugs feitas na versão 3.0.

Opções aprimoradas de construtor de cliente

As opções do construtor foram simplificadas:

  • masterKey foi renomeado como chave e movido para o nível superior
  • As propriedades anteriormente em options.auth foram movidas para o nível superior
// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

API simplificada do QueryIterator

Na v2, havia várias maneiras de iterar ou recuperar resultados de uma consulta. Tentamos simplificar a API da v3 e remover APIs semelhantes ou duplicadas:

  • Remover iterator.next() e iterator.current(). Usar fetchNext() para obter páginas de resultados.
  • Remover iterator.forEach(). Em vez disso, usar iteradores assíncronos.
  • iterator.executeNext() renomeado para iterator.fetchNext().
  • iterator.toArray() renomeado para iterator.fetchAll().
  • As páginas agora são objetos de resposta adequados, em vez de objetos JS simples.
  • const container = client.database(dbId).container(containerId)
// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

Os contêineres fixos agora estão particionados.

O serviço do Azure Cosmos DB agora é compatível com chaves de partição em todos os contêineres, incluindo aqueles que foram criados anteriormente como contêineres fixos. O SDK v3 é atualizado para a versão mais recente da API que implementa essa alteração, mas está sem interrupção. Se você não fornecer uma chave de partição para operações, usaremos como padrão uma chave do sistema que funcione com todos os seus contêineres e documentos existentes.

Upsert removido dos procedimentos armazenados

Anteriormente, upsert era permitido em coleções não particionadas. Mas, com a atualização de versão da API, todas as coleções são particionadas e nós o removemos por completo.

A leitura de itens não lançará um erro 404

const container = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

Gravação padrão de várias regiões

Por padrão, o SDK agora gravará em várias regiões em que a configuração do Azure Cosmos DB for compatível. Esse era um comportamento opcional anteriormente.

Objetos de erro apropriados

As solicitações com falha agora geram erro ou subclasses de erro apropriados. Anteriormente, eles lançavam objetos JS simples.

Novos recursos

Solicitações canceláveis pelo usuário

A mudança para efetuar fetch internamente nos permite usar a API AbortController do navegador para compatibilidade com operações canceláveis pelo usuário. No caso de operações em que várias solicitações estão potencialmente em andamento (como consultas entre partições), todas as solicitações da operação serão canceladas. Os usuários de navegadores modernos já terão AbortController. Os usuários de node.js precisarão usar uma biblioteca polyfill.

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

Definir a taxa de transferência como parte da operação de criação de BD/contêiner

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

A geração de tokens de cabeçalho foi dividida em uma nova biblioteca, @azure/cosmos-sign. Qualquer pessoa que chamar a API REST do Azure Cosmos DB diretamente poderá usar isso para assinar cabeçalhos utilizando o mesmo código que chamamos dentro de @azure/cosmos.

UUID para IDs geradas

A v2 tinha código personalizado para gerar IDs de item. Mudamos para a biblioteca de comunidade uuid, bem conhecida e mantida.

Cadeias de conexão

Agora é possível passar uma cadeia de conexão copiada do portal do Azure:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

Experiência de navegador aprimorada

Embora fosse possível usar o SDK v2 no navegador, não era uma experiência ideal. Era necessário o Polyfill em várias bibliotecas internas do Node.js e usar um empacotador, como webpack ou Parcel. O SDK da v3 torna a experiência imediata e muito melhor para os usuários do navegador.

  • Substituir os elementos internos da solicitação por fetch (nº 245)
  • Remover uso do buffer (nº 330)
  • Remover o uso interno do nó em favor de pacotes/APIs universais (nº 328)
  • Mudar para node-abort-controller (nº 294)

Correções de bug

  • Corrigir leitura de oferta e trazer de volta testes de oferta (nº 224)
  • Corrigir EnableEndpointDiscovery (nº 207)
  • Corrigir RUs ausente nos resultados paginados (nº 360)
  • Expandir tipo de parâmetro de consulta SQL (nº 346)
  • Adicionar ttl a ItemDefinition (nº 341)
  • Corrigir métricas de consulta de CP (nº 311)
  • Adicionar activityId a FeedResponse (nº 293)
  • Mudar _ts type de cadeia de caracteres para número (nº 252)(nº 295)
  • Corrigir agregação de solicitação de encargo (nº 289)
  • Permitir chaves de partição com cadeia de caracteres em branco (nº 277)
  • Adicionar cadeia de caracteres ao tipo de consulta de conflito (nº 237)
  • Adicionar uniqueKeyPolicy ao contêiner (nº 234)

Sistemas de engenharia

Nem sempre são as alterações mais visíveis, mas ajudam nossa equipe a fornecer um código melhor, mais rápido.

  • Usar rollup nas compilações de produção (nº 104)
  • Atualizar para TypeScript 3.5 (nº 327)
  • Converter em referências de projeto TS. Extrair pasta de teste (nº 270)
  • Habilitar noUnusedLocals e noUnusedParameters (nº 275)
  • YAML do Azure Pipelines para compilações de CI (nº 298)

Datas de lançamento e desativação

A Microsoft notifica pelo menos 12 meses antes de desativar um SDK, a fim de realizar uma transição tranquila para uma versão mais recente/com suporte. Os novos recursos, funcionalidades e otimizações são adicionados apenas ao SDK atual. Portanto, é recomendável atualizar sempre que possível para a versão do SDK mais recente. Leia a Política de Suporte da Microsoft para SDKs para obter mais detalhes.

Versão Data de lançamento Data de desativação
v3 28 de junho de 2019 ---
v2 24 de setembro de 2018 24 de setembro de 2021
v1 8 de abril de 2015 30 de agosto de 2020

Perguntas frequentes

Como serei notificado sobre a desativação do SDK?

A Microsoft enviará uma notificação com 12 meses de antecedência informando sobre o fim do suporte para o SDK a ser desativado, para facilitar uma transição suave para um SDK com suporte. Você será notificado por meio de vários canais de comunicação: o portal do Azure, as atualizações do Azure e a comunicação direta com os administradores de serviços atribuídos.

Durante o período de 12 meses, posso criar aplicativos usando um SDK do Azure Cosmos DB que será desativado?

Sim, durante o período de notificação de 12 meses, você poderá criar, implantar e modificar aplicativos usando o SDK do Azure Cosmos DB que será desativado. Recomendamos que você migre para uma versão do SDK do Azure Cosmos DB mais recente com suporte durante o período de notificação de 12 meses, conforme o necessário.

Após a data de desativação, o que acontece com os aplicativos que usam o SDK do Azure Cosmos DB sem suporte?

Após a data de desativação, o Azure Cosmos DB não fará mais correções de bug, não adicionará novos recursos nem dará suporte às versões desativadas do SDK. Se você preferir não fazer a atualização, as solicitações enviadas das versões desativadas do SDK continuarão sendo atendidas pelo serviço Azure Cosmos DB.

Quais versões do SDK terão os recursos e as atualizações mais recentes?

Os novos recursos e atualizações serão adicionados somente à última versão secundária da última versão principal do SDK com suporte. Recomendamos que você sempre use a última versão para aproveitar os novos recursos, os aprimoramentos de desempenho e as correções de bug. Se você estiver usando uma versão antiga e não desativada do SDK, suas solicitações para o Azure Cosmos DB continuarão a funcionar, mas você não terá acesso a nenhuma funcionalidade nova.

O que fazer se eu não conseguir atualizar meu aplicativo antes da data limite?

Recomendamos atualizar o mais rápido possível para o SDK mais recente. Depois que um SDK for marcado para desativação, você terá 12 meses para atualizar seu aplicativo. Se você não conseguir fazer a atualização até data de desativação, as solicitações enviadas das versões desativadas do SDK continuarão a ser atendidas pelo Azure Cosmos DB, para que os aplicativos em execução continuem a funcionar. No entanto, o Azure Cosmos DB não fará mais correções de bug, não adicionará novos recursos nem dará suporte às versões desativadas do SDK.

Se você tem um plano de suporte e precisa de suporte técnico, entre em contato conosco abrindo um tíquete de suporte.

Como solicitar que recursos sejam adicionados a um SDK ou ao conector?

Os novos recursos nem sempre são adicionados a cada SDK ou conector imediatamente. Se não houver suporte para um recurso que você gostaria de adicionar, adicione comentários ao nosso fórum da comunidade.

Confira também

Para saber mais sobre o Azure Cosmos DB, veja a página do serviço Microsoft Azure Cosmos DB.