Azure Cosmos DB:使用 Python 和 Azure 门户生成 SQL API 应用

Azure Cosmos DB 是 21Vianet 提供的多区域分布式多模型数据库服务。 可以快速创建和查询文档数据库,这些数据库受益于 Azure Cosmos DB 核心的多区域分布和水平缩放功能。

本快速入门演示如何使用 Azure 门户创建 Azure Cosmos DB SQL API 帐户、文档数据库和容器。 然后使用 SQL API 的 Python SDK 构建并运行控制台应用。 本快速入门使用 3.0 版的 [Python SDK]。(https://pypi.org/project/azure-cosmos)

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

可以使用 URI 为 https://localhost:8081Azure Cosmos DB 模拟器对请求进行身份验证中提供了主密钥。

先决条件

创建数据库帐户

  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(文档数据库)。 每种 API 当前均需要用户创建单独的帐户。

    之所以选择 SQL 是因为本文将使用 SQL 语法创建文档数据库和查询。

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

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

    然后单击“创建” 。

    Azure Cosmos DB 的“新建帐户”页

  4. 创建帐户需要几分钟时间。 等待门户中显示“祝贺你!已创建 Azure Cosmos DB 帐户”页。

    Azure 门户“通知”窗格

添加集合

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

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

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

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

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

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

    除了前面的设置,还可以选择为集合添加“唯一键”。 在此示例中,请将此字段留空。 开发人员可以使用唯一键向数据库添加一层数据完整性。 创建集合时,通过创建唯一键策略,可确保每个分区键的一个或多个值的唯一性。 若要了解详细信息,请参阅 Azure Cosmos DB 中的唯一键一文。

    单击 “确定”

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

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

添加示例数据

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

  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。 此默认查询检索并显示集合中的所有文档。

    数据资源管理器中的默认查询是“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-python-getting-started.git
    

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。 否则,可以直接跳转到更新连接字符串

注意,如果你熟悉旧版 Python SDK,则可能已看惯了术语“集合”和“文档”。 由于 Azure Cosmos DB 支持多 API 模型,因此 3.0+ 版的 Python SDK 使用通用术语“容器”(可能是集合),并使用“项”来描述容器的内容。

以下代码片段全部摘自 CosmosGetStarted.py 文件。

  • 对 CosmosClient 进行初始化。

    # Initialize the Cosmos client
    client = cosmos_client.CosmosClient(url_connection=config['ENDPOINT'], auth={'masterKey': config['MASTERKEY']})
    
  • 会创建一个新数据库。

    # Create a database
    db = client.CreateDatabase({ 'id': config['DATABASE'] })
    
  • 创建一个新集合。

    # Create collection options
    options = {
        'offerThroughput': 400
    }
    
    # Create a container
    container = client.CreateContainer(db['_self'], container_definition, options)
    
  • 向容器中添加一些项。

    # Create and add some items to the container
    item1 = client.CreateItem(container['_self'], {
        'serverId': 'server1',
        'Web Site': 0,
        'Cloud Service': 0,
        'Virtual Machine': 0,
        'message': 'Hello World from Server 1!'
        }
    )
    
    item2 = client.CreateItem(container['_self'], {
        'serverId': 'server2',
        'Web Site': 1,
        'Cloud Service': 0,
        'Virtual Machine': 0,
        'message': 'Hello World from Server 2!'
        }
    )
    
  • 使用 SQL 执行查询

    query = {'query': 'SELECT * FROM server s'}
    
    options = {}
    options['enableCrossPartitionQuery'] = True
    options['maxItemCount'] = 2
    
    result_iterable = client.QueryItems(container['_self'], query, options)
    for item in iter(result_iterable):
        print(item['message'])
    

更新连接字符串

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

  1. Azure 门户 上的 Azure Cosmos DB 帐户中,单击左侧导航栏中的“密钥”。 在下一步骤中你将使用屏幕右侧的复制按钮将 URI主密钥复制到 CosmosGetStarted.py 文件中。

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

  2. 在 Visual Studio Code 中打开 C:\git-samples\azure-cosmos-db-python-getting-started 中的 CosmosGetStarted.py 文件。

  3. 从门户中复制 URI 值(使用复制按钮),并在 CosmosGetStarted.py 中将其设为终结点密钥的值。

    'ENDPOINT': 'https://FILLME.documents.azure.cn',

  4. 然后从门户复制“主密钥”的值,并在 DocumentDBGetStarted.py 中将其设为 config.MASTERKEY 的值。 现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

    'PRIMARYKEY': 'FILLME',

  5. 保存 CosmosGetStarted.py 文件。

运行应用程序

  1. 在 Visual Studio Code 中,选择“视图”>“命令面板”。

  2. 在提示符下输入 Python: Select Interpreter,然后选择要使用的 Python 版本。

    Visual Studio Code 中的“页脚”会更新,以指示选定的解释器。

  3. 选择“视图” > “集成终端”以打开 Visual Studio Code 集成终端。

  4. 在集成的终端窗口中,确保位于 azure-cosmos-db-python-getting-started 文件夹中。 如果不是,请运行以下命令切换到该文件夹。

    cd "C:\git-samples\azure-cosmos-db-python-getting-started"`
    
  5. 运行以下命令来安装 azure-cosmos 程序包。

    pip3 install azure-cosmos
    

    如果尝试安装 azure-cosmos 时收到有关访问被拒绝的错误,则需要以管理员身份运行 VS Code

  6. 运行以下命令运行示例,并在 Azure Cosmos DB 中创建和存储新文档。

    python CosmosGetStarted.py
    
  7. 若要确认是否已创建并保存了新项,请在 Azure 门户中选择“数据资源管理器”,展开“列”,展开“文档”,然后选择 server1 文档。 server1 文档内容与集成终端窗口中返回的内容匹配。

    在 Azure 门户中查看新文档

在 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. 在新窗口中选择资源组,然后单击“删除资源组”。

    Azure 门户中的指标

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

后续步骤

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