Adicionar um código JavaScript para trabalhar com o Cosmos DB

A Microsoft fornece APIs que permitem que você acesse o Cosmos DB por meio do código do aplicativo. Nos bastidores, essas APIs são wrappers em torno de uma série de chamadas REST que enviam e recebem solicitações HTTP bidirecionalmente no serviço do Cosmos DB. Essas APIs estão disponíveis para uma variedade de linguagens de programação, incluindo JavaScript.

Nesta unidade, você aprenderá a usar a API JavaScript para Cosmos DB para consultar e gerenciar documentos e contêineres.

Instalar a API JavaScript para Cosmos DB

A API JavaScript para Cosmos DB é fornecida em um pacote chamado @azure/cosmos . Instale esse pacote usando o npm (Gerenciador de Pacotes do Node).

Conectar-se a uma conta do Cosmos DB

A API JavaScript expõe uma classe chamada CosmosClient que funciona como o ponto de acesso para o Cosmos DB. Use um objeto CosmosClient para obter um identificador em bancos de dados e contêineres. Quando você tem acesso a um contêiner, pode consultar e manipular documentos.

Use o construtor para criar um objeto CosmosClient. O construtor usa uma cadeia de conexão do Cosmos DB como parâmetro. A cadeia de conexão contém o endereço de sua conta do Cosmos DB e a chave de segurança necessária para acessar a conta. Obtenha a cadeia de conexão para uma conta usando o painel do Cosmos DB no Visual Studio Code. Clique com o botão direito do mouse na conta e selecione Copiar Cadeia de Conexão .

Captura de tela do painel do Cosmos DB no Visual Studio Code. O usuário está copiando a cadeia de conexão da conta do Cosmos DB para a área de transferência.

No aplicativo JavaScript use o seguinte código para se conectar a uma conta do Cosmos DB usando a cadeia de conexão:

var cosmos = require("@azure/cosmos");

const client = new cosmos.CosmosClient("Connection string goes here");

Use o objeto client para recuperar, criar, atualizar e excluir documentos em um contêiner. Todas essas operações exigem uma referência ao contêiner. Obtenha essa referência por meio da função database de um objeto CosmosClient, da seguinte maneira:

const databaseid = "Your database name";
const containerid = "Your container name";
const containerref = client.database(databaseid).container(containerid);
const containerdata = containerref.items;

Recuperar documentos

O Cosmos DB fornece duas maneiras de recuperar documentos. Você pode executar uma consulta ou efetuar fetch de um documento diretamente usando a ID dele.

Consultar documentos

A primeira técnica é executar uma consulta. Use a função query de um contêiner e especifique uma instrução SELECT que identifica os documentos a serem buscados.

Esse código percorre a hierarquia dos objetos do Cosmos DB descritos no módulo 2. O objeto containerdata fornece acesso aos documentos (itens) no contêiner.

O snippet de código a seguir mostra como executar uma consulta em um contêiner. Este exemplo localiza os documentos para todos os alunos que têm um ano acadêmico especificado:

var academicyear = ...;
...
const studentquery = {
    query: "SELECT s.id, s.Name.Forename, s.Name.Lastname \
            FROM students s  \
            WHERE s.AcademicYear = @year",
    parameters: [
        {
            name: "@year",
            value: academicyear
        }
    ]
};

const { resources } = await containerdata.query(studentquery).fetchAll();
for (let queryResult of resources) {
    let resultString = JSON.stringify(queryResult);
    process.stdout.write(`\nQuery returned ${resultString}\n`);
}

Observação

Muitas das funções na API JavaScript para Cosmos DB operam de maneira assíncrona. Use objetos JavaScript Promise para agendar tarefas quando uma função é concluída com êxito e para tratar exceções. Use também o operador JavaScript await (como mostrado no código acima) para pausar a execução até que a função conclua o trabalho.

Neste exemplo, o texto da consulta é encapsulado na variável studentquery . A consulta é parametrizada; essa é uma boa prática para evitar possíveis ataques de injeção de SQL. A função query da variável containerdata executa a consulta e retorna um conjunto de resultados. Por padrão, uma consulta do Cosmos DB só recuperará os primeiros 100 documentos. Neste exemplo, a função fetchAll é usada para efetuar fetch de cada documento correspondente. O conjunto de resultados é retornado como a propriedade resources de um objeto. O loop for itera pelos documentos no conjunto de resultados e exibe o conteúdo de cada documento como uma cadeia de caracteres JSON.

Efetuar fetch de um documento pela ID

Se você sabe a ID de um documento, a maneira mais rápida de recuperá-lo é fazendo a leitura diretamente no contêiner. Use a função read para fazer isso. Os parâmetros para read são a ID e a chave de partição do documento. O exemplo a seguir efetua fetch do documento de um aluno considerando a ID do aluno e o ano acadêmico (a chave de partição no cenário de exemplo). O valor retornado pela função read é um objeto que contém uma cópia do documento na propriedade resource e um código de status HTTP.

O código de status indica se a leitura foi bem-sucedida; os códigos no intervalo 200-299 indicam êxito e outros valores indicam uma falha. Se houver uma falha, a função read também gerará uma exceção. Para tratar a falha manualmente, você deverá examinar o código de status HTTP em um manipulador de exceção. Esse processo não está incluído na amostra abaixo:

var id = ...;
var year = ...;
...
const { resource, statusCode } = await containerref.item(id, year).read();
process.stdout.write(`\nDetails: ${JSON.stringify(resource)}\n`);

Criar, atualizar e excluir documentos

Para adicionar um novo documento a um contêiner, use a função create do contêiner e forneça o documento como o parâmetro. Se a operação de criação for bem-sucedida, como a função read , ela retornará um objeto que contém uma cópia do novo documento e o código de status HTTP da solicitação:

var student = {
    id: "SU999",
    AcademicYear: "2019",
    Name: {
        Forename: "...",
        Lastname: "..."
    },
    CourseGrades: []
};

const { item, statusCode } = await containerdata.create(student)

Use as funções upsert ou replace para atualizar um documento. A rigor, o Cosmos DB não faz realmente uma operação de atualização. Em vez disso, ele exclui um documento e o substitui por um novo que tenha a mesma ID. Você precisará fornecer o documento inteiro como um parâmetro. O código abaixo mostra um exemplo:

var updatedstudent = {
    id: "SU999",
    ...
};

const { item, statusCode } = await containerdata.upsert(updatedstudent);

A sintaxe para a função replace é semelhante. A principal diferença entre upsert e replace diz respeito ao caso em que um documento com a ID especificada ainda não existe no contêiner. Nessa situação, a função replace gerará uma exceção, mas upsert só inserirá o novo documento.

Use a função delete para remover um documento. Assim como ocorre com read , você precisará fornecer a ID e a chave de partição do documento como parâmetros, conforme mostrado no seguinte código:

var student = {
    id: "SU999",
    AcademicYear: "2019",
    ...
};

const { item, statusCode } = await containerref.item(student.id, student.AcademicYear).delete();

Se não houver nenhum documento com uma ID e uma chave de partição correspondentes, a função delete gerará uma exceção.