快速入门:使用 Azure Cosmos DB 的 API for MongoDB 构建 Python 应用Quickstart: Build a Python app using Azure Cosmos DB's API for MongoDB

Azure Cosmos DB 是世纪互联提供的多区域分布式多模型数据库服务。Azure Cosmos DB is 21Vianet's multiple-regionally distributed multi-model database service. 可快速创建和查询文档、键/值和图形数据库,所有这些都受益于 Cosmos DB 核心的多区域分布和水平缩放功能。You can quickly create and query document, key/value, and graph databases, all of which benefit from the multiple-region distribution and horizontal scale capabilities at the core of Cosmos DB.

本快速入门指南使用以下 Flask 示例并演示如何借助 Azure Cosmos DB 模拟器和 Azure Cosmos DB 的用于 MongoDB 的 API 构建简单的待办事项 Flask 应用。This quickstart guide uses the following Flask example and demonstrates how to build a simple To-Do Flask app with the Azure Cosmos DB Emulator and the Azure Cosmos DB's API for MongoDB.


  • 下载 Azure Cosmos DB 模拟器Download the Azure Cosmos DB Emulator. 当前只有 Windows 支持模拟器。The emulator is currently only supported on Windows. 此示例演示如何借助 Azure 中的生产密钥使用示例,此操作可在任何平台上完成。The sample shows how to use the sample with a production key from Azure, which can be done on any platform.

  • 如果尚未安装 Visual Studio Code,可为平台(Windows、Mac、Linux)快速安装 VS CodeIf you don't already have Visual Studio Code installed, you can quickly install VS Code for your platform (Windows, Mac, Linux).

  • 请务必通过安装任一常用 Python 扩展来添加 Python 语言支持。Be sure to add Python Language support by installing one of the popular Python extensions.

    1. 选择扩展。Select an extension.

    2. 通过在命令面板 Ctrl+Shift+P 中键入 ext install 来安装扩展。Install the extension by typing ext install into the Command Palette Ctrl+Shift+P.

      本文档中的示例使用 Don Jayamanne 的常用、全功能型 Python 扩展The examples in this document use Don Jayamanne's popular and full featured Python Extension.

克隆示例应用程序Clone the sample application

现在,请从 GitHub 克隆 Flask-MongoDB 应用、设置连接字符串并运行该应用。Now let's clone a Flask-MongoDB app from GitHub, set the connection string, and run it. 你会看到以编程方式处理数据是多么容易。You see how easy it is to work with data programmatically.

  1. 打开命令提示符,新建一个名为“git-samples”的文件夹,然后关闭命令提示符。Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
  2. 打开诸如 git bash 之类的 git 终端窗口,并使用 cd 命令更改为要安装示例应用的新文件夹。Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
  3. 运行下列命令以克隆示例存储库。Run the following command to clone the sample repository. 此命令在计算机上创建示例应用程序的副本。This command creates a copy of the sample app on your computer.

    git clone https://github.com/Azure-Samples/CosmosDB-Flask-Mongo-Sample.git
  4. 运行以下命令以安装 python 模块。Run the following command to install the python modules.

    pip install -r .\requirements.txt
  5. 在 Visual Studio Code 中打开该文件夹。Open the folder in Visual Studio Code.

查看代码Review the code

此步骤是可选的。This step is optional. 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。If you're interested in learning how the database resources are created in the code, you can review the following snippets. 否则,可以跳到运行 Web 应用Otherwise, you can skip ahead to Run the web app.

以下代码片段全部摘自 app.py 文件,并对本地 Azure Cosmos DB 模拟器使用连接字符串。The following snippets are all taken from the app.py file and uses the connection string for the local Azure Cosmos DB Emulator. 密码需要进行拆分(如下所示)以适应在其他方面无法解析的正斜杠。The password needs to be split up as seen below to accommodate for the forward slashes that cannot be parsed otherwise.

  • 初始化 MongoDB 客户端、检索数据库,并进行身份验证。Initialize the MongoDB client, retrieve the database, and authenticate.

    client = MongoClient("mongodb://") #host uri
    db = client.test    #Select the database
    db.authenticate(name="localhost",password='C2y6yDjf5' + r'/R' + '+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw' + r'/Jw==')
  • 检索集合或创建集合(如果不存在)。Retrieve the collection or create it if it does not already exist.

    todos = db.todo #Select the collection
  • 创建应用程序Create the app

    app = Flask(__name__)
    title = "TODO with Flask"
    heading = "ToDo Reminder"

运行 Web 应用Run the web app

  1. 确保 Azure Cosmos DB 模拟器正在运行。Make sure the Azure Cosmos DB Emulator is running.

  2. 打开终端窗口并使用 cd 切换到保存应用的目录。Open a terminal window and cd to the directory that the app is saved in.

  3. 然后,使用 set FLASK_APP=app.py$env:FLASK_APP = app.py(适用于 PowerShell 编辑器)或 export FLASK_APP=app.py(如果使用的是 Mac)设置 Flask 应用的环境变量。Then set the environment variable for the Flask app with set FLASK_APP=app.py, $env:FLASK_APP = app.py for PowerShell editors, or export FLASK_APP=app.py if you are using a Mac.

  4. 使用 flask run 运行此应用并浏览到 the app with flask run and browse to

  5. 添加和删除任务,并查看集合中添加和更改的任务。Add and remove tasks and see them added and changed in the collection.

创建数据库帐户Create a database account

  1. 在新窗口中,登录到 Azure 门户In a new window, sign in to the Azure portal.

  2. 在左菜单中,依次单击“创建资源”、“数据库”,然后在“Azure Cosmos DB”下单击“创建”。In the left menu, click Create a resource, click Databases, and then under Azure Cosmos DB, click Create.

    Azure 门户的屏幕截图,其中突出显示了“更多服务”和“Azure Cosmos DB”

  3. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos DB 帐户的设置。In the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account.

    设置Setting Value DescriptionDescription
    订阅Subscription 订阅Your subscription 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    资源组Resource Group 新建Create new

    然后输入在 ID 中提供的同一唯一名称Then enter the same unique name as provided in ID
    选择“新建”。Select Create new. 然后输入帐户的新资源组名称。Then enter a new resource-group name for your account. 为简单起见,可以使用与 ID 相同的名称。For simplicity, use the same name as your ID.
    帐户名Account Name 输入唯一的名称Enter a unique name 输入标识此 Azure Cosmos DB 帐户的唯一名称。Enter a unique name to identify your Azure Cosmos DB account. 由于 documents.azure.cn 字符串将追加到所提供的 ID 后面以创建 URI,因此,请使用唯一的 ID。Because documents.azure.cn is appended to the ID that you provide to create your URI, use a unique ID.

    该 ID 只能使用小写字母、数字和连字符 (-) 字符。The ID can use only lowercase letters, numbers, and the hyphen (-) character. 它的长度必须介于 3 到 31 个字符之间。It must be between 3 and 31 characters in length.
    APIAPI Azure Cosmos DB 的用于 MongoDB 的 APIAzure Cosmos DB's API for MongoDB API 确定要创建的帐户的类型。The API determines the type of account to create. Azure Cosmos DB 提供五种 API:适用于文档数据库的 Core (SQL)、适用于图形数据库的 Gremlin、适用于文档数据库的用于 Azure Cosmos DB 的 API MongoDB、Azure 表和 Cassandra。Azure Cosmos DB provides five APIs: Core (SQL) for document databases, Gremlin for graph databases, Azure Cosmos DB's API MongoDB for document databases, Azure Table, and Cassandra. 目前,你必须为每种 API 创建单独的帐户。Currently, you must create a separate account for each API.

    选择“MongoDB”,因为本快速入门将创建使用 MongoDB 的表。Select MongoDB because in this quickstart you are creating a table that works with the MongoDB.
    位置Location 选择离用户最近的区域Select the region closest to your users 选择用于托管 Azure Cosmos DB 帐户的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用离用户最近的位置,使他们能够以最快的速度访问数据。Use the location that's closest to your users to give them the fastest access to the data.

    选择“查看 + 创建”。Select Review+Create. 可以跳过“网络”和“标记”部分。You can skip the Network and Tags section.

    Azure Cosmos DB 的“新建帐户”页

  4. 创建帐户需要几分钟时间。The account creation takes a few minutes. 等待门户中显示“祝贺你!具有 MongoDB 的网络协议兼容性的 Cosmos 帐户已准备就绪”页面。Wait for the portal to display the Congratulations! Your Cosmos account with wire protocol compatibility for MongoDB is ready page.

    Azure 门户“通知”窗格

更新连接字符串Update your connection string

若要针对实时 Cosmos 帐户测试代码,请转到 Azure 门户创建一个帐户,并获取连接字符串信息。If you want to test the code against a live Cosmos Account, go to the Azure portal to create an account and get your connection string information. 然后将其复制到此应用中。Then copy it into the app.

  1. Azure 门户中,在你的 Cosmos 帐户中,在左侧导航栏中单击“连接字符串” ,然后单击“读写密钥” 。In the Azure portal, in your Cosmos account, in the left navigation click Connection String, and then click Read-write Keys. 使用屏幕右侧的复制按钮将用户名、密码和主机复制到下一步的 Dal.cs 文件中。You'll use the copy buttons on the right side of the screen to copy the Username, Password, and Host into the Dal.cs file in the next step.

  2. 在根目录中打开 app.py 文件 。Open the app.py file in the root directory.

  3. 从门户中(使用复制按钮)复制“用户名”值,并在 app.py 文件中将其设为“名称”的值 。Copy your username value from the portal (using the copy button) and make it the value of the name in your app.py file.

  4. 然后从门户中复制“连接字符串”值,并在 app.py 文件中将其设为 MongoClient 值 。Then copy your connection string value from the portal and make it the value of the MongoClient in your app.py file.

  5. 最后从门户复制“密码”值,并在 app.py 文件中将其设为“密码”的值 。Finally copy your password value from the portal and make it the value of the password in your app.py file.

你现在已使用与 Cosmos DB 进行通信所需的所有信息更新了应用。You've now updated your app with all the info it needs to communicate with Cosmos DB. 此时,即可像以前一样运行它。You can run it the same way as before.

“部署到 Azure”Deploy to Azure

若要部署此应用,可在 Azure 中创建新的 Web 应用,并使用此 GitHub 存储库分支启用持续部署。To deploy this app, you can create a new web app in Azure and enable continuous deployment with a fork of this GitHub repo. 按照此教程,在 Azure 中使用 GitHub 设置持续部署。Follow this tutorial to set up continuous deployment with GitHub in Azure.

部署到 Azure 时,应删除应用程序密钥并确保以下部分未被注释掉:When deploying to Azure, you should remove your application keys and make sure the section below is not commented out:

    client = MongoClient(os.getenv("MONGOURL"))
    db = client.test    #Select the database

然后需要将 MONGOURL、MONGO_PASSWORD 和 MONGO_USERNAME 添加到应用程序设置中。You then need to add your MONGOURL, MONGO_PASSWORD, and MONGO_USERNAME to the application settings. 可参阅此教程了解有关 Azure Web 应用中应用程序设置的详细信息。You can follow this tutorial to learn more about Application Settings in Azure Web Apps.


如果打算将代码存储在 GitHub 或其他源代码管理选项中,请务必从代码中删除连接字符串。If you plan to store your code in GitHub or other source control options, please be sure to remove your connection strings from the code. 可改为使用 Web 应用的应用程序设置进行设置。They can be set with application settings for the web app instead.

在 Azure 门户中查看 SLAReview SLAs in the Azure portal

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Azure Cosmos DB 服务级别协议 (SLA) 相关联的指标的图表显示与实际性能对比的 SLA 值。Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. 这套指标使 SLA 监视变得透明。This suite of metrics makes monitoring your SLAs transparent.

若要查看指标和 SLA,请执行以下操作:To review metrics and SLAs:

  1. 在 Cosmos DB 帐户的导航菜单中,选择“指标”。Select Metrics in your Cosmos DB account's navigation menu.

  2. 选择一个选项卡,例如“延迟”,然后在右侧选择一个时间范围。Select a tab such as Latency, and select a timeframe on the right. 比较图表上的“实际值”行和“SLA”行。Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB 指标套件

  3. 查看其他选项卡上的指标。Review the metrics on the other tabs.

清理资源Clean up resources

不再需要 Web 应用和 Azure Cosmos DB 帐户以后,即可删除创建的 Azure 资源,避免产生更多费用。When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. 若要删除资源,请执行以下操作:To delete the resources:

  1. 在 Azure 门户中,选择最左侧的“资源组”。In the Azure portal, select Resource groups on the far left. 如果左侧菜单处于折叠状态,请选择 “展开”按钮 将其展开。If the left menu is collapsed, select Expand button to expand it.

  2. 选择为本快速入门创建的资源组。Select the resource group you created for this quickstart.

    Azure 门户中的指标

  3. 在新窗口中选择“删除资源组”。In the new window, select Delete resource group.

    Azure 门户中的指标

  4. 在下一窗口中键入要删除的资源组的名称,然后选择“删除”。In the next window, type the name of the resource group to delete, and then select Delete.

后续步骤Next steps

在本快速入门中,你已学习了如何创建 Cosmos 帐户和运行 Flask 应用。In this quickstart, you've learned how to create a Cosmos account and run a Flask app. 现在可以向你的 Cosmos 数据库导入更多数据。You can now import additional data to your Cosmos database.