Início Rápido: Criar um aplicativo Java usando a conta de API de SQL do Azure Cosmos DBQuickstart: Build a Java application using Azure Cosmos DB SQL API account

Este início rápido mostra como criar e gerenciar recursos de uma conta da API de SQL do Azure Cosmos DB usando um aplicativo Java.This quickstart shows how to create and manage resources of an Azure Cosmos DB SQL API account by using a Java application. Primeiro, crie uma conta da API de SQL do Azure Cosmos DB usando o portal do Azure; crie um aplicativo Java usando o SDK do Java para SQL e adicione recursos à conta do Cosmos DB usando o aplicativo Java.First, you create an Azure Cosmos DB SQL API account using the Azure portal, create a Java app using the SQL Java SDK, add resources to your Cosmos DB account by using the Java application. Estas instruções podem ser seguidas em qualquer sistema operacional compatível com Java.The instructions in this quickstart can be followed on any operating system that is capable of running Java. Ao concluir este início rápido, você estará familiarizado com a criação e a modificação de contêineres e bancos de dados do Cosmos DB na interface do usuário ou de forma programática, o que preferir.After completing this quickstart you'll be familiar with creating and modifying Cosmos DB databases, containers in either the UI or programmatically, whichever is your preference.

Pré-requisitosPrerequisites

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Você pode Experimentar o Azure Cosmos DB gratuitamente sem uma assinatura do Azure, gratuitamente e sem compromisso.You can Try Azure Cosmos DB for free without an Azure subscription, free of charge and commitments. Ou, você pode usar o Emulador do Azure Cosmos DB com um URI de https://localhost:8081.Or, you can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. A Chave Primária é fornecida nas Solicitações de autenticação.The Primary Key is provided in Authenticating requests.

Além disso:In addition:

  • Java Development Kit (JDK) versão 8Java Development Kit (JDK) version 8
    • Defina a variável de ambiente JAVA_HOME para apontar para a pasta onde o JDK está instalado.Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • Baixar e instalar um armazenamento binário MavenDownload and install a Maven binary archive
    • No Ubuntu, você pode executar apt-get install maven para instalar o Maven.On Ubuntu, you can run apt-get install maven to install Maven.
  • GitGit
    • No Ubuntu, você pode executar sudo apt-get install git para instalar o Git.On Ubuntu, you can run sudo apt-get install git to install Git.

Criar uma conta de banco de dadosCreate a database account

Antes de criar um banco de dados de documentos, você precisa criar uma conta de API do SQL com o Azure Cosmos DB.Before you can create a document database, you need to create a SQL API account with Azure Cosmos DB.

  1. Entre no Portal do Azure.Sign in to the Azure portal.

  2. Selecione Criar um recurso > Bancos de dados > Azure Cosmos DB.Select Create a resource > Databases > Azure Cosmos DB.

    O painel Bancos de Dados do portal do Azure

  3. Na página Criar Conta do Azure Cosmos DB, insira as configurações básicas da nova conta do Azure Cosmos.On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    ConfiguraçãoSetting ValorValue DESCRIÇÃODescription
    AssinaturaSubscription Nome da assinaturaSubscription name Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos.Select the Azure subscription that you want to use for this Azure Cosmos account.
    Grupo de recursosResource Group Nome do grupo de recursosResource group name Selecione um grupo de recursos ou selecione Criar novo, então insira um nome exclusivo para o novo grupo de recursos.Select a resource group, or select Create new, then enter a unique name for the new resource group.
    Nome da contaAccount Name Insira um nome exclusivoEnter a unique name Insira um nome para identificar a conta do Azure Cosmos.Enter a name to identify your Azure Cosmos account. Como documents.Azure.com é acrescentado à ID que você fornece para criar o URI, use uma ID exclusiva.Because documents.azure.com is appended to the ID that you provide to create your URI, use a unique ID.

    A ID pode conter apenas letras minúsculas, números e o caractere de hífen (-).The ID can only contain lowercase letters, numbers, and the hyphen (-) character. Ela deve ter entre 3 e 31 caracteres.It must be between 3-31 characters in length.
    APIAPI Núcleo (SQL)Core (SQL) A API determina o tipo de conta a ser criada.The API determines the type of account to create. O Azure Cosmos DB fornece cinco APIs: Núcleo (SQL) e MongoDB para dados de documento, Gremlin para dados de grafo, Tabela do Azure e Cassandra.Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. No momento, você deve criar uma conta separada para cada API.Currently, you must create a separate account for each API.

    Selecione Núcleo (SQL) para criar uma consulta e um banco de dados de documento usando a sintaxe SQL.Select Core (SQL) to create a document database and query by using SQL syntax.

    Saiba mais sobre a API do SQL.Learn more about the SQL API.
    Local padrãoLocation Selecione a região mais próxima de seus usuáriosSelect the region closest to your users Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB.Select a geographic location to host your Azure Cosmos DB account. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.Use the location that is closest to your users to give them the fastest access to the data.

    A página da nova conta do Azure Cosmos DB

  4. Selecione Examinar + criar.Select Review + create. Você pode ignorar as seções Rede e Marcas.You can skip the Network and Tags sections.

  5. Examine as configurações da conta e selecione Criar.Review the account settings, and then select Create. São necessários alguns minutos para criar a conta.It takes a few minutes to create the account. Aguarde até que a página do portal exiba Sua implantação está concluída.Wait for the portal page to display Your deployment is complete.

    O painel Notificações do portal do Azure

  6. Selecione Ir para recurso para ir para a página da conta do Azure Cosmos DB.Select Go to resource to go to the Azure Cosmos DB account page.

    A página da conta do Azure Cosmos DB

Adicionar um contêinerAdd a container

Agora, você pode usar a ferramenta Data Explorer no portal do Azure para criar um banco de dados e um contêiner.You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. Selecione Data Explorer > Novo Contêiner.Select Data Explorer > New Container.

    A área Adicionar Contêiner é exibida à extrema direita; talvez seja necessário rolar a página para a direita para vê-la.The Add Container area is displayed on the far right, you may need to scroll right to see it.

    O Data Explorer do portal do Azure, painel Adicionar Contêiner

  2. Na página Adicionar contêiner, insira as configurações do novo contêiner.In the Add container page, enter the settings for the new container.

    ConfiguraçãoSetting Valor sugeridoSuggested value DESCRIÇÃODescription
    ID do banco de dadosDatabase ID TarefasTasks Insira ToDoList como o nome para o novo banco de dados.Enter ToDoList as the name for the new database. Os nomes dos banco de dados devem conter de 1 a 255 caracteres e não podem conter /, \\, #, ? nem um espaço à direita.Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. Marque a opção Provisionar a produtividade do banco de dados; ela permite que você compartilhe a produtividade provisionada para o banco de dados em todos os contêineres no banco de dados.Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. Essa opção também ajuda na economia de custo.This option also helps with cost savings.
    Taxa de transferênciaThroughput 400400 Deixe a taxa de transferência em 400 unidades de solicitação por segundo (RU/s).Leave the throughput at 400 request units per second (RU/s). Se quiser reduzir a latência, você poderá escalar verticalmente a taxa de transferência mais tarde.If you want to reduce latency, you can scale up the throughput later.
    ID do contêinerContainer ID ItensItems Insira Itens como o nome do novo contêiner.Enter Items as the name for your new container. As IDs do contêiner têm os mesmos requisitos de caractere dos nomes de bancos de dados.Container IDs have the same character requirements as database names.
    Chave de partiçãoPartition key /category/category O exemplo descrito neste artigo usa /category como a chave de partição.The sample described in this article uses /category as the partition key.

    Além das configurações anteriores, opcionalmente, você pode adicionar Chaves exclusivas ao contêiner.In addition to the preceding settings, you can optionally add Unique keys for the container. Vamos deixar o campo vazio neste exemplo.Let's leave the field empty in this example. As chaves exclusivas oferecem aos desenvolvedores a capacidade de adicionar uma camada de integridade dos dados ao seu banco de dados.Unique keys provide developers with the ability to add a layer of data integrity to the database. Ao criar uma política de chave exclusiva durante a criação de um contêiner, você garante a exclusividade de um ou mais valores por chave de partição.By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. Para obter mais informações, consulte o artigo Chaves exclusivas no Azure Cosmos DB.To learn more, refer to the Unique keys in Azure Cosmos DB article.

    Selecione OK.Select OK. O Data Explorer exibe o novo banco de dados e o contêiner.The Data Explorer displays the new database and container.

Adicionar dados de exemploAdd sample data

Agora você pode adicionar dados à sua nova coleção usando o Data Explorer.You can now add data to your new collection using Data Explorer.

  1. No Data Explorer, o novo banco de dados aparece no painel Coleções.In Data Explorer, the new database appears in the Collections pane. Expanda o banco de dados Tarefas, expanda a coleção Itens, clique em Documentos e clique em Novos Documentos.Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

    Criar novos documentos no Data Explorer no portal do Azure

  2. Agora, adicione um documento à coleção com a seguinte estrutura.Now add a document to the collection with the following structure.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. Depois de ter adicionado o json à guia Documentos, clique em Salvar.Once you've added the json to the Documents tab, click Save.

    Copie nos dados json e clique em Salvar no Data Explorer no portal do Azure

  4. Crie e salve mais um documento onde você insere um valor exclusivo para a propriedade id e altere as outras propriedades quando achar adequado.Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. Os novos documentos podem ter qualquer estrutura que você deseje, pois o Azure Cosmos DB não impõe nenhum esquema para seus dados.Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

Consultar seus dadosQuery your data

Você pode usar consultas no Data Explorer para recuperar e filtrar os dados.You can use queries in Data Explorer to retrieve and filter your data.

  1. Na parte superior da guia Documentos no Data Explorer, examine a consulta padrão SELECT * FROM c.At the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. Essa consulta recupera e exibe todos os documentos na coleção na ordem da ID.This query retrieves and displays all documents in the collection in ID order.

    A consulta padrão no Data Explorer é SELECT * FROM c

  2. Para alterar a consulta, selecione Editar Filtro, substitua a consulta padrão por ORDER BY c._ts DESC e selecione Aplicar Filtro.To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    Altere a consulta padrão adicionando ORDER BY c._ts DESC e clicando Aplicar Filtro

    A consulta modificada exibe os documentos em ordem decrescente com base em seu carimbo de data/hora, portanto, agora o segundo documento é listado primeiro.The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    Alterada a consulta para ORDER BY c._ts DESC e clicando em Aplicar Filtro

Se você estiver familiarizado com a sintaxe SQL, poderá inserir qualquer consulta SQL compatível na caixa de predicado de consulta.If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. Você também pode usar o Data Explorer para criar procedimentos armazenados, UDFs e gatilhos para lógica de negócios do lado do servidor.You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

O Data Explorer fornece acesso fácil ao portal do Azure para todos os recursos de acesso a dados programático interno por disponível nas APIs.Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. Você também pode usar o portal para dimensionar a taxa de transferência, obter as chaves e as cadeias de conexão e examinar as métricas e os SLAs para sua conta do Azure Cosmos DB.You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

Clonar o aplicativo de exemploClone the sample application

Agora, vamos trabalhar com o código.Now let's switch to working with code. Vamos clonar um aplicativo de API do SQL do GitHub, definir a cadeia de conexão e executá-lo.Let's clone a SQL API app from GitHub, set the connection string, and run it. Você verá como é fácil trabalhar usando dados de forma programática.You'll see how easy it is to work with data programmatically.

  1. Execute o comando a seguir para clonar o repositório de exemplo.Run the following command to clone the sample repository. Este comando cria uma cópia do aplicativo de exemplo no seu computador.This command creates a copy of the sample app on your computer.

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

Examine o códigoReview the code

Esta etapa é opcional.This step is optional. Se você estiver interessado em aprender como os recursos de banco de dados são criados no código, poderá examinar os snippets de código a seguir.If you're interested in learning how the database resources are created in the code, you can review the following snippets. Caso contrário, você poderá seguir para Executar o aplicativo.Otherwise, you can skip ahead to Run the app .

  • Inicialização de AsyncDocumentClient.AsyncDocumentClient initialization. O AsyncDocumentClient fornece a representação lógica do lado do cliente para o serviço de banco de dados do Azure Cosmos.The AsyncDocumentClient provides client-side logical representation for the Azure Cosmos database service. Esse cliente é usado para configurar e executar solicitações no serviço.This client is used to configure and execute requests against the service.

    client = new AsyncDocumentClient.Builder()
             .withServiceEndpoint(YOUR_COSMOS_DB_ENDPOINT)
             .withMasterKeyOrResourceToken(YOUR_COSMOS_DB_MASTER_KEY)
             .withConnectionPolicy(ConnectionPolicy.GetDefault())
             .withConsistencyLevel(ConsistencyLevel.Eventual)
             .build();
    
  • Criação do Banco de Dados.Database creation.

    Database databaseDefinition = new Database();
    databaseDefinition.setId(databaseName);
    
    client.createDatabase(databaseDefinition, null)
            .toCompletable()
            .await();
    
  • Criação de DocumentCollection.DocumentCollection creation.

    DocumentCollection collectionDefinition = new DocumentCollection();
    collectionDefinition.setId(collectionName);
    
    //...
    
    client.createCollection(databaseLink, collectionDefinition, requestOptions)
            .toCompletable()
            .await();
    
  • Criação de documentos usando o método createDocument.Document creation by using the createDocument method.

    // Any Java object within your code
    // can be serialized into JSON and written to Azure Cosmos DB
    Family andersenFamily = new Family();
    andersenFamily.setId("Andersen.1");
    andersenFamily.setLastName("Andersen");
    // More properties
    
    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    client.createDocument(collectionLink, family, null, true)
            .toCompletable()
            .await();
    
    
  • Consultas SQL em JSON são executadas usando o método queryDocuments.SQL queries over JSON are performed using the queryDocuments method.

    FeedOptions queryOptions = new FeedOptions();
    queryOptions.setPageSize(-1);
    queryOptions.setEnableCrossPartitionQuery(true);
    queryOptions.setMaxDegreeOfParallelism(-1);
    
    String collectionLink = String.format("/dbs/%s/colls/%s",
            databaseName,
            collectionName);
    Iterator<FeedResponse<Document>> it = client.queryDocuments(
            collectionLink,
            "SELECT * FROM Family WHERE Family.lastName = 'Andersen'",
            queryOptions).toBlocking().getIterator();
    
    System.out.println("Running SQL query...");
    while (it.hasNext()) {
        FeedResponse<Document> page = it.next();
        System.out.println(
                String.format("\tRead a page of results with %d items",
                        page.getResults().size()));
        for (Document doc : page.getResults()) {
            System.out.println(String.format("\t doc %s", doc));
        }
    }
    

Execute o aplicativoRun the app

Agora volte ao portal do Azure para obter as informações de cadeia de conexão e iniciar o aplicativo com as informações de ponto de extremidade.Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. Isso permite que seu aplicativo se comunique com o banco de dados hospedado.This enables your app to communicate with your hosted database.

  1. Na janela do terminal do Git, execute cd na pasta do código de exemplo.In the git terminal window, cd to the sample code folder.

    cd azure-cosmos-db-sql-api-async-java-getting-started/azure-cosmosdb-get-started
    
  2. Na janela do terminal git, use o seguinte comando para instalar os pacotes necessários do Java.In the git terminal window, use the following command to install the required Java packages.

    mvn package
    
  3. Na janela do terminal git, use o seguinte comando para iniciar o aplicativo Java (substitua YOUR_COSMOS_DB_HOSTNAME pelo valor entre aspas do URI do portal e substitua YOUR_COSMOS_DB_MASTER_KEY pela chave primária entre aspas do portal)In the git terminal window, use the following command to start the Java application (replace YOUR_COSMOS_DB_HOSTNAME with the quoted URI value from the portal, and replace YOUR_COSMOS_DB_MASTER_KEY with the quoted primary key from portal)

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

    A janela de terminal exibe uma notificação de que o banco de dados FamilyDB foi criado.The terminal window displays a notification that the FamilyDB database was created.

  4. Pressione uma tecla para criar o banco de dados e outra tecla para criar a coleção.Press a key to create the database, and then another key to create the collection.

    Alterne para o Data Explorer no navegador para ver que agora ele contém um banco de dados FamilyDB e uma coleção FamilyCollection.Switch back to Data Explorer in your browser to see that it now contains a FamilyDB database, and FamilyCollection collection.

  5. Alterne para a janela do console e pressione uma tecla para criar o primeiro documento, depois pressione outra tecla para criar o segundo documento.Switch to the console window and press a key to create the first document, and then another key to create the second document. Depois, alterne de volta para o Data Explorer para exibi-los.Then switch back to Data Explorer to view them.

  6. Pressione uma tecla para executar uma consulta e ver a saída na janela do console.Press a key to run a query and see the output in the console window.

  7. O aplicativo não exclui os recursos criados.The app doesn't delete the created resources. Volte para o portal a fim de limpar os recursos.Switch back to the portal to clean up the resources. da sua conta para que você não incorra em encargos.from your account so that you don't incur charges.

    Saída do console

Examinar SLAs no Portal do AzureReview SLAs in the Azure portal

O portal do Azure monitora a taxa de transferência, armazenamento, disponibilidade, latência e consistência da conta do Cosmos DB.The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Gráficos de métricas associados a um SLA (Contrato de Nível de Serviço) do Azure Cosmos DB mostram o valor do SLA em comparação com o desempenho real.Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. Esse conjunto de métricas torna o monitoramento dos SLAs transparente.This suite of metrics makes monitoring your SLAs transparent.

Para examinar as métricas e os SLAs:To review metrics and SLAs:

  1. Selecione Métricas no menu de navegação da sua conta do Cosmos DB.Select Metrics in your Cosmos DB account's navigation menu.

  2. Selecione uma guia, tal como Latência, e selecione um período à direita.Select a tab such as Latency, and select a timeframe on the right. Comparar as linhas Real e SLA dos gráficos.Compare the Actual and SLA lines on the charts.

    Pacote de métricas do Azure Cosmos DB

  3. Examine as métricas nas outras guias.Review the metrics on the other tabs.

Limpar recursosClean up resources

Quando você concluir seu aplicativo Web e a conta do Azure Cosmos DB, poderá excluir os recursos do Azure criados para não incorrer em mais cobranças.When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. Para excluir os recursos:To delete the resources:

  1. No portal do Azure, selecione Grupos de recursos no canto esquerdo.In the Azure portal, select Resource groups on the far left. Se o menu esquerdo estiver recolhido, selecione Expandir botão para expandi-lo.If the left menu is collapsed, select Expand button to expand it.

  2. Selecione o grupo de recursos que você criou para este início rápido.Select the resource group you created for this quickstart.

    Métricas no portal do Azure

  3. Na nova janela, selecione Excluir grupo de recursos.In the new window, select Delete resource group.

    Métricas no portal do Azure

  4. Na próxima janela, digite o nome do grupo de recursos a ser excluído e selecione Excluir.In the next window, type the name of the resource group to delete, and then select Delete.

Próximas etapasNext steps

Neste início rápido, você aprendeu a criar uma conta do Azure Cosmos, um banco de dados de documentos e um contêiner usando o Data Explorer e executar um aplicativo para fazer a mesma coisa de forma programática.In this quickstart, you've learned how to create an Azure Cosmos account, document database, and container using the Data Explorer, and run an app to do the same thing programmatically. Agora, você pode importar dados adicionais para seu contêiner do Azure Cosmos.You can now import additional data into your Azure Cosmos container.