快速入门:使用 Azure Cosmos DB SQL API 帐户构建 Java 应用程序Quickstart: Build a Java application using Azure Cosmos DB SQL API account

本快速入门介绍如何使用 Java 应用程序创建和管理 Azure Cosmos DB SQL API 帐户的资源。This quickstart shows how to create and manage resources of an Azure Cosmos DB SQL API account by using a Java application. 首先,请使用 Azure 门户创建 Azure Cosmos DB SQL API 帐户,使用 SQL Java SDK 创建 Java 应用,使用 Java 应用程序将资源添加到 Cosmos DB 帐户。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. 本快速入门中的说明适用于任何能够运行 Java 的操作系统。The instructions in this quickstart can be followed on any operating system that is capable of running Java. 完成本快速入门以后,你就会熟悉如何通过 UI 或编程方式(以首选方式为准)创建和修改 Cosmos DB 数据库和容器。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.

先决条件Prerequisites

如果没有 Azure 订阅,可在开始前创建一个试用帐户If you don't have an Azure subscription, create a trial account before you begin.

可以使用 URI 为 https://localhost:8081Azure Cosmos DB 模拟器You can use the Azure Cosmos DB Emulator with a URI of https://localhost:8081. 对请求进行身份验证中提供了主密钥。The Primary Key is provided in Authenticating requests.

此外:In addition:

  • Java 开发工具包 (JDK) 版本 8Java Development Kit (JDK) version 8
    • 请确保设置 JAVA_HOME 环境变量,使之指向在其中安装了 JDK 的文件夹。Be sure to set the JAVA_HOME environment variable to point to the folder where the JDK is installed.
  • 下载安装 Maven 二进制存档Download and install a Maven binary archive
    • 在 Ubuntu 上,可以通过运行 apt-get install maven 来安装 Maven。On Ubuntu, you can run apt-get install maven to install Maven.
  • GitGit
    • 在 Ubuntu 上,可以通过运行 sudo apt-get install git 来安装 Git。On Ubuntu, you can run sudo apt-get install git to install Git.

创建数据库帐户Create a database account

在创建文档数据库之前,需通过 Azure Cosmos DB 创建 SQL API 帐户。Before you can create a document database, you need to create a SQL API account with Azure Cosmos DB.

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 选择“创建资源” > “数据库” > “Azure Cosmos DB”。Select Create a resource > Databases > Azure Cosmos DB.

    Azure 门户“数据库”窗格

  3. 在“创建 Azure Cosmos DB 帐户”页上,输入新 Azure Cosmos 帐户的基本设置。On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    设置Setting Value DescriptionDescription
    订阅Subscription 订阅名称Subscription name 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。Select the Azure subscription that you want to use for this Azure Cosmos account.
    资源组Resource Group 资源组名称Resource group name 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。Select a resource group, or select Create new, then enter a unique name for the new resource group.
    帐户名Account Name 输入唯一的名称Enter a unique name 输入标识此 Azure Cosmos 帐户的名称。Enter a name to identify your Azure Cosmos account. 由于 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一的 ID。Because documents.azure.cn is appended to the ID that you provide to create your URI, use a unique ID.

    ID 只能包含小写字母、数字和连字符 (-) 字符。The ID can only contain lowercase letters, numbers, and the hyphen (-) character. 它的长度必须介于 3 到 31 个字符之间。It must be between 3-31 characters in length.
    APIAPI Core (SQL)Core (SQL) API 确定要创建的帐户的类型。The API determines the type of account to create. Azure Cosmos DB 提供五种 API:适用于文档数据的 Core (SQL) 和 MongoDB、适用于图形数据的 Gremlin、Azure 表和 Cassandra。Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 目前,你必须为每种 API 创建单独的帐户。Currently, you must create a separate account for each API.

    选择“Core (SQL)”,以便使用 SQL 语法创建文档数据库并进行查询。Select Core (SQL) to create a document database and query by using SQL syntax.

    详细了解 SQL APILearn more about the SQL API.
    位置Location 选择离用户最近的区域Select the region closest to your users 选择用于托管 Azure Cosmos DB 帐户的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用离用户最近的位置,使他们能够以最快的速度访问数据。Use the location that is closest to your users to give them the fastest access to the data.

    Azure Cosmos DB 的“新建帐户”页

  4. 选择“查看 + 创建”。Select Review + create. 可以跳过“网络”和“标记”部分。You can skip the Network and Tags sections.

  5. 检查帐户设置,然后选择“创建”。Review the account settings, and then select Create. 创建帐户需要几分钟时间。It takes a few minutes to create the account. 等待门户页显示“你的部署已完成”消息。Wait for the portal page to display Your deployment is complete.

    Azure 门户“通知”窗格

  6. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB 帐户页

添加容器Add a container

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和容器。You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. 选择“数据资源管理器” > “新建容器”。 Select Data Explorer > New Container.

    “添加容器”区域显示在最右侧,可能需要向右滚动才能看到它。 The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Azure 门户 >“数据资源管理器”>“添加集合”窗格

  2. 在“添加容器”页中,输入新容器的设置。 In the Add container page, enter the settings for the new container.

    设置Setting 建议的值Suggested value 说明Description
    数据库 IDDatabase ID 任务Tasks 输入 ToDoList 作为新数据库的名称。Enter ToDoList as the name for the new database. 数据库名称必须包含 1 到 255 个字符,不能包含 /, \\, #, ? 或尾随空格。Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. 选中“预配数据库吞吐量”选项,这样就可以在数据库中的所有容器之间共享预配给该数据库的吞吐量。 Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. 此选项还有助于节省成本。This option also helps with cost savings.
    吞吐量Throughput 400400 将吞吐量保留为每秒 400 个请求单位 (RU/s)。Leave the throughput at 400 request units per second (RU/s). 如果想要减少延迟,以后可以增加吞吐量。If you want to reduce latency, you can scale up the throughput later.
    容器 IDContainer ID ItemsItems 输入 Items 作为新容器的名称。Enter Items as the name for your new container. 容器 ID 与数据库名称的字符要求相同。Container IDs have the same character requirements as database names.
    分区键Partition key /category/category 本文中所述的示例使用 /category 作为分区键。The sample described in this article uses /category as the partition key.

    除了前面的设置,还可以选择为容器添加“唯一键”。 In addition to the preceding settings, you can optionally add Unique keys for the container. 在此示例中,请将此字段留空。Let's leave the field empty in this example. 开发人员可以使用唯一键向数据库添加一层数据完整性。Unique keys provide developers with the ability to add a layer of data integrity to the database. 创建容器时,通过创建唯一键策略,可确保每个分区键的一个或多个值的唯一性。By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. 若要了解详细信息,请参阅 Azure Cosmos DB 中的唯一键一文。To learn more, refer to the Unique keys in Azure Cosmos DB article.

    选择“确定” 。Select OK. 数据资源管理器将显示新的数据库和容器。The Data Explorer displays the new database and container.

添加示例数据Add sample data

现在可以使用数据资源管理器将数据添加到新集合。You can now add data to your new collection using Data Explorer.

  1. 在数据资源管理器中,新数据库会显示在“集合”窗格中。In Data Explorer, the new database appears in the Collections pane. 展开 Tasks 数据库,展开 Items 集合,单击“文档”,然后单击“新建文档”。Expand the Tasks database, expand the Items collection, click Documents, and then click New Documents.

    在 Azure 门户的数据资源管理器中创建新文档

  2. 现在,将文档添加到具有以下结构的集合。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. 将 json 添加到“文档”选项卡以后,单击“保存”。Once you've added the json to the Documents tab, click Save.

    通过复制添加 json 数据,然后在 Azure 门户的数据资源管理器中单击“保存”

  4. 再创建并保存一个文档,在其中插入 id 属性的唯一值,并将其他属性更改为适当值。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. 新文档可以具有所需的任何结构,因为 Azure Cosmos DB 不对数据施加任何架构。Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

查询数据Query your data

可以在数据资源管理器中使用查询来检索和筛选数据。You can use queries in Data Explorer to retrieve and filter your data.

  1. 在数据资源管理器的“文档”选项卡顶部,查看默认查询 SELECT * FROM cAt the top of the Documents tab in Data Explorer, review the default query SELECT * FROM c. 此查询按 ID 顺序检索并显示集合中的所有文档。This query retrieves and displays all documents in the collection in ID order.

    数据资源管理器中的默认查询是“SELECT * FROM c”

  2. 若要更改查询,请选择“编辑筛选器”,将默认查询替换为 ORDER BY c._ts DESC,然后选择“应用筛选器”。To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

    添加“ORDER BY c._ts DESC”并单击“应用筛选器”,更改默认查询

    此修改后的查询根据文档的时间戳按降序显示文档,所以现在最先列出的是第二个文档。The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    将查询更改为 ORDER BY c._ts DESC,然后单击“应用筛选器”

如果熟悉 SQL 语法,可以在查询谓词框中输入任何受支持的 SQL 查询If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. 还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑。You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

数据资源管理器可以通过 Azure 门户轻松访问 API 中提供的所有内置编程数据访问功能。Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. 也可通过门户缩放吞吐量、获取密钥和连接字符串,以及查看 Azure Cosmos DB 帐户的指标和 SLA。You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

克隆示例应用程序Clone the sample application

现在,让我们转到如何使用代码上来。Now let's switch to working with code. 接下来,克隆 GitHub 中的 SQL API 应用程序,设置连接字符串,并运行应用程序。Let's clone a SQL API app from GitHub, set the connection string, and run it. 会看到以编程方式处理数据是多么容易。You'll see how easy it is to work with data programmatically.

  1. 运行下列命令以克隆示例存储库。Run the following command to clone the sample repository. 此命令在计算机上创建示例应用程序的副本。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
    

查看代码Review the code

此步骤是可选的。This step is optional. 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。If you're interested in learning how the database resources are created in the code, you can review the following snippets. 否则,可以跳到运行应用Otherwise, you can skip ahead to Run the app.

  • AsyncDocumentClient 初始化。AsyncDocumentClient initialization. AsyncDocumentClient 为 Azure Cosmos 数据库服务提供客户端逻辑表示。The AsyncDocumentClient provides client-side logical representation for the Azure Cosmos database service. 此客户端用于对服务配置和执行请求。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();
    
  • Database 创建。Database creation.

    Database databaseDefinition = new Database();
    databaseDefinition.setId(databaseName);
    
    client.createDatabase(databaseDefinition, null)
            .toCompletable()
            .await();
    
  • DocumentCollection 创建。DocumentCollection creation.

    DocumentCollection collectionDefinition = new DocumentCollection();
    collectionDefinition.setId(collectionName);
    
    //...
    
    client.createCollection(databaseLink, collectionDefinition, requestOptions)
            .toCompletable()
            .await();
    
  • 使用 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();
    
    
  • 使用 queryDocuments 方法,对 JSON 执行 SQL 查询。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));
        }
    }
    

运行应用Run the app

现在返回到 Azure 门户,获取连接字符串信息,并使用终结点信息启动应用。Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. 这样,应用程序就可以与托管的数据库进行通信。This enables your app to communicate with your hosted database.

  1. 在 git 终端窗口中,通过 cd 转至示例代码文件夹。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. 在 git 终端窗口中,使用以下命令安装所需的 Java 包。In the git terminal window, use the following command to install the required Java packages.

    mvn package
    
  3. 在 git 终端窗口中,使用以下命令启动 Java 应用程序(将 YOUR_COSMOS_DB_HOSTNAME 替换为门户中带引号的 URI 值,将 YOUR_COSMOS_DB_MASTER_KEY 替换为门户中带引号的主键)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
    
    

    此时,终端窗口显示通知,提示 FamilyDB 数据库已创建。The terminal window displays a notification that the FamilyDB database was created.

  4. 按下某个键创建数据库,然后按下另一个键创建集合。Press a key to create the database, and then another key to create the collection.

    在浏览器中切换回到数据资源管理器,可以看到,帐户中现在包含 FamilyDB 数据库和 FamilyCollection 集合。Switch back to Data Explorer in your browser to see that it now contains a FamilyDB database, and FamilyCollection collection.

  5. 切换到控制台窗口,按下某个键创建第一个文档,再按下另一个键创建第二个文档。Switch to the console window and press a key to create the first document, and then another key to create the second document. 然后切换回到数据资源管理器以查看这些资源。Then switch back to Data Explorer to view them.

  6. 按下某个键运行查询,并在控制台窗口中查看输出。Press a key to run a query and see the output in the console window.

  7. 应用不删除创建的资源。The app doesn't delete the created resources. 切换回门户,以便在帐户中清理资源Switch back to the portal to clean up the resources. 以免产生费用。from your account so that you don't incur charges.

    控制台输出

在 Azure 门户中查看 SLAReview SLAs in the Azure portal

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Azure Cosmos DB 服务级别协议 (SLA) 相关联的指标的图表显示与实际性能对比的 SLA 值。Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. 这套指标使 SLA 监视变得透明。This suite of metrics makes monitoring your SLAs transparent.

若要查看指标和 SLA,请执行以下操作:To review metrics and SLAs:

  1. 在 Cosmos DB 帐户的导航菜单中,选择“指标”。Select Metrics in your Cosmos DB account's navigation menu.

  2. 选择一个选项卡,例如“延迟”,然后在右侧选择一个时间范围。Select a tab such as Latency, and select a timeframe on the right. 比较图表上的“实际值”行和“SLA”行。Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB 指标套件

  3. 查看其他选项卡上的指标。Review the metrics on the other tabs.

清理资源Clean up resources

不再需要 Web 应用和 Azure Cosmos DB 帐户以后,即可删除创建的 Azure 资源,避免产生更多费用。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. 若要删除资源,请执行以下操作:To delete the resources:

  1. 在 Azure 门户中,选择最左侧的“资源组”。In the Azure portal, select Resource groups on the far left. 如果左侧菜单处于折叠状态,请选择 “展开”按钮 将其展开。If the left menu is collapsed, select Expand button to expand it.

  2. 选择为本快速入门创建的资源组。Select the resource group you created for this quickstart.

    Azure 门户中的指标

  3. 在新窗口中选择“删除资源组”。In the new window, select Delete resource group.

    Azure 门户中的指标

  4. 在下一窗口中键入要删除的资源组的名称,然后选择“删除”。In the next window, type the name of the resource group to delete, and then select Delete.

后续步骤Next steps

本快速入门介绍了如何使用数据资源管理器创建 Azure Cosmos 帐户、文档数据库和容器,以及如何通过运行应用以编程方式执行同一操作。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. 现在可以将其他数据导入 Azure Cosmos 容器。You can now import additional data into your Azure Cosmos container.