SDK do Node.js do Azure Cosmos DB para API para NoSQL: Notas de versão e recursos

APLICA-SE A: NoSQL

• SDK do .NET v3
• SDK do .NET v2
• SDK do .NET Core v2
• SDK Feed de Alterações .NET v2
• Node.js
• Java SDK v4
• Sincronizar Java SDK v2
• SDK Java assíncrono v2
• Spring Data v2
• Spring Data v3
• Dados do Spring v5
• Python
• Ir
• REST
• Fornecedor de Recursos REST
• SQL
• Executor em massa - .NET v2
• Executor em massa - Java

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

Notas de versão

O histórico de versões é mantido no repositório azure-sdk-for-js, para obter uma lista detalhada das versões, consulte o arquivo changelog.

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

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 esta versão e as correções de bugs feitas na versão 3.0.

Opções melhoradas do construtor do cliente

As opções do construtor foram simplificadas:

• masterKey foi renomeado key 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 de iterador de consulta simplificada

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

• Remova iterator.next() e iterator.current(). Use fetchNext() para obter páginas de resultados.
• Remova iterator.forEach(). Em vez disso, use iteradores assíncronos.
• iterator.executeNext() renomeado para iterator.fetchNext()
• iterator.toArray() renomeado para iterator.fetchAll()
• As páginas agora são objetos Response apropriados 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 contentores fixos estão agora particionados

O serviço Azure Cosmos DB agora dá suporte a chaves de partição em todos os contêineres, incluindo aqueles que foram criados anteriormente como contêineres fixos. O SDK v3 atualiza para a versão mais recente da API que implementa essa alteração, mas não está quebrando. 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 para procedimentos armazenados

Anteriormente, o upsert era permitido para coleções não particionadas, mas com a atualização da versão da API, todas as coleções são particionadas, então removemos completamente.

As leituras de itens não serão lançadas no 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ções padrão em várias regiões

O SDK agora gravará em várias regiões por padrão se sua configuração do Azure Cosmos DB oferecer suporte a isso. Anteriormente, tratava-se de um comportamento de opt-in.

Objetos de erro adequados

Solicitações com falha agora lançam o erro adequado ou subclasses de erro. Anteriormente, eles jogavam objetos JS simples.

Novas funcionalidades

Pedidos canceláveis pelo utilizador

A mudança para buscar internamente nos permite usar a API AbortController do navegador para suportar 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 para a operação serão canceladas. Os usuários de navegadores modernos já terão o AbortController. Node.js usuários 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 taxa de transferência como parte da operação de criação db/container

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 token de cabeçalho foi dividida em uma nova biblioteca, @azure/cosmos-sign. Qualquer pessoa que chame a API REST do Azure Cosmos DB diretamente pode usar isso para assinar cabeçalhos usando o mesmo código que chamamos dentro @azure/cosmosdo .

UUID para IDs gerados

v2 tinha código personalizado para gerar IDs de item. Mudamos para a conhecida e mantida biblioteca comunitária uuid.

Cadeias de ligaçã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 melhorada

Embora fosse possível usar o SDK v2 no navegador, não era uma experiência ideal. Você precisava Polyfill várias bibliotecas Node.js integradas e usar um bundler como webpack ou Parcel. O SDK v3 torna a experiência pronta para uso muito melhor para os usuários do navegador.

• Substitua solicitações internas por busca (#245)
• Remover o uso do Buffer (#330)
• Remover o uso interno do nó em favor de pacotes/APIs universais (#328)
• Alternar para node-abort-controller (#294)

Correções de erros

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

Sistemas de engenharia

Nem sempre as alterações mais visíveis, mas ajudam a nossa equipa a enviar um código melhor, mais rápido.

• Usar o pacote cumulativo para compilações de produção (#104)
• Atualização para o TypeScript 3.5 (#327)
• Converter em referências de projeto TS. Extrair pasta de teste (#270)
• Ativar noUnusedLocals e noUnusedParameters (#275)
• Azure Pipelines YAML para compilações de CI (#298)

Datas de Lançamento e Aposentadoria

A Microsoft fornece notificação com pelo menos 12 meses de antecedência da desativação de um SDK para facilitar a transição para uma versão mais recente/suportada. Novos recursos, funcionalidades e otimizações são adicionados apenas ao SDK atual, como tal, é recomendável que você sempre atualize para a versão mais recente do SDK o mais cedo possível. Leia a Política de Suporte da Microsoft para SDKs para obter mais detalhes.

Versão	Data de Lançamento	Data de Extinção
v3	Junho 28, 2019	---
v2	24 de setembro de 2018	24 de setembro de 2021
v1	Abril 08, 2015	30 de agosto de 2020

FAQ

Como vou ser notificado do SDK descontinuado?

A Microsoft dará um aviso com 12 meses de antecedência antes do fim de suporte do SDK descontinuado para permitir uma transição suave para um SDK suportado. Será notificado através de vários canais de comunicação: o portal do Azure, as atualizações do Azure e através de comunicação direta com os administradores atribuídos aos serviços.

Posso criar aplicações com um SDK do Azure Cosmos DB que vai ser descontinuado durante o período de 12 meses?

Sim, poderá criar, implementar e modificar aplicações com o SDK do Azure Cosmos DB que vai ser descontinuado durante o período de aviso de 12 meses. Recomendamos que migre para uma versão suportada mais recente do SDK do Azure Cosmos DB durante o período de aviso de 12 meses, conforme adequado.

Após a data da descontinuação, o que acontece às aplicações que utilizam o SDK do Azure Cosmos DB não suportado?

Após a data de descontinuação, o Azure Cosmos DB deixará de fazer correções de erros, adicionar funcionalidades novas e fornecer suporte às versões descontinuadas do SDK. Se preferir não atualizar, o serviço Azure Cosmos DB continua a servir os pedidos enviados das versões descontinuadas do SDK.

Que versões do SDK terão as mais recentes funcionalidades e atualizações?

As funcionalidades e atualizações novas só vão ser adicionadas à última versão menor da última grande versão do SDK. Recomendamos que utilize sempre a última versão para tirar partido das funcionalidades, das melhorias ao desempenho e das correções de erro mais recentes. Se estiver a utilizar uma versão antiga e ainda em uso do SDK, os pedidos ao Azure Cosmos DB continuarão a funcionar, mas não terá acesso a nenhuma capacidade nova.

O que devo fazer se não conseguir atualizar a minha aplicação antes da data de descontinuação?

Recomendamos que atualize para o último SDK o mais cedo possível. Quando um SDK é marcado para descontinuação, tem 12 meses para atualizar a sua aplicação. Se não conseguir atualizar até à data de descontinuação, os pedidos enviados das versões descontinuadas do SDK continuam a ser servidos pelo Azure Cosmos DB, pelo que as aplicações em execução continuam a funcionar. Contudo, o Azure Cosmos DB deixará de fazer correções de erros, adicionar funcionalidades novas e fornecer suporte às versões descontinuadas do SDK.

Se tiver um plano de suporte e precisar de suporte técnico, preencha um pedido de suporte para nos contactar.

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

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

Consulte também

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