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

Notas de lançamento

O histórico de lançamentos é mantido no repositório azure-sdk-for-js para obter uma lista detalhada de versões, consulte o 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 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 é 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 funciona com todos os seus contêineres e documentos existentes.

Upsert removido dos 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 a removemos completamente.

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

O SDK agora gravará em várias regiões por padrão se sua configuração de Azure Cosmos DB der suporte a ela. 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. 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 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 Azure Cosmos DB diretamente pode usá-lo para assinar cabeçalhos usando o mesmo código que chamamos dentro @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 um cadeia de conexão copiado do portal 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

• 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)
• Azure Pipelines YAML para builds de CI (nº 298)

Datas de lançamento e desativação

Microsoft fornece notificação pelo menos 12 meses antes de desativar um SDK para facilitar a transição 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 Suporte da Microsoft para SDKs para obter mais detalhes.

perguntas frequentes

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

Microsoft fornecerá um aviso prévio de 12 meses antes do fim do suporte do SDK de desativação para facilitar uma transição suave para um SDK com suporte. Notificaremos você por meio de vários canais de comunicação: o portal Azure, as atualizações Azure e a comunicação direta com os administradores de serviços atribuídos.

Não posso criar aplicativos usando um SDK de Azure Cosmos DB to-bedesativado durante o período de 12 meses?

Sim, você poderá criar, implantar e modificar aplicativos usando o SDK de Azure Cosmos DB to-bedesativado durante o período de aviso prévio de 12 meses. Recomendamos que você migre para uma versão mais recente com suporte do SDK do Azure Cosmos DB durante o período de aviso prévio de 12 meses, conforme apropriado.

A data de desativação, o que acontece com os aplicativos que usam o SDK Azure Cosmos DB sem suporte?

Após a data de desativação, Azure Cosmos DB não fará mais correções de bugs, adicionará novos recursos ou fornecerá suporte às versões de SDK desativadas. Se você preferir não atualizar, as solicitações enviadas das versões desativadas do SDK continuarão a ser 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 Azure Cosmos DB ainda funcionarão, mas você não terá acesso a novos recursos.

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 atualizar até a data de desativação, as solicitações enviadas das versões desativadas do SDK continuarão a ser atendidas por Azure Cosmos DB, portanto, os aplicativos em execução continuarão funcionando. Mas Azure Cosmos DB não fará mais correções de bugs, adicionará novos recursos ou fornecerá suporte às versões de SDK desativadas.

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.

Consulte também

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