快速入门:生成 Java 应用以管理 Azure Cosmos DB SQL API 数据

适用于: SQL API

在本快速入门中,你将通过 Azure 门户并使用从 GitHub 克隆的 Java 应用来创建和管理 Azure Cosmos DB SQL API 帐户。 首先,请使用 Azure 门户创建 Azure Cosmos DB SQL API 帐户,使用 SQL Java SDK 创建 Java 应用,然后使用 Java 应用程序将资源添加到 Cosmos DB 帐户。 Azure Cosmos DB 是一种多模型数据库服务,可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图数据库。

重要

本快速入门仅适用于 Azure Cosmos DB Java SDK v4。 请查看 Azure Cosmos DB Java SDK v4 发行说明Maven 存储库、Azure Cosmos DB Java SDK v4 性能提示和 Azure Cosmos DB Java SDK v4 故障排除指南了解详细信息。 如果你当前使用的是早于 v4 的版本,请参阅迁移到 Azure Cosmos DB Java SDK v4 指南,获取升级到 v4 的相关帮助。

先决条件

  • 具有活动订阅的 Azure 帐户。 创建试用版订阅。 你还可以使用 Azure Cosmos DB 模拟器以及 URI https://localhost:8081 和密钥 C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

  • Java 开发工具包 (JDK) 8。 将 JAVA_HOME 环境变量指向其中安装了 JDK 的文件夹。

  • Maven 二进制存档。 在 Ubuntu 上运行 apt-get install maven,以安装 Maven。

  • Git。 在 Ubuntu 上运行 sudo apt-get install git,以安装 Git。

介绍性说明

Cosmos DB 帐户的结构。 不管使用 API 还是编程语言,都具有以下特点:一个 Cosmos DB 帐户包含零个或零个以上的数据库,一个数据库 (DB) 包含零个或零个以上的容器,一个容器包含零个或零个以上的项,如下图所示:

Azure Cosmos 帐户实体

可在此处阅读有关数据库、容器和项的详细信息。 几个重要属性在容器级别定义,其中包括预配吞吐量和分区键。

预配吞吐量以具有货币价格的请求单位 (RU) 度量,是帐户运营成本中重要的确定性因素。 可以按单容器粒度或单数据库粒度选择预配吞吐量,但通常首选容器级别吞吐量规范。 可在此处阅读有关吞吐量预配的详细信息。

将项插入 Cosmos DB 容器时,数据库会添加更多的存储和计算来处理请求,以水平方式增长。 存储和计算容量添加到称为分区的离散单元中,你必须在文档中选择一个字段作为分区键,以便将每个文档映射到分区。 分区的管理方式是从分区键值的范围内为每个分区分配一个大致相等的切片;因此,建议选择相对随机或均匀分布的分区键。 否则,某些分区看到的请求数会多得多(热分区),而其他分区看到的请求数会少得多(冷分区),这是应该避免的。 可以在此处详细了解分区。

创建数据库帐户

在创建文档数据库之前,需通过 Azure Cosmos DB 创建 SQL API 帐户。

  1. 在 Azure 门户菜单或主页中,选择“创建资源” 。

  2. 在“新建”页面中搜索“Azure Cosmos DB”,然后选择它。

  3. 在“Azure Cosmos DB”页上,选择“创建”。

  4. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos 帐户的基本设置。

    设置 说明
    订阅 订阅名称 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。
    资源组 资源组名称 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。
    帐户名 唯一的名称 输入标识此 Azure Cosmos 帐户的名称。 由于 documents.azure.cn 将追加到所提供的名称以创建 URI,因此,请使用唯一的名称。

    名称只能包含小写字母、数字和连字符 (-)。 它的长度必须介于 3 到 31 个字符之间。
    API 要创建的帐户的类型 选择“Core (SQL)”,以便使用 SQL 语法创建文档数据库并进行查询。

    API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API:适用于文档数据的 Core (SQL) 和 MongoDB、适用于图形数据的 Gremlin、Azure 表和 Cassandra。 目前,你必须为每种 API 创建单独的帐户。

    详细了解 SQL API
    位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。
    应用 Azure Cosmos DB 免费层折扣 “应用”或“不应用” 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。

    备注

    每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。

    Azure Cosmos DB 的“新建帐户”页面

  5. 在“全局分发”选项卡中,配置以下详细信息。 对于本快速入门,可以保留默认值:

    设置 说明
    异地冗余 禁用 通过将你的区域与另一区域进行配对来启用或禁用帐户的全局分发。 稍后可以将更多区域添加到帐户。
    多区域写入 禁用 借助多区域写入功能,可以利用全球数据库和容器的预配吞吐量。

    备注

    如果选择“无服务器”作为“容量模式”,则以下选项不可用 :

    • 应用免费层折扣
    • 异地冗余
    • 多区域写入
  6. (可选)可以在以下选项卡中配置其他详细信息:

    • 网络 - 配置从虚拟网络进行访问

    • 备份策略 -配置定期备份策略。

    • 加密 - 使用服务管理的密钥或客户管理的密钥

    • 标记 - 标记是名称/值对。通过将相同的标记应用到多个资源和资源组,可以对资源进行分类并查看合并的账单。

  7. 选择“查看 + 创建”。

  8. 检查帐户设置,然后选择“创建”。 创建帐户需要几分钟时间。 等待门户页显示“你的部署已完成”消息。

    Azure 门户“通知”窗格

  9. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。

    Azure Cosmos DB 帐户页面

添加容器

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和容器。

  1. 选择“数据资源管理器” > “新建容器”。

    “添加容器”区域显示在最右侧,可能需要向右滚动才能看到它。

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

  2. 在“添加容器”页中,输入新容器的设置。

    设置 建议的值 说明
    数据库 ID ToDoList 输入 Tasks 作为新数据库的名称。 数据库名称必须包含 1 到 255 个字符,不能包含 /, \\, #, ? 或尾随空格。 选中“跨容器共享吞吐量”选项,这样就可以在数据库中的所有容器之间共享在该数据库上预配的吞吐量。 此选项还有助于节省成本。
    数据库吞吐量 可以预配“自动缩放”或“手动”吞吐量 。 “手动”吞吐量使你可以自行缩放 RU/秒,而自动缩放吞吐量使系统可以根据使用情况缩放 RU/秒。 对于此示例,请选择“手动”。

    将吞吐量保留为每秒 400 个请求单位 (RU/s)。 如果希望减少延迟,可以稍后通过使用容量计算器估算所需的 RU/秒来纵向扩展吞吐量。

    注意:在无服务器帐户中创建新容器时,此设置不可用。
    容器 ID Items 输入 Items 作为新容器的名称。 容器 ID 与数据库名称的字符要求相同。
    分区键 /category 本文中所述的示例使用 /category 作为分区键。

    请勿为此示例添加“唯一键”或启用“分析存储” 。 使用唯一键可将数据完整性层添加到数据库,因为它能确保每个分区键的一个或多个值的唯一性。 有关详细信息,请参阅 Azure Cosmos DB 中的唯一键分析存储用于针对操作数据启用大规模分析,而不会对事务工作负载产生任何影响。

    选择“确定” 。 数据资源管理器将显示新的数据库和容器。

添加示例数据

现在可以使用数据资源管理器将数据添加到新容器。

  1. 在“数据资源管理器”中展开“Tasks”数据库,然后展开“Items”容器。 依次选择“项”、“新建项”。

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

  2. 现在,将文档添加到具有以下结构的容器。

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. 将 json 添加到“文档”选项卡以后,即可选择“保存”。

    通过复制添加 JSON 数据,然后在 Azure 门户上的数据资源管理器中选择“保存”

  4. 再创建并保存一个文档,在其中插入 id 属性的唯一值,并将其他属性更改为适当值。 新文档可以具有所需的任何结构,因为 Azure Cosmos DB 不对数据施加任何架构。

查询数据

可以在数据资源管理器中使用查询来检索和筛选数据。

  1. 在数据资源管理器的“项”选项卡顶部,查看默认查询 SELECT * FROM c。 此查询检索并显示容器中按 ID 排序的所有文档。

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

  2. 若要更改查询,请选择“编辑筛选器”,将默认查询替换为 ORDER BY c._ts DESC,然后选择“应用筛选器”。

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

    此修改后的查询根据文档的时间戳按降序显示文档,所以现在最先列出的是第二个文档。

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

如果熟悉 SQL 语法,可以在查询谓词框中输入任何受支持的 SQL 查询。 还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑。

数据资源管理器可以通过 Azure 门户轻松访问 API 中提供的所有内置编程数据访问功能。 也可通过门户缩放吞吐量、获取密钥和连接字符串,以及查看 Azure Cosmos DB 帐户的指标和 SLA。

克隆示例应用程序

现在,让我们转到如何使用代码上来。 接下来,克隆 GitHub 中的 SQL API 应用程序,设置连接字符串,并运行应用程序。 会看到以编程方式处理数据是多么容易。

运行下列命令,克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

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

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。 否则,可以跳到运行应用

使用同步 (sync) API 管理数据库资源

  • CosmosClient 初始化。 CosmosClient 为 Azure Cosmos 数据库服务提供客户端逻辑表示形式。 此客户端用于对服务配置和执行请求。

    client = new CosmosClientBuilder()
        .endpoint(AccountSettings.HOST)
        .key(AccountSettings.MASTER_KEY)
        //  Setting the preferred location to Cosmos DB Account region
        //  China North is just an example. User should set preferred location to the Cosmos DB region closest to the application
        .preferredRegions(Collections.singletonList("China North"))
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildClient();
    
    
  • CosmosDatabase 的创建。

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
    
  • CosmosContainer 的创建。

    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());
    
    
  • 使用 createItem 方法创建项。

    //  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);
    
    
  • 使用 readItem 方法执行点读取。

    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);
    }
    
    
  • 使用 queryItems 方法对 JSON 执行 SQL 查询。

    // 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()));
    });
    
    

运行应用

现在返回到 Azure 门户,获取连接字符串信息,并使用终结点信息启动应用。 这样,应用程序就可以与托管的数据库进行通信。

  1. 在 git 终端窗口中,通过 cd 转至示例代码文件夹。

    cd azure-cosmos-java-getting-started
    
  2. 在 git 终端窗口中,使用以下命令安装所需的 Java 包。

    mvn package
    
  3. 在 git 终端窗口中,使用以下命令启动 Java 应用程序(请将 SYNCASYNCMODE 替换为 syncasync,具体取决于要运行的示例代码;将 YOUR_COSMOS_DB_HOSTNAME 替换为门户中带引号的 URI 值,并将 YOUR_COSMOS_DB_MASTER_KEY 替换为门户中带引号的主密钥)

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

    此时,终端窗口显示通知,提示 FamilyDB 数据库已创建。

  4. 该应用创建名为 AzureSampleFamilyDB 的数据库

  5. 该应用创建名为 FamilyContainer 的容器

  6. 该应用使用对象 ID 和分区键值(在本示例中为 lastName)执行点读取。

  7. 该应用将查询项,以检索姓氏中包含 ('Andersen', 'Wakefield', 'Johnson') 的所有家庭

  8. 应用不删除创建的资源。 切换回门户,以便在帐户中清理资源, 以免产生费用。

在 Azure 门户中查看 SLA

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。 与 Azure Cosmos DB 服务级别协议 (SLA) 关联的指标的图表显示与实际性能相比的 SLA 值。 此套指标使得监视 SLA 十分透明。

若要查看指标和 SLA,请执行以下操作:

  1. 在 Cosmos DB 帐户的导航菜单中选择“指标” 。

  2. 选择一个选项卡,如“延迟” ,然后选择右侧的时间范围。 比较图表上的“实际” 和“SLA” 线。

    Azure Cosmos DB 指标套件

  3. 查看其他选项卡上的指标。

清理资源

执行完应用和 Azure Cosmos DB 帐户的操作以后,可以删除所创建的 Azure 资源,以免产生更多费用。 若要删除资源,请执行以下操作:

  1. 在 Azure 门户的“搜索”栏中,搜索并选择“资源组” 。

  2. 从列表中选择为本快速入门创建的资源组。

    选择要删除的资源组

  3. 在资源组“概览”页上,选择“删除资源组” 。

    删除资源组

  4. 在下一窗口中输入要删除的资源组的名称,然后选择“删除” 。

后续步骤

在本快速入门中,你已了解了如何使用数据资源管理器创建 Azure Cosmos DB SQL API 帐户、文档数据库和容器,以及如何通过运行 Java 应用以编程方式执行同一操作。 现在可以将其他数据导入 Azure Cosmos DB 帐户了。