快速入门:开始使用适用于 MongoDB 和 Python 的 Azure Cosmos DB API

适用于:适用于 MongoDB 的 Azure Cosmos DB API

快速入门演示如何:

  1. 创建 Azure Cosmos DB API for MongoDB 帐户
  2. 使用 PyMongo 连接到帐户
  3. 创建示例数据库和集合
  4. 在示例集合中执行 CRUD 操作

运行示例应用的先决条件

  • Python 3.9+(最好使用此推荐版本运行本文中所述的示例代码。 尽管它可能同样适用于更早版本的 Python 3。)
  • 在计算机上安装 PyMongo

创建数据库帐户

  1. 在新浏览器窗口中,登录到 Azure 门户

  2. 在左侧菜单中,选择“创建资源”。

    在 Azure 门户中创建资源的屏幕截图。

  3. 在 "新建" 页上,选择 "数据库" Azure Cosmos DB

    Azure 门户“数据库”窗格的屏幕截图。

  4. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos DB 帐户的设置。

    设置 说明
    订阅 订阅名称 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 资源组名称 选择一个资源组,或者选择“新建”,然后输入新资源组的唯一名称。
    帐户名 输入唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。 帐户 URI 将是追加到唯一帐户名称的“mongo.cosmos.azure.cn” 。

    帐户名称只能使用小写字母、数字及连字符 (-),必须为 3 到 44 个字符长。
    API Azure Cosmos DB for Mongo DB API API 确定要创建的帐户的类型。 选择“Azure Cosmos DB API for MongoDB”,因为本快速入门将创建使用 MongoDB 的集合。 若要了解有关详细信息,请参阅 Azure Cosmos DB API for MongoDB 概述
    位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。

    注意:无服务器帐户仅支持 MongoDB API 版本 4 和 3.6。 选择版本 3.2 将强制帐户处于配置的吞吐量模式。
    应用免费层折扣 “应用”或“不应用” 使用 Azure Cosmos DB 免费层,你将在帐户中获得每秒前 1000 RU 的免费吞吐量和 25 GB 的免费存储。 了解免费层的详细信息。
    版本 选择所需的服务器版本 Azure Cosmos DB API for MongoDB 与 Server 版本 4.0、3.6 和 3.2 兼容。 创建帐户后,可以对其进行升级或降级

    注意

    每个 Azure 订阅最多可以有一个免费层 Azure Cosmos DB 帐户,并且你必须在创建帐户时选择加入使用。 如果看不到用于应用免费层折扣的选项,这意味着订阅中的另一个帐户已启用免费层。

    Azure Cosmos DB“新建帐户”页面的屏幕截图。

  5. 在“全局分发”选项卡中,配置以下详细信息。 对于本快速入门,可以保留默认值:

    设置 说明
    异地冗余 禁用 通过将你的区域与某个配对区域进行配对来启用或禁用帐户的多区域分发。 稍后可以将更多区域添加到帐户。
    多区域写入 禁用 借助多区域写入功能,可以利用全中国的数据库和容器的预配吞吐量。

    注意

    如果选择“无服务器”作为“容量模式”,则以下选项不可用 :

    • 应用免费层折扣
    • 异地冗余
    • 多区域写入
  6. (可选)可以在以下选项卡中配置其他详细信息:

    • 网络 - 配置来自虚拟网络的访问

    • 备份策略 - 配置定期备份策略。

    • 加密 - 使用服务管理的密钥或客户管理的密钥

    • 标记 - 标记是名称/值对,通过将相同的标记应用到多个资源和资源组,可以对资源进行分类并查看合并的账单。

  7. 选择“查看 + 创建”。

  8. 创建帐户需要几分钟时间。 等待门户中显示“祝贺你! Azure Cosmos DB API for MongoDB 帐户已准备就绪”页面。

    Azure 门户“通知”窗格的屏幕截图。

了解对象模型

在继续生成应用程序之前,先研究 API for MongoDB 中资源的层次结构以及用于创建和访问这些资源的对象模型。 API for MongoDB 按以下顺序创建资源:

  • Azure Cosmos DB API for MongoDB 帐户
  • 数据库
  • 集合
  • 文档

若要详细了解实体的层次结构,请参阅 Azure Cosmos DB 资源模型一文。

获取代码

存储库下载示例 Python 代码或使用 git 克隆:

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

检索连接字符串

运行示例代码时,必须输入适用于 MongoDB 的 API 帐户的连接字符串。 请使用以下步骤来查找此字符串:

  1. Azure 门户中,选择你的 Cosmos DB 帐户。

  2. 在左侧导航栏中,选择“连接字符串”,然后选择“读写密钥” 。 将使用屏幕右侧的复制按钮复制主要连接字符串。

警告

切勿将密码或其他敏感数据签入源代码。

运行代码

python run.py

了解应用程序的工作原理

Connecting

下面的代码提示用户输入连接字符串。 最好不要在代码中使用连接字符串,因为它使任何拥有它的人都可以读取或写入你的数据库。

CONNECTION_STRING = getpass.getpass(prompt='Enter your primary connection string: ') # Prompts user for connection string

以下代码为适用于 MongoDB 的 API 创建客户端连接并进行测试以确保其有效。

client = pymongo.MongoClient(CONNECTION_STRING)
try:
    client.server_info() # validate connection string
except pymongo.errors.ServerSelectionTimeoutError:
    raise TimeoutError("Invalid API for MongoDB connection string or timed out when attempting to connect")

创建资源

以下代码创建将用于执行 CRUD 操作的示例数据库和集合。 以编程方式创建资源时,建议使用适用于 MongoDB 的 API 扩展命令(如此处所示),因为这些命令能够设置资源吞吐量 (RU/s) 并配置分片。

可以使用隐式创建的资源,但会默认为吞吐量的建议值,并且不会被分片。

# Database with 400 RU throughput that can be shared across the DB's collections
db.command({'customAction': "CreateDatabase", 'offerThroughput': 400})
 # Creates a unsharded collection that uses the DBs shared throughput
db.command({'customAction': "CreateCollection", 'collection': UNSHARDED_COLLECTION_NAME})

编写文档

下面插入一个示例文档,我们将在整个示例中继续使用该文档。 我们获取其唯一的 _id 字段值,以便可以在后续操作中进行查询。

"""Insert a sample document and return the contents of its _id field"""
document_id = collection.insert_one({SAMPLE_FIELD_NAME: randint(50, 500)}).inserted_id

读取/更新文档

以下将查询、更新和再次查询之前插入的文档。

print("Found a document with _id {}: {}".format(document_id, collection.find_one({"_id": document_id})))

collection.update_one({"_id": document_id}, {"$set":{SAMPLE_FIELD_NAME: "Updated!"}})
print("Updated document with _id {}: {}".format(document_id, collection.find_one({"_id": document_id})))

删除文档

最后,我们将从集合中删除创建的文档。

"""Delete the document containing document_id from the collection"""
collection.delete_one({"_id": document_id})

后续步骤

本快速入门介绍了如何创建适用于 MongoDB 的 API 帐户、使用代码创建数据库和集合,以及执行 CRUD 操作。

尝试为迁移到 Azure Cosmos DB 进行容量计划? 可以使用有关现有数据库群集的信息进行容量规划。