Quickstart: Construa uma app Java para gerir a Azure Cosmos DB para dados NoSQL

APLICA-SE A: NoSQL

Neste quickstart, você cria e gere uma conta Azure Cosmos DB para NoSQL a partir do portal do Azure, e usando uma aplicação Java clonada do GitHub. Em primeiro lugar, cria uma conta Azure Cosmos para NoSQL utilizando o portal do Azure, ou sem um cartão de crédito ou uma subscrição Azure, pode configurar uma conta DB try Azure Cosmos gratuita, depois criar uma aplicação Java usando o SQL Java SDK e, em seguida, adicionar recursos à sua conta DB Azure Cosmos utilizando a aplicação Java. Azure Cosmos DB é um serviço de base de dados multi-modelo que permite criar e consultar rapidamente documentos, tabelas, valor-chave e bases de dados de gráficos com capacidades de distribuição global e escala horizontal.

Importante

Este quickstart é apenas para Azure Cosmos DB Java SDK v4. Por favor, veja as notas de lançamento do Azure Cosmos DB Java SDK v4, repositório de Maven, dicas de desempenho V4 da Azure Cosmos DB Java SDK para obter mais informações. Se está a utilizar uma versão mais antiga do que v4, consulte o guia Migrae para Azure Cosmos DB Java SDK v4 para ajudar a atualizar para v4.

Pré-requisitos

Notas introdutórias

A estrutura de uma conta DB Azure Cosmos. Independentemente da API ou da linguagem de programação, uma conta DB do Azure Cosmos contém zero ou mais bases de dados, uma base de dados (DB) contém zero ou mais contentores, e um recipiente contém zero ou mais itens, como mostra o diagrama abaixo:

Entidades de conta Azure Cosmos DB

Pode ler mais sobre bases de dados, contentores e itens aqui. Algumas propriedades importantes são definidas ao nível do recipiente, entre elas a chave de produção e partição.

A produção prevista é medida em Unidades de Pedido (RUs) que têm um preço monetário e constituem um fator determinante substancial no custo de exploração da conta. A produção a provisionada pode ser selecionada em granularidade por contentor ou granularidade por base de dados, no entanto, normalmente é preferível a especificação de produção ao nível do contentor. Pode ler mais sobre o fornecimento de produção aqui.

À medida que os itens são inseridos num recipiente DB Azure Cosmos, a base de dados cresce horizontalmente adicionando mais armazenamento e cálculo para lidar com pedidos. A capacidade de armazenamento e computação são adicionadas em unidades discretas conhecidas como divisórias, e deve escolher um campo nos seus documentos para ser a chave de partição que mapeia cada documento para uma partição. A forma como as divisórias são geridas é que cada partição é atribuída a uma fatia aproximadamente igual fora da gama de valores-chave de partição; por isso, é aconselhável escolher uma chave de partição que seja relativamente aleatória ou distribuída uniformemente. Caso contrário, algumas divisórias verão substancialmente mais pedidos (partição quente) enquanto outras divisórias vêem substancialmente menos pedidos (partição fria), e isso deve ser evitado. Pode aprender mais sobre divisórias aqui.

Criar uma conta de base de dados

Antes de poder criar uma base de dados de documentos, precisa de criar uma conta API para NoSQL com a Azure Cosmos DB.

  1. A partir do menu portal do Azure ou da página Inicial, selecione Criar um recurso.

  2. Na página Nova , procure e selecione Azure Cosmos DB.

  3. Na página de opção Select API , selecione a opção Criar dentro da secção NoSQL - Recomendar . A Azure Cosmos DB fornece cinco APIs: NoSQL e MongoDB para dados de documentos, Gremlin para dados gráficos, Azure Table e Cassandra. De momento, deve criar uma conta separada para cada API. Saiba mais sobre a API para NoSQL.

  4. Na página De Conta DB Create Azure Cosmos , insira as definições básicas para a nova conta DB Azure Cosmos.

    Definição Valor Descrição
    Subscrição Nome da subscrição Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos DB.
    Grupo de Recursos Nome do grupo de recursos Selecione um grupo de recursos ou selecione Criar novo e, em seguida, introduza um nome exclusivo para o novo grupo de recursos.
    Nome da Conta Um nome exclusivo Insira um nome para identificar a sua conta DB Azure Cosmos. Uma vez que documents.azure.com é anexado ao nome que indicar para criar o URI, utilize um nome exclusivo.

    O nome só pode conter letras minúsculas, números e o caráter de hífen (-). Deve ter entre 3 a 44 caracteres de comprimento.
    Localização A região mais próxima dos seus utilizadores Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.
    Modo de capacidade Produção provisida ou sem servidor Selecione A produção provisida para criar uma conta no modo de produção previsto. Selecione Serverless para criar uma conta no modo sem servidor .
    Aplicar desconto de nível gratuito Azure Cosmos DB Aplicar ou não aplicar Com o nível livre de DB Azure Cosmos, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente numa conta. Saiba mais sobre o free tier.

    Nota

    Pode ter até uma conta DB Azure Cosmos de nível gratuito por subscrição Azure e deve optar pela criação da conta. Se não vir a opção de aplicar o desconto de nível livre, isto significa que outra conta na subscrição já foi ativada com nível gratuito.

    A página de nova conta do Azure Cosmos DB

  5. No separador Distribuição Global , configuure os seguintes detalhes. Pode deixar os valores predefinidos para este arranque rápido:

    Definição Valor Descrição
    Redundância Geográfica Desativar Ativar ou desativar a distribuição global na sua conta, emparelhando a sua região com uma região de pares. Pode adicionar mais regiões à sua conta mais tarde.
    Escritas de várias regiões Desativar A capacidade de escrita multi-região permite-lhe tirar partido da produção prevista para as suas bases de dados e contentores em todo o mundo.

    Nota

    As seguintes opções não estão disponíveis se selecionar Serverless como o modo Capacidade:

    • Aplicar Desconto de Escalão Gratuito
    • Georredundância
    • Escritas de várias regiões
  6. Opcionalmente, pode configurar mais detalhes nos seguintes separadores:

  7. Selecione Rever + criar.

  8. Reveja as definições da conta e, em seguida, selecione Criar. A criação da conta demora alguns minutos. Aguarde até que a página do portal apresente A implementação está concluída.

    O painel Notificações do portal do Azure

  9. Selecione Ir para recurso para aceder à página da conta do Azure Cosmos DB.

    A página da conta do Azure Cosmos DB

Adicionar um contentor

Pode agora utilizar a ferramenta Data Explorer na portal do Azure para criar uma base de dados e um recipiente.

  1. Selecione Data Explorer>Novo Recipiente.

    A área do Recipiente Adicionar é apresentada na extrema direita, podendo ser necessário deslocar-se para a frente para o ver.

    O Data Explorer no portal do Azure, painel Adicionar Contentor

  2. Na página do recipiente Adicionar , introduza as definições para o novo recipiente.

    Definição Valor sugerido Descrição
    ID da Base de Dados ToDoList Designe a nova base de dados como Tarefas. Os nomes da base de dados devem conter de 1 a 255 caracteres, e não podem conter /, \\, #, ?, ou um espaço de fuga. Verifique a produção de partilha através da opção de contentores , permite-lhe partilhar o produto previsto na base de dados em todos os contentores dentro da base de dados. Esta opção também ajuda na poupança de custos.
    Produção de base de dados Pode providenciar autoescala ou produção manual . A produção manual permite-lhe escalar RU/s si mesmo, enquanto que a produção de escala automática permite que o sistema dimensione RU/s com base na utilização. Selecione Manual para este exemplo.

    Deixe a produção a 400 unidades de pedido por segundo (RU/s). Se quiser reduzir a latência, pode aumentar a produção mais tarde, estimando o RU/s necessário com a calculadora de capacidade.

    Nota: Esta definição não está disponível ao criar um novo recipiente numa conta sem servidor.
    ID do Contentor Itens Insira itens como o nome do seu novo recipiente. Os IDs dos contentores têm os mesmos requisitos em termos de carateres que os nomes das bases de dados.
    Chave de partição /categoria A amostra descrita neste artigo utiliza /categoria como chave de partição.

    Não adicione teclas Únicas ou ligue a loja Analítica para este exemplo. As teclas únicas permitem adicionar uma camada de integridade dos dados à base de dados, garantindo a singularidade de um ou mais valores por chave de partição. Para mais informações, consulte as chaves únicas em Azure Cosmos DB.A loja analítica é utilizada para permitir análises em larga escala contra dados operacionais sem qualquer impacto nas suas cargas de trabalho transacionais.

    Selecione OK. O Data Explorer mostra a base de dados e o contentor novos.

Adicionar dados de exemplo

Pode agora adicionar dados ao seu novo recipiente utilizando Data Explorer.

  1. A partir do Data Explorer, expanda a base de dados Tarefas, expanda o recipiente Itens. Selecione Itens e, em seguida, selecione Novo Item.

    Criar documentos novos no Data Explorer no portal do Azure

  2. Adicione agora um documento ao recipiente com a seguinte estrutura.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Depois de adicionar o json ao separador Documentos , selecione Save.

    Copie os dados json e selecione Guardar em Data Explorer no portal do Azure

  4. Crie e guarde mais um documento onde insere um valor exclusivo para a propriedade id e altere as outras propriedades conforme necessário. Agora, os documentos podem ter qualquer estrutura que queira criar, uma vez que o Azure Cosmos DB não impõe qualquer esquema aos seus dados.

Consultar os seus dados

Pode utilizar consultas em Data Explorer para recuperar e filtrar os seus dados.

  1. No topo do separador Itens em Data Explorer, reveja a consulta SELECT * FROM cpor defeito . Esta consulta recupera e exibe todos os documentos do recipiente encomendado por ID.

    Consulta padrão em Data Explorer é SELECT * FROM c

  2. Para alterar a consulta, selecione Editar Filtro, substitua a consulta predefinida com ORDER BY c._ts DESC, e, em seguida, selecione Apply Filter.

    Altere a consulta predefinida ao adicionar ORDER BY c._ts DESC e clique em Aplicar Filtro

    A consulta modificada exibe os documentos em ordem descendente com base no seu carimbo de tempo, pelo que agora o seu segundo documento está listado primeiro.

    Alteração da consulta para ORDER BY c._ts DESC e clicar em Aplicar Filtro

Se estiver familiarizado com a sintaxe SQL, pode introduzir quaisquer consultas SQL suportadas na caixa predicado de consulta. Também pode usar Data Explorer para criar procedimentos armazenados, UDFs e gatilhos para lógica de negócio do lado do servidor.

Data Explorer proporciona fácil acesso portal do Azure a todas as funcionalidades de acesso a dados programáticos incorporadas disponíveis nas APIs. Também usa o portal para escalar a produção, obter chaves e cordas de conexão, e rever métricas e SLAs para a sua conta Azure Cosmos DB.

Clonar a aplicação de exemplo

Agora, vamos trabalhar com código. Vamos clonar uma aplicação API para NoSQL do GitHub, definir a cadeia de ligação e executá-la. Vai ver como é fácil trabalhar com dados programaticamente.

Execute o seguinte comando para clonar o repositório de exemplo. Este comando cria uma cópia da aplicação de exemplo no seu computador.

git clone https://github.com/Azure-Samples/azure-cosmos-java-getting-started.git

Rever o código

Este passo é opcional. Se estiver interessado em aprender de que forma os recursos da base de dados são criados no código, pode consultar os seguintes fragmentos. Caso contrário, pode avançar para Executar a aplicação.

Gerir recursos de base de dados utilizando a API sincronizada (sincronizada)

  • CosmosClient inicialização. O CosmosClient fornece representação lógica do lado do cliente para o serviço de base de dados DB Azure Cosmos. Este cliente é utilizado para configurar e executar pedidos no serviço.

    client = new CosmosClientBuilder()
        .endpoint(AccountSettings.HOST)
        .key(AccountSettings.MASTER_KEY)
        //  Setting the preferred location to Cosmos DB Account region
        //  West US is just an example. User should set preferred location to the Cosmos DB region closest to the application
        .preferredRegions(Collections.singletonList("West US"))
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildClient();
    
    
  • CosmosDatabase criação.

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
  • CosmosContainer criação.

    CosmosContainerProperties containerProperties =
        new CosmosContainerProperties(containerName, "/lastName");
    
    //  Create container with 400 RU/s
    CosmosContainerResponse cosmosContainerResponse =
        database.createContainerIfNotExists(containerProperties, ThroughputProperties.createManualThroughput(400));
    container = database.getContainer(cosmosContainerResponse.getProperties().getId());
    
  • Criação de artigo utilizando o createItem método.

    //  Create item using container that we created using sync client
    
    //  Use lastName as partitionKey for cosmos item
    //  Using appropriate partition key improves the performance of database operations
    CosmosItemRequestOptions cosmosItemRequestOptions = new CosmosItemRequestOptions();
    CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()), cosmosItemRequestOptions);
    
  • As leituras de pontos são realizadas utilizando o readItem método.

    try {
        CosmosItemResponse<Family> item = container.readItem(family.getId(), new PartitionKey(family.getLastName()), Family.class);
        double requestCharge = item.getRequestCharge();
        Duration requestLatency = item.getDuration();
        logger.info("Item successfully read with id {} with a charge of {} and within duration {}",
            item.getItem().getId(), requestCharge, requestLatency);
    } catch (CosmosException e) {
        logger.error("Read Item failed with", e);
    }
    
  • As consultas SQL sobre JSON são realizadas usando o queryItems método.

    // Set some common query options
    CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions();
    //queryOptions.setEnableCrossPartitionQuery(true); //No longer necessary in SDK v4
    //  Set query metrics enabled to get metrics around query executions
    queryOptions.setQueryMetricsEnabled(true);
    
    CosmosPagedIterable<Family> familiesPagedIterable = container.queryItems(
        "SELECT * FROM Family WHERE Family.lastName IN ('Andersen', 'Wakefield', 'Johnson')", queryOptions, Family.class);
    
    familiesPagedIterable.iterableByPage(10).forEach(cosmosItemPropertiesFeedResponse -> {
        logger.info("Got a page of query result with {} items(s) and request charge of {}",
                cosmosItemPropertiesFeedResponse.getResults().size(), cosmosItemPropertiesFeedResponse.getRequestCharge());
    
        logger.info("Item Ids {}", cosmosItemPropertiesFeedResponse
            .getResults()
            .stream()
            .map(Family::getId)
            .collect(Collectors.toList()));
    });
    

Executar a aplicação

Agora, regresse ao portal do Azure para obter as informações da cadeia de ligação e inicie a aplicação com as suas informações de ponto final. Isto permite à aplicação comunicar com a base de dados alojada.

  1. Na janela de terminal do git, cd para a pasta de código de exemplo.

    cd azure-cosmos-java-getting-started
    
  2. Na janela de terminal do git, utilize o seguinte comando para instalar os pacotes Java necessários.

    mvn package
    
  3. Na janela do terminal de git, utilize o seguinte comando para iniciar a aplicação Java (substitua o SYNCASYNCMODE com sync ou async dependendo do código de amostra que pretende executar, substitua YOUR_COSMOS_DB_HOSTNAME pelo valor URI citado do portal e substitua YOUR_COSMOS_DB_MASTER_KEY pela chave primária citada do portal)

    mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY
    
    

    A janela do terminal apresenta uma notificação que a base de dados FamilyDB tinha criado.

  4. A aplicação cria base de dados com nome AzureSampleFamilyDB

  5. A aplicação cria recipiente com nome FamilyContainer

  6. A aplicação executará leituras de ponto usando IDs de objeto e valor chave de partição (que é o último Nome na nossa amostra).

  7. A aplicação irá consultar itens para recuperar todas as famílias com apelido em ('Andersen', 'Wakefield', 'Johnson')

  8. A aplicação não elimina os recursos criados. Mude novamente para o portal para limpar os recursos. da sua conta, para que não incorra em custos.

Rever os SLAs no portal do Azure

O portal do Azure monitoriza a sua conta DB Azure Cosmos, armazenamento, disponibilidade, latência e consistência. Gráficos para métricas associadas a um Acordo de Nível de Serviço DB da Azure Cosmos (SLA) mostram o valor SLA em comparação com o desempenho real. Este conjunto de métricas torna transparente a monitorização dos seus SLAs.

Para rever métricas e SLAs:

  1. Selecione Métricas no menu de navegação da sua conta Azure Cosmos DB.

  2. Selecione um separador como a Latência e selecione um prazo à direita. Compare as linhas Atual e SLA nas tabelas.

    Conjunto de métricas do Azure Cosmos DB

  3. Reveja as métricas nas outras abas.

Limpar os recursos

Quando terminar a sua app e a conta DB da Azure Cosmos, pode eliminar os recursos Azure que criou para não incorrer em mais encargos. Para eliminar os recursos:

  1. Na barra de pesquisa portal do Azure, procure e selecione grupos de Recursos.

  2. Na lista, selecione o grupo de recursos que criou para este arranque rápido.

    Selecione o grupo de recursos para eliminar

  3. Na página de visão geral do grupo de recursos, selecione Eliminar o grupo de recursos.

    Eliminar o grupo de recursos

  4. Na janela seguinte, insira o nome do grupo de recursos para eliminar e, em seguida, selecione Delete.

Passos seguintes

Neste quickstart, aprendeu a criar um Azure Cosmos DB para conta NoSQL, criar uma base de dados de documentos e um contentor usando o Data Explorer, e executar uma aplicação Java para fazer a mesma coisa programáticamente. Pode agora importar dados adicionais na sua conta DB Azure Cosmos.

A tentar planear a capacidade de uma migração para a Azure Cosmos DB? Pode utilizar informações sobre o seu cluster de base de dados existente para o planeamento de capacidades.