Azure Cosmos DB Node.js SDK para API para NoSQL: Notas de lançamento e recursos

Notas de lançamento

O histórico de lançamentos é mantido no repositório azure-sdk-for-js; para uma lista detalhada de lançamentos, consulte o ficheiro 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 suporta chaves de partição em todos os contentores, incluindo aqueles que foram anteriormente criados como contentores 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, o padrão será 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 escreve em várias regiões por defeito, se a sua configuração do Azure Cosmos DB o suportar. 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 precisam 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 diretamente a API Azure Cosmos DB REST pode usar isto para assinar cabeçalhos usando o mesmo código que chamamos dentro de @azure/cosmos.

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 ligaçã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 for CI builds (#298)

Datas de Lançamento e Aposentadoria

Microsoft fornece notificação pelo menos 12 meses antes de retirar 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 Suporte da Microsoft para SDKs para mais detalhes.

FAQ

Como vou ser notificado do SDK descontinuado?

A Microsoft fornecerá um aviso prévio de 12 meses antes do fim do suporte do SDK que está a ser retirado para facilitar uma transição suave para um SDK suportado. Notificaremos através de vários canais de comunicação: o portal Azure, atualizações do Azure e comunicação direta com os administradores de serviço atribuídos.

Posso criar candidaturas usando um SDK de Azure Cosmos DB to-bereformado durante o período de 12 meses?

Sim, poderá criar, implementar e modificar aplicações usando o SDK Azure Cosmos DB to-be- retirado durante o período de aviso prévio de 12 meses. Recomendamos que migre para uma versão mais recente suportada do Azure Cosmos DB SDK durante o período de aviso prévio de 12 meses, conforme apropriado.

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

Após a data de reforma, o Azure Cosmos DB deixará de corrigir bugs, adicionar novas funcionalidades nem fornecer suporte às versões do SDK retiradas. Se preferir não atualizar, os pedidos enviados pelas versões desativadas do SDK continuarão a ser servidos pelo serviço Azure Cosmos DB.

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 estiveres a usar uma versão antiga e não desativada do SDK, os teus pedidos para o Azure Cosmos DB continuarão a funcionar, mas não terás acesso a novas funcionalidades.

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 reforma, os pedidos enviados das versões desativadas do SDK continuarão a ser servidos pelo Azure Cosmos DB, pelo que as suas aplicações em execução continuarão a funcionar. Mas o Azure Cosmos DB já não fará correções de bugs, adiciona novas funcionalidades nem fornece suporte às versões do SDK retiradas.

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 Azure Cosmos DB, consulte a página de serviço Microsoft Azure Cosmos DB.