Quickstart: Construa uma app Java para gerir dados da Azure Cosmos DB SQL API

APLICA-SE A: SQL API

Neste quickstart, você cria e gere uma conta API de Azure Cosmos SQL API a partir do portal Azure, e usando uma aplicação Java clonada a partir de GitHub. Primeiro, cria uma conta Azure Cosmos DB SQL API utilizando o portal Azure, depois cria uma aplicação Java utilizando o SQL Java SDK e, em seguida, adicione recursos à sua conta Cosmos DB 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, AzureCosmos DB Java SDK v4 dicas de desempenho , e Azure Cosmos DB Java SDK v4 guia de resolução de problemas 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 de Cosmos DB. Independentemente da API ou da linguagem de programação, uma conta Cosmos DB 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

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 são 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 Cosmos DB, a base de dados cresce horizontalmente adicionando mais armazenamento e cálculo para lidar com pedidos. Armazenamento e capacidade de computação são adicionadas em unidades discretas conhecidas como divisórias, e você 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 a partilha aqui.

Criar uma conta de base de dados

Antes de poder criar uma base de dados de documentos, tem de criar uma conta de API SQL com o Azure Cosmos DB.

  1. A partir do menu do portal 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 DB do Azure Cosmos, selecione Criar.

  4. Na página De Conta DB Create Azure Cosmos, insira as definições básicas para a nova conta 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.
    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 Introduza um nome para identificar a conta do 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.
    API O tipo de conta a criar Selecione Núcleo (SQL) para criar uma base de dados de documentos e consultar com a sintaxe SQL.

    A API determina o tipo de conta a criar. A Azure Cosmos DB fornece cinco APIs: Core (SQL) e MongoDB para dados de documentos, Gremlin para dados gráficos, Tabela Azure e Cassandra. De momento, deve criar uma conta separada para cada API.

    Saiba mais sobre a API SQL.
    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 Provisão 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 Azure Cosmos DB, 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 efeitos deste 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 detalhes adicionais nos seguintes separadores:

    • Networking - Configurar o acesso a partir de uma rede virtual.
    • Política de Backup - Configurar uma política de backup periódica ou contínua.
    • Encriptação - Utilize uma chave gerida pelo serviço ou uma chave gerida pelo cliente.
    • Tags - Tags são pares de nome/valor que lhe permitem categorizar recursos e visualizar faturação consolidada aplicando a mesma etiqueta a múltiplos recursos e grupos de recursos.
  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 no portal 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, pode 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, não podendo 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 os 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 de 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

Agora pode adicionar dados ao seu novo recipiente utilizando o 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 ter adicionado o json ao separador Documentos, selecione Save.

    Copie em dados json e selecione Guardar no Data Explorer no portal 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 no Data Explorer para recuperar e filtrar os seus dados.

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

    Consulta padrão no 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 'Aplicar Filtro'.

    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 utilizar o Data Explorer para criar procedimentos armazenados, UDFs e gatilhos para lógica de negócio do lado do servidor.

O Data Explorer fornece um fácil acesso ao portal 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 da SQL API a partir 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 serviço de base de dados Azure Cosmos fornece representação lógica do lado do cliente. 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 readItem o 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);
    }
    
  • SQL consultas 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 Azure monitoriza a sua conta Cosmos DB, 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 Cosmos DB.

  2. Selecione um separador como 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 apagar os recursos Azure que criou para não incorrer em mais encargos. Para eliminar os recursos:

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

  2. A partir da 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 uma conta API Azure Cosmos SQL, criar uma base de dados de documentos e um contentor utilizando 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.

Import data into Azure Cosmos DB (Importar dados para o Azure Cosmos DB).