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

Tip

Azure Cosmos DB DocumentDB API 或 SQL (DocumentDB) API 现在称为 Azure Cosmos DB SQL API。 无需进行任何更改即可继续运行使用 DocumentDB API 构建的应用。 功能保持相同。

Azure Cosmos DB 由 21Vianet 提供,是多个区域分布的多模型数据库服务。 使用 Azure Cosmos DB,可以快速创建和查询托管文档和表。

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

先决条件

Note

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

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

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

此外:

  • 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。

创建数据库帐户

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

  1. 在新浏览器窗口中,登录到 Azure 门户
  2. 单击“新建” > “数据库” > “Azure Cosmos DB”。

    Azure 门户“数据库”窗格

  3. 在“新建帐户”页上,输入新 Azure Cosmos DB 帐户的设置。

    设置 建议的值 说明
    ID 输入唯一名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 由于 documents.azure.cn 将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一但可识别的 ID。

    ID 只能包含小写字母、数字和连字符 (-) 字符,并且必须包含 3 到 50 个字符。
    API SQL API 确定要创建的帐户的类型。 Azure Cosmos DB 提供了三种 API,用于满足应用程序的需求:SQL(文档数据库)、MongoDB(文档数据库)和 Azure 表,每个目前都需要单独的帐户。

    之所以选择 SQL 是因为,在本快速入门中将创建可使用 SQL 语法查询并可通过 SQL API 访问的文档数据库。

    详细了解 SQL API
    订阅 订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 新建

    然后输入上面在 ID 中提供的同一唯一名称
    选择“新建”,然后输入帐户的新资源组名称。 为简单起见,可以使用与 ID 相同的名称。
    位置 选择离用户最近的区域 选择要在其中托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    启用异地冗余 留空 这将在第二个(配对)区域中创建数据库的复制版本。 将此项留空。
    固定到仪表板 选择 选中此框,以便将新的数据库帐户添加到门户仪表板以便于访问。

    然后单击“创建” 。

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

  4. 创建帐户需要几分钟时间。 在创建帐户过程中,门户会在右侧显示“部署 Azure Cosmos DB”磁贴,可能需要向右滚动仪表板才能看到此磁贴。 另外,还会在屏幕顶部附近显示进度条。 你可以查看任一区域来了解进度。

    Azure 门户“通知”窗格

    创建帐户后,会显示“祝贺你!已创建 Azure Cosmos DB 帐户”页。

添加集合

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

  1. 单击“数据资源管理器” > “新建集合”。

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

    Azure 门户“数据资源管理器”,“添加集合”边栏选项卡

  2. 在“添加集合”页上,输入新集合的设置。

    设置 建议的值 说明
    数据库 ID 任务 输入 Tasks 作为新数据库的名称。 数据库名称必须包含 1 到 255 个字符,不能包含 /、\、#、? 或尾随空格。
    集合 ID Items 输入 Items 作为新集合的名称。 集合 ID 与数据库名称的字符要求相同。
    存储容量 固定 (10 GB) 将值更改为“固定(10GB)”。 此值是数据库的存储容量。
    吞吐量 400 RU 将吞吐量更改为每秒 400 个请求单位 (RU/s)。 存储容量必须设置为“固定(10 GB)”,才能将吞吐量设置为 400 RU/s。 如果想要减少延迟,以后可以增加吞吐量。

    单击 “确定”

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

    显示新的数据库和集合的 Azure 门户数据资源管理器

添加示例数据

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

  1. 展开“项”集合,依次单击“文档” > “新建文档”。

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

  2. 现在,采用以下结构将文档添加到集合中,再单击“保存”。

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    

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

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

查询数据

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

  1. 请注意,查询默认设置为 SELECT * FROM c。 此默认查询检索并显示集合中的所有文档。

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

  2. 单击“编辑筛选器”按钮,将 ORDER BY c._ts DESC 添加到查询谓词框中,再单击“应用筛选器”,从而更改查询。

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

此修改后的查询根据文档的时间戳按降序列出文档,所以现在最先列出的是第二个文档。 如果熟悉 SQL 语法,可以在此框中输入任何受支持的 SQL 查询

数据资源管理器中的工作到此结束。 继续处理代码前,请注意,还可以使用数据资源管理器创建存储过程、UDF 和触发器,实现服务器端业务逻辑和缩放吞吐量。 数据资源管理器公开 API 中提供的所有内置编程数据访问,但你可以使用它轻松访问 Azure 门户中的数据。

克隆示例应用程序

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

  1. 打开命令提示符,新建一个名为“git-samples”的文件夹,然后关闭命令提示符。

    md "C:\git-samples"
    
  2. 打开诸如 git bash 之类的 git 终端窗口,并使用 cd 命令更改为要安装示例应用的新文件夹。

    cd "C:\git-samples"
    
  3. 运行下列命令,克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

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

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建数据库资源,可以查看下面的代码段。 这些代码段全部取自 C:\git-samples\azure-cosmos-db-documentdb-java-getting-started\src\GetStarted 文件夹中安装的 Program.java 文件。 否则,可以直接跳转到更新连接字符串

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

    this.client = new DocumentClient("https://FILLME.documents.azure.cn",
            "FILLME", 
            new ConnectionPolicy(),
            ConsistencyLevel.Session);
    
  • Database 创建。

    Database database = new Database();
    database.setId(databaseName);
    
    this.client.createDatabase(database, null);
    
  • DocumentCollection 创建。

    DocumentCollection collectionInfo = new DocumentCollection();
    collectionInfo.setId(collectionName);
    
    ...
    
    this.client.createCollection(databaseLink, collectionInfo, requestOptions);
    
  • 使用 createDocument 方法创建文档。

    // 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);
    
  • 使用 queryDocuments 方法,对 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 门户中,单击“密钥”。

    使用屏幕右侧的“复制”按钮,复制最上面的 URI 值。

    在 Azure 门户的“密钥”页中,查看并复制访问密钥

  2. 打开 C:\git-samples\azure-cosmos-db-documentdb-java-getting-started\src\GetStarted 文件夹中的 Program.java 文件。

  3. 将门户中的 URI 值粘贴到第 45 行上的 https://FILLME.documents.azure.cn

  4. 返回到门户,并复制主密钥值,如屏幕截图所示。 将门户中的主密钥值粘贴到第 46 行上的 FILLME

    现在,getStartedDemo 方法应如下所示:

    private void getStartedDemo() throws DocumentClientException, IOException {
        this.client = new DocumentClient("https://youraccountname.documents.azure.cn:443/",
                "your-primary-key...RJhQrqQ5QQ==", 
                new ConnectionPolicy(),
                ConsistencyLevel.Session);
    
  5. 保存 Program.java 文件。

运行应用程序

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

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

    mvn package
    
  3. 在 git 终端窗口中,使用以下命令启动 Java 应用程序。

    mvn exec:java -D exec.mainClass=GetStarted.Program
    

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

  4. 按任意键创建集合。

  5. 切换到数据资源管理器,此时会看到其中包含 FamilyDB 数据库。

  6. 继续在控制台窗口中按键以使代码创建文档并执行查询。

    在程序结束时,此应用程序的所有资源都会从帐户中删除,这样便不会产生任何费用。

    控制台输出

在 Azure 门户中查看 SLA

在 Azure 门户中监视帐户中资源的吞吐量、存储空间、可用性、延迟和一致性。 让我们快速了解一下这些指标。

  1. 在导航菜单中单击“指标”。

    Azure 门户中的指标

  2. 单击每个选项卡,以便了解 Azure Cosmos DB 提供的指标。

    Azure Cosmos DB 服务级别协议 (SLA) 关联的每个图表都提供了一行,显示是否违反了任何 SLA。 Azure Cosmos DB 通过此套指标使监视 SLA 的操作更透明。

    Azure Cosmos DB 指标套件

清理资源

如果不打算继续使用此应用,请按照以下步骤删除本快速入门中创建的所有资源,以免产生任何费用:

  1. 在 Azure 门户中,选择最左侧的“资源组”。

    Azure 门户中的指标

  2. 在资源组列表中,选择创建的资源组,然后单击“删除资源组”。

  3. 键入要删除的资源组名称,然后单击“删除”。

后续步骤

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