Azure Cosmos DB:使用 Java 和 Azure 门户创建文档数据库

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

本快速入门通过适用于 Azure Cosmos DB 的 Azure 门户工具创建文档数据库。 本快速入门还介绍了如何使用 DocumentDB Java API 快速创建 Java 控制台应用。 本快速入门中的说明适用于任何能够运行 Java 的操作系统。 完成本快速入门以后,即可熟悉如何通过 UI 或编程方式创建和修改文档数据库资源,具体取决于你首选哪种方式。

先决条件

  • Java 开发工具包 (JDK) 1.7+
    • 在 Ubuntu 上运行 apt-get install default-jdk,以便安装 JDK。
    • 请确保设置 JAVA_HOME 环境变量,使之指向在其中安装了 JDK 的文件夹。
  • 下载安装 Maven 二进制存档
    • 在 Ubuntu 上,可以通过运行 apt-get install maven 来安装 Maven。
  • Git
    • 在 Ubuntu 上,可以通过运行 sudo apt-get install git 来安装 Git。

Note

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

或者,可以将 Azure Cosmos DB 模拟器用于本教程,该模拟器的 URI 为 https://localhost:8081,密钥为:

C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

创建数据库帐户

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

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

    Azure 门户“数据库”窗格

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

    使用 Azure Cosmos DB,可以选择以下三个编程模型之一:MongoDB、SQL (Cosmos DB) 和表(键/值),每个目前都需要单独的帐户。

    在本快速入门文章中,我们针对 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. 当“通知”窗口指示部署成功后,请关闭通知窗口,然后从仪表板上的“所有资源”磁贴打开新帐户。

    “所有资源”磁贴中的 Azure Cosmos DB 帐户

添加集合

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

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

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

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

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

数据资源管理器显示新的数据库和集合。

添加示例数据

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

  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 不对数据施加任何架构。

    现在可以在数据资源管理器中使用查询来检索数据,只需单击“编辑筛选器”和“应用筛选器”按钮即可。 默认情况下,数据资源管理器使用 SELECT * FROM c 来检索集合中的所有文档,但可以将其更改为其他 SQL 查询(例如 SELECT * FROM c ORDER BY c._ts DESC),根据时间戳按升序返回所有文档。

    还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑和缩放吞吐量。 数据资源管理器公开 API 中提供的所有内置编程数据访问,但你可以使用它轻松访问 Azure 门户中的数据。

克隆示例应用程序

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

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

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

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

查看代码

快速查看应用中发生的情况。 从 \src\GetStarted 文件夹打开 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);
    
    ...
    
    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 和 PRIMARY KEY 复制到下一步的 Program.java 文件中。

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

  2. 在打开的 Program.java 文件中,通过门户复制 URI 值(使用复制按钮),在 Program.java 中将其设为 DocumentClient 构造函数的终结点的值。

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

  3. 然后从门户复制 PRIMARY KEY 值,以粘贴方式替换“FILLME”,使之成为 DocumentClient 构造函数中的第二个参数。 现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

运行应用程序

  1. 在 git 终端窗口中,通过 cd 命令转到 azure-cosmos-db-documentdb-java-getting-started 文件夹。

  2. 在 git 终端窗口键入 mvn package,安装所需的 Java 包。

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

    在终端窗口中会出现通知,指出 FamilyDB 数据库已创建,按一个键即可继续。 按一个键创建数据库,然后切换到数据资源管理器,此时会看到其中包含 FamilyDB 数据库。 继续按键创建集合和文档,然后执行查询。 项目完成后,资源会从帐户中删除。

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

在 Azure 门户中查看 SLA

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

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

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

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

清理资源

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

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

后续步骤

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