Azure Cosmos DB:使用 Java 和 Azure 门户生成 DocumentDB API 应用

Azure Cosmos DB 由 Microsoft 提供,是全球分布的多模型数据库服务。 可快速创建和查询文档、键/值数据库,所有这些都受益于 Azure Cosmos DB 核心的全球分布和水平缩放功能。

本快速入门教程演示如何使用 Azure 门户创建 Azure Cosmos DB 帐户、文档数据库和集合。 然后会生成并运行基于 DocumentDB Java API 构建的控制台应用。

先决条件

  • 在运行此示例之前,必须具备以下先决条件:
    • JDK 1.7+(如果没有 JDK,请运行 apt-get install default-jdk
    • Maven(如果没有 Maven,请运行 apt-get install maven
Note

如果没有 Azure 订阅,可在开始前创建一个试用帐户

创建数据库帐户

  1. 在新窗口中,登录到 Azure 门户
  2. 在左侧窗格中,依次单击“新建”、“数据库”、“Azure Cosmos DB”。

    Azure 门户“数据库”窗格

  3. 在“新建帐户”边栏选项卡中,为 Azure Cosmos DB 帐户指定所需配置。

    使用 Azure Cosmos DB,可以选择以下三个编程模型之一:MongoDB、SQL (DocumentDB) 和表(键/值)。

    在本快速入门文章中,我们针对 DocumentDB API 进行编程,因此填写表单时,请选择“SQL(DocumentDB)”。 但如果有社交媒体应用的图形数据、键/值(表)数据或从 MongoDB 应用迁移的数据,请意识到 Azure Cosmos DB 可以为所有任务关键型应用程序提供高度可用的全球分布式数据库服务平台。

    将以下屏幕截图中的信息作为指南,完成“新建帐户”边栏选项卡上的各字段。 设置帐户时,选择与屏幕截图中的值不匹配的唯一值。

    “新建 Azure Cosmos DB”边栏选项卡

    设置 建议的值 说明
    ID 唯一值 标识 Azure Cosmos DB 帐户的唯一名称。 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一但可识别的 ID。 ID 只能包含小写字母、数字和连字符 (-) 字符,并且必须包含 3 到 50 个字符。
    API SQL (DocumentDB) 在本文的后面部分中,我们将针对 DocumentDB API 编程。
    订阅 你的订阅 要用于 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 与 ID 相同的值 帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    位置 离你的用户最近的区域 要在其中托管 Azure Cosmos DB 帐户的地理位置。 选择离用户最近的位置,使他们能够以最快的速度访问数据。
  4. 单击“创建” 以创建帐户。
  5. 在顶部工具栏上,单击“通知”可监视部署过程。

    Azure 门户“通知”窗格

  6. 部署完成后,请从“所有资源”磁贴打开新帐户。

    “所有资源”磁贴中的 DocumentDB 帐户

添加集合

现在可以使用数据资源管理器创建一个集合,并将数据添加到数据库。

  1. 在 Azure 门户的左侧导航菜单中,单击“数据资源管理器(预览版)”。

  2. 在“数据资源管理器(预览版)”边栏选项卡中,单击“新建集合”,然后提供以下信息:

    Azure 门户“数据资源管理器”边栏选项卡

    设置 建议的值 说明
    数据库 ID 任务 新数据库的 ID。 数据库名称必须包含 1 到 255 个字符,不能包含 /、\、#、? 或尾随空格。
    集合 ID Items 新集合的 ID。 集合名称与数据库 ID 的字符要求相同。
    存储容量 固定 (10 GB) 使用默认值。 这是数据库的存储容量。
    吞吐量 400 RU 使用默认值。 如果想要减少延迟,以后可以增加吞吐量。
    RU/m 关闭 保留默认值。 如果以后需要处理高峰工作负荷,则可到时候启用 RU/m 功能。
    分区键 /category 一个分区键,用于将数据均匀分配到每个分区。 选择正确的分区键对于创建高性能集合而言很重要。 若要了解详细信息,请参阅设计分区
  3. 完成表单后,单击“确定”。

克隆示例应用程序

现在,我们从 github 克隆 DocumentDB API 应用、设置连接字符串,并运行该应用。 你会看到以编程方式处理数据是多么容易。

  1. 打开 git 终端窗口(例如 git bash)并使用 CD 切换到工作目录。

  2. 运行下列命令,克隆示例存储库。

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

查看代码

快速查看应用中发生的情况。 打开 Program.java 文件,查找用于创建 Azure Cosmos DB 资源的代码行。

  • DocumentClient 进行初始化。

    this.client = new DocumentClient("https://FILLME.documents.azure.cn",
            "FILLME", 
            new ConnectionPolicy(),
            ConsistencyLevel.Session);
    
  • 会创建一个新数据库。

    Database database = new Database();
    database.setId(databaseName);
    
    this.client.createDatabase(database, null);
    
  • 创建一个新集合。

    DocumentCollection collectionInfo = new DocumentCollection();
    collectionInfo.setId(collectionName);
    
    // DocumentDB collections can be reserved with throughput
    // specified in request units/second. 1 RU is a normalized
    // request equivalent to the read of a 1KB document. Here we
    // create a collection with 400 RU/s.
    RequestOptions requestOptions = new RequestOptions();
    requestOptions.setOfferThroughput(400);
    
    this.client.createCollection(databaseLink, collectionInfo, requestOptions);
    
  • 此时会创建一些文档。

    // 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);
    this.client.createDocument(collectionLink, family, new RequestOptions(), true);
    
  • 对 JSON 执行 SQL 查询。

    FeedOptions queryOptions = new FeedOptions();
    queryOptions.setPageSize(-1);
    queryOptions.setEnableCrossPartitionQuery(true);
    
    String collectionLink = String.format("/dbs/%s/colls/%s", databaseName, collectionName);
    FeedResponse<Document> queryResults = this.client.queryDocuments(
        collectionLink,
        "SELECT * FROM Family WHERE Family.lastName = 'Andersen'", queryOptions);
    
    System.out.println("Running SQL query...");
    for (Document family : queryResults.getQueryIterable()) {
        System.out.println(String.format("\tRead %s", family));
    }
    

更新连接字符串

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。

  1. Azure 门户的 Azure Cosmos DB 帐户的左侧导航栏中,单击“密钥”,然后单击“读写密钥”。 使用屏幕右侧的复制按钮将 URI 和主密钥复制到下一步的 Program.java 文件中。

    在 Azure 门户的“密钥”边栏选项卡中查看并复制访问密钥

  2. 打开 Program.java 文件。

  3. 从门户中复制 URI 值(使用复制按钮),并在 Program.java 的 DocumentClient 构造函数中将其设为终结点的值。

    "https://FILLME.documents.azure.cn"

  4. 然后从门户复制“主密钥”的值,并将第二个参数“FILL ME”替换为 Program.java 的 DocumentClient 构造函数中的密钥。 现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

运行应用程序

  1. 在终端中运行 mvn package,安装所需的 Java 包。

  2. 在终端中运行 mvn exec:java -D exec.mainClass=GetStarted.Program,启动 Java 应用程序。

现可返回到数据资源管理器,查看查询、修改和处理此新数据。

在 Azure 门户中查看 SLA

现在,应用已启动且正在运行,建议确保业务连续性并监视用户访问以确保高可用性。 可以使用 Azure 门户查看集合的可用性、延迟、吞吐量和一致性。

Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图均提供一行内容,显示满足 SLA 所需的配额和实际使用情况,从而让你清楚地了解数据库性能。 门户中还提供其他指标,例如存储使用量和每分钟的请求数。

  • 在 Azure 门户的左侧窗格中,单击“监视”下的“指标”。

    包含示例数据的待办事项应用

清理资源

如果不打算继续使用此应用,请删除本快速入门教程在 Azure 门户中创建的所有资源,步骤如下:

  1. 在 Azure 门户的左侧菜单中,单击“资源组”,然后单击已创建资源的名称。
  2. 在资源组页上单击“删除”,在文本框中键入要删除的资源的名称,并单击“删除”。

后续步骤

在本快速入门教程中,已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建集合和运行应用。 现在可以将其他数据导入 Cosmos DB 帐户。