快速入门:使用 Azure Cosmos DB SQL API 帐户生成 Python 应用程序Quickstart: Build a Python application using an Azure Cosmos DB SQL API account

适用于: SQL API

在本快速入门中,你将通过 Azure 门户创建和管理 Azure Cosmos DB SQL API 帐户,并通过 Visual Studio Code 使用从 GitHub 克隆的 Python 应用来添加数据。In this quickstart, you create and manage an Azure Cosmos DB SQL API account from the Azure portal, and from Visual Studio Code with a Python app cloned from GitHub. Azure Cosmos DB 是一种多模型数据库服务,可让你通过多区域分布和水平缩放功能快速创建和查询文档、表、键/值和图数据库。Azure Cosmos DB is a multi-model database service that lets you quickly create and query document, table, key-value, and graph databases with multiple-region distribution and horizontal scale capabilities.


创建数据库帐户Create a database account

  1. 在 Azure 门户菜单或主页中,选择“创建资源” 。From the Azure portal menu or the Home page , select Create a resource.

  2. 在“新建”页面中搜索“Azure Cosmos DB”,然后选择它。 On the New page, search for and select Azure Cosmos DB.

  3. 在“Azure Cosmos DB”页上,选择“创建”。On the Azure Cosmos DB page, select Create.

  4. 在“创建 Azure Cosmos DB 帐户”页上,输入新 Azure Cosmos 帐户的基本设置。On the Create Azure Cosmos DB Account page, enter the basic settings for the new Azure Cosmos account.

    设置Setting Value 说明Description
    订阅Subscription 订阅名称Subscription name 选择要用于此 Azure Cosmos 帐户的 Azure 订阅。Select the Azure subscription that you want to use for this Azure Cosmos account.
    资源组Resource Group 资源组名称Resource group name 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。Select a resource group, or select Create new , then enter a unique name for the new resource group.
    帐户名Account Name 唯一的名称A unique name 输入标识此 Azure Cosmos 帐户的名称。Enter a name to identify your Azure Cosmos account. 由于 documents.azure.cn 将追加到所提供的名称以创建 URI,因此,请使用唯一的名称。Because documents.azure.cn is appended to the name that you provide to create your URI, use a unique name.

    名称只能包含小写字母、数字和连字符 (-)。The name can only contain lowercase letters, numbers, and the hyphen (-) character. 它的长度必须介于 3-44 个字符之间。It must be between 3-44 characters in length.
    APIAPI 要创建的帐户的类型The type of account to create 选择“Core (SQL)”,以便使用 SQL 语法创建文档数据库并进行查询。Select Core (SQL) to create a document database and query by using SQL syntax.

    API 确定要创建的帐户的类型。The API determines the type of account to create. Azure Cosmos DB 提供五种 API:适用于文档数据的 Core (SQL) 和 MongoDB、适用于图形数据的 Gremlin、Azure 表和 Cassandra。Azure Cosmos DB provides five APIs: Core (SQL) and MongoDB for document data, Gremlin for graph data, Azure Table, and Cassandra. 目前,你必须为每种 API 创建单独的帐户。Currently, you must create a separate account for each API.
    容量模式Capacity mode 预配吞吐量或无服务器Provisioned throughput or Serverless 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。Select Provisioned throughput to create an account in provisioned throughput mode. 选择“无服务器”以在无服务器模式下创建帐户。Select Serverless to create an account in serverless mode.

    注意 :无服务器当前仅适用于核心 (SQL) API 帐户。Note : Serverless is currently available for Core (SQL) API accounts only.
    应用免费层折扣Apply Free Tier Discount 应用或不应用Apply or Do not apply 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒的前 400 RU 免费的吞吐量和 5 GB 的免费存储。With Azure Cosmos DB free tier, you will get the first 400 RU/s and 5 GB of storage for free in an account. 了解免费层的详细信息。Learn more about free tier.
    位置Location 离用户最近的区域The region closest to your users 选择用于托管 Azure Cosmos DB 帐户的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用离用户最近的位置,使他们能够以最快的速度访问数据。Use the location that is closest to your users to give them the fastest access to the data.
    帐户类型Account Type 生产或非生产Production or Non-Production 如果帐户将用于生产工作负荷,请选择“生产”。Select Production if the account will be used for a production workload. 如果帐户将用于非生产环境(例如开发、测试、QA 或过渡),请选择“非生产”。Select Non-Production if the account will be used for non-production, e.g. development, testing, QA, or staging. 这是一个 Azure 资源标记设置,用于调整门户体验,但不会影响基础 Azure Cosmos DB 帐户。This is an Azure resource tag setting that tunes the Portal experience but does not affect the underlying Azure Cosmos DB account. 可以随时更改此值。You can change this value anytime.


    每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.


    如果选择“无服务器”作为“容量模式” ,则以下选项不可用:The following options are not available if you select Serverless as the Capacity mode :

    • 应用免费层折扣Apply Free Tier Discount
    • 异地冗余Geo-redundancy
    • 多区域写入Multi-region Writes

    Azure Cosmos DB 的“新建帐户”页面

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

  6. 检查帐户设置,然后选择“创建”。Review the account settings, and then select Create. 创建帐户需要几分钟时间。It takes a few minutes to create the account. 等待门户页显示“你的部署已完成”消息。Wait for the portal page to display Your deployment is complete.

    Azure 门户“通知”窗格

  7. 选择“转到资源”,转到 Azure Cosmos DB 帐户页。Select Go to resource to go to the Azure Cosmos DB account page.

    Azure Cosmos DB 帐户页面

添加容器Add a container

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和容器。You can now use the Data Explorer tool in the Azure portal to create a database and container.

  1. 选择“数据资源管理器” > “新建容器”。 Select Data Explorer > New Container.

    “添加容器”区域显示在最右侧,可能需要向右滚动才能看到它。The Add Container area is displayed on the far right, you may need to scroll right to see it.

    Azure 门户 >“数据资源管理器”>“添加集合”窗格

  2. 在“添加容器”页中,输入新容器的设置。In the Add container page, enter the settings for the new container.

    设置Setting 建议的值Suggested value 说明Description
    数据库 IDDatabase ID 任务Tasks 输入 Tasks 作为新数据库的名称。Enter Tasks as the name for the new database. 数据库名称必须包含 1 到 255 个字符,不能包含 /, \\, #, ? 或尾随空格。Database names must contain from 1 through 255 characters, and they cannot contain /, \\, #, ?, or a trailing space. 选中“预配数据库吞吐量”选项,这样就可以在数据库中的所有容器之间共享预配给该数据库的吞吐量。Check the Provision database throughput option, it allows you to share the throughput provisioned to the database across all the containers within the database. 此选项还有助于节省成本。This option also helps with cost savings.
    吞吐量Throughput 400400 将吞吐量保留为每秒 400 个请求单位 (RU/s)。Leave the throughput at 400 request units per second (RU/s). 如果想要减少延迟,以后可以增加吞吐量。If you want to reduce latency, you can scale up the throughput later.
    容器 IDContainer ID ItemsItems 输入 Items 作为新容器的名称。Enter Items as the name for your new container. 容器 ID 与数据库名称的字符要求相同。Container IDs have the same character requirements as database names.
    分区键Partition key /category/category 本文中所述的示例使用 /category 作为分区键。The sample described in this article uses /category as the partition key.

    除了前面的设置,还可以选择为容器添加“唯一键”。In addition to the preceding settings, you can optionally add Unique keys for the container. 在此示例中,请将此字段留空。Let's leave the field empty in this example. 开发人员可以使用唯一键向数据库添加一层数据完整性。Unique keys provide developers with the ability to add a layer of data integrity to the database. 创建容器时,通过创建唯一键策略,可确保每个分区键的一个或多个值的唯一性。By creating a unique key policy while creating a container, you ensure the uniqueness of one or more values per partition key. 若要了解详细信息,请参阅 Azure Cosmos DB 中的唯一键一文。To learn more, refer to the Unique keys in Azure Cosmos DB article.

    选择“确定”。Select OK. 数据资源管理器将显示新的数据库和容器。The Data Explorer displays the new database and container.

添加示例数据Add sample data

现在可以使用数据资源管理器将数据添加到新容器。You can now add data to your new container using Data Explorer.

  1. 在“数据资源管理器”中展开“Tasks”数据库,然后展开“Items”容器。From the Data Explorer, expand the Tasks database, expand the Items container. 依次选择“项”、“新建项”。Select Items, and then select New Item.

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

  2. 现在,将文档添加到具有以下结构的容器。Now add a document to the container with the following structure.

        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
  3. 将 json 添加到“文档”选项卡以后,即可选择“保存”。Once you've added the json to the Documents tab, select Save.

    通过复制添加 JSON 数据,然后在 Azure 门户上的数据资源管理器中选择“保存”

  4. 再创建并保存一个文档,在其中插入 id 属性的唯一值,并将其他属性更改为适当值。Create and save one more document where you insert a unique value for the id property, and change the other properties as you see fit. 新文档可以具有所需的任何结构,因为 Azure Cosmos DB 不对数据施加任何架构。Your new documents can have any structure you want as Azure Cosmos DB doesn't impose any schema on your data.

查询数据Query your data

可以在数据资源管理器中使用查询来检索和筛选数据。You can use queries in Data Explorer to retrieve and filter your data.

  1. 在数据资源管理器的“项”选项卡顶部,查看默认查询 SELECT * FROM cAt the top of the Items tab in Data Explorer, review the default query SELECT * FROM c. 此查询检索并显示容器中按 ID 排序的所有文档。This query retrieves and displays all documents from the container ordered by ID.

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

  2. 若要更改查询,请选择“编辑筛选器”,将默认查询替换为 ORDER BY c._ts DESC,然后选择“应用筛选器”。To change the query, select Edit Filter, replace the default query with ORDER BY c._ts DESC, and then select Apply Filter.

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

    此修改后的查询根据文档的时间戳按降序显示文档,所以现在最先列出的是第二个文档。The modified query displays the documents in descending order based on their time stamp, so now your second document is listed first.

    将查询更改为 ORDER BY c._ts DESC,然后单击“应用筛选器”

如果熟悉 SQL 语法,可以在查询谓词框中输入任何受支持的 SQL 查询If you're familiar with SQL syntax, you can enter any supported SQL queries in the query predicate box. 还可以使用数据资源管理器创建存储过程、UDF 和触发器以执行服务器端业务逻辑。You can also use Data Explorer to create stored procedures, UDFs, and triggers for server-side business logic.

数据资源管理器可以通过 Azure 门户轻松访问 API 中提供的所有内置编程数据访问功能。Data Explorer provides easy Azure portal access to all of the built-in programmatic data access features available in the APIs. 也可通过门户缩放吞吐量、获取密钥和连接字符串,以及查看 Azure Cosmos DB 帐户的指标和 SLA。You also use the portal to scale throughput, get keys and connection strings, and review metrics and SLAs for your Azure Cosmos DB account.

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

现在,让我们从 GitHub 中克隆一个 SQL API 应用,设置连接字符串,然后运行该应用。Now let's clone a SQL API app from GitHub, set the connection string, and run it. 本快速入门使用 Python SDK 版本 4。This quickstart uses version 4 of the Python SDK.

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

    md "git-samples"

    如果使用的是 bash 提示符,则应当改用以下命令:If you are using a bash prompt, you should instead use the following command:

    mkdir "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 "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/azure-cosmos-db-python-getting-started.git

更新连接字符串Update your connection string

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。Now go back to the Azure portal to get your connection string information and copy it into the app.

  1. Azure 门户中,在你的 Azure Cosmos DB 帐户中,选择左侧导航栏中的“密钥”。In your Azure Cosmos DB account in the Azure portal, select Keys from the left navigation. 使用屏幕右侧的复制按钮将 URI主密钥 复制到下一步的 cosmos_get_started.py 文件中。Use the copy buttons on the right side of the screen to copy the URI and Primary Key into the cosmos_get_started.py file in the next step.

    在 Azure 门户的“密钥”设置中获取访问密钥和 URI

  2. 在 Visual Studio Code 中,打开 \git-samples\azure-cosmos-db-python-getting-started 中的 cosmos_get_started.py 文件。In Visual Studio Code, open the cosmos_get_started.py file in \git-samples\azure-cosmos-db-python-getting-started.

  3. 从门户中复制你的 URI 值(使用复制按钮),并在 cosmos_get_started.py 中将其设为 endpoint 变量的值。Copy your URI value from the portal (using the copy button) and make it the value of the endpoint variable in cosmos_get_started.py.

    endpoint = 'https://FILLME.documents.azure.cn',

  4. 然后从门户复制“主密钥”值,并在 cosmos_get_started.py 中将其设为 key 的值。Then copy your PRIMARY KEY value from the portal and make it the value of the key in cosmos_get_started.py. 现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

    key = 'FILLME'

  5. 保存 cosmos_get_started.py 文件。Save the cosmos_get_started.py file.

查看代码Review the code

此步骤是可选的。This step is optional. 了解在代码中创建的数据库资源,或者跳转到更新连接字符串Learn about the database resources created in code, or skip ahead to Update your connection string.

以下代码片段全部摘自 cosmos_get_started.py 文件。The following snippets are all taken from the cosmos_get_started.py file.

  • 对 CosmosClient 进行初始化。The CosmosClient is initialized. 请务必根据更新连接字符串部分中所述更新“endpoint”和“key”值。Make sure to update the "endpoint" and "key" values as described in the Update your connection string section.

    client = CosmosClient(endpoint, key)
  • 将创建一个新数据库。A new database is created.

    database_name = 'AzureSampleFamilyDatabase'
    database = client.create_database_if_not_exists(id=database_name)
  • 将创建一个预配吞吐量为 400 RU/秒的新容器。A new container is created, with 400 RU/s of provisioned throughput. 选择 lastName 作为分区键,这可以按属性进行筛选并执行有效的查询。We choose lastName as the partition key, which allows us to do efficient queries that filter on this property.

    container_name = 'FamilyContainer'
    container = database.create_container_if_not_exists(
  • 向容器中添加一些项。Some items are added to the container. 容器是项(JSON 文档)的集合,这些项可以采用不同的架构。Containers are a collection of items (JSON documents) that can have varied schema. 帮助器方法 get_[name]_family_item 返回 Azure Cosmos DB 中作为 JSON 文档存储的家族表示形式。The helper methods get_[name]_family_item return representations of a family that are stored in Azure Cosmos DB as JSON documents.

    for family_item in family_items_to_create:
  • 使用 read_item 方法执行点读取(键值查找)。Point reads (key value lookups) are performed using the read_item method. 我们将输出每个操作的 RU 费用We print out the RU charge of each operation.

    for family in family_items_to_create:
        item_response = container.read_item(item=family['id'], partition_key=family['lastName'])
        request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
        print('Read item with id {0}. Operation consumed {1} request units'.format(item_response['id'], (request_charge)))
  • 使用 SQL 查询语法执行查询。A query is performed using SQL query syntax. 由于我们在 WHERE 子句中使用 lastName 的分区键值,因此 Azure Cosmos DB 会有效地将此查询路由到相关分区,从而提高性能。Because we're using partition key values of lastName in the WHERE clause, Azure Cosmos DB will efficiently route this query to the relevant partitions, improving performance.

    query = "SELECT * FROM c WHERE c.lastName IN ('Wakefield', 'Andersen')"
    items = list(container.query_items(
    request_charge = container.client_connection.last_response_headers['x-ms-request-charge']
    print('Query returned {0} items. Operation consumed {1} request units'.format(len(items), request_charge))

运行应用Run the app

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

  2. 在提示符处,输入 Python:Select Interpreter,然后选择要使用的 Python 的版本。At the prompt, enter Python: Select Interpreter and then select the version of Python to use.

    Visual Studio Code 中的页脚将更新以指示所选的解释器。The Footer in Visual Studio Code is updated to indicate the interpreter selected.

  3. 选择“视图” > “集成终端”以打开 Visual Studio Code 集成终端。 Select View > Integrated Terminal to open the Visual Studio Code integrated terminal.

  4. 在集成的终端窗口中,确保位于 azure-cosmos-db-python-getting-started 文件夹中。In the integrated terminal window, ensure you are in the azure-cosmos-db-python-getting-started folder. 如果没有位于该文件夹中,请运行以下命令来切换到示例文件夹。If not, run the following command to switch to the sample folder.

    cd "\git-samples\azure-cosmos-db-python-getting-started"`
  5. 运行以下命令来安装 azure-cosmos 程序包。Run the following command to install the azure-cosmos package.

    pip install --pre azure-cosmos

    如果尝试安装 azure-cosmos 时收到有关访问被拒绝的错误,则需要以管理员身份运行 VS CodeIf you get an error about access being denied when attempting to install azure-cosmos, you'll need to run VS Code as an administrator.

  6. 运行以下命令来运行示例并将新文档存储在 Azure Cosmos DB 中。Run the following command to run the sample and create and store new documents in Azure Cosmos DB.

    python cosmos_get_started.py
  7. 若要确认是否已创建并保存新项,请在 Azure 门户中选择“数据资源管理器” > “AzureSampleFamilyDatabase” > “项”。 To confirm the new items were created and saved, in the Azure portal, select Data Explorer > AzureSampleFamilyDatabase > Items. 查看创建的项。View the items that were created. 例如,下面是 Andersen 家族的示例 JSON 文档:For example, here is a sample JSON document for the Andersen family:

        "id": "Andersen-1569479288379",
        "lastName": "Andersen",
        "district": "WA5",
        "parents": [
                "familyName": null,
                "firstName": "Thomas"
                "familyName": null,
                "firstName": "Mary Kay"
        "children": null,
        "address": {
            "state": "WA",
            "county": "King",
            "city": "Seattle"
        "registered": true,
        "_rid": "8K5qAIYtZXeBhB4AAAAAAA==",
        "_self": "dbs/8K5qAA==/colls/8K5qAIYtZXc=/docs/8K5qAIYtZXeBhB4AAAAAAA==/",
        "_etag": "\"a3004d78-0000-0800-0000-5d8c5a780000\"",
        "_attachments": "attachments/",
        "_ts": 1569479288

在 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

执行完应用和 Azure Cosmos DB 帐户的操作以后,可以删除所创建的 Azure 资源,以免产生更多费用。When you're done with your 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 Search bar, search for and select Resource groups.

  2. 从列表中选择为本快速入门创建的资源组。From the list, select the resource group you created for this quickstart.


  3. 在资源组“概览”页上,选择“删除资源组” 。On the resource group Overview page, select Delete resource group.


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

后续步骤Next steps

在本快速入门中,你已了解了如何创建 Azure Cosmos DB 帐户,使用数据资源管理器创建容器,以及在 Visual Studio Code 中运行 Python 应用。In this quickstart, you've learned how to create an Azure Cosmos DB account, create a container using the Data Explorer, and run a Python app in Visual Studio Code. 现在可以将其他数据导入 Azure Cosmos DB 帐户了。You can now import additional data to your Azure Cosmos DB account.