Microsoft Azure Cosmos Python客户端库

导航

已验证详情

这些详情已由PyPI验证
维护者
Avatar for azure-sdk from gravatar.com azure-sdk Avatar for Laurent.Mazuel from gravatar.com Laurent.Mazuel Avatar for microsoft from gravatar.com microsoft

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
分类器

项目描述

免责声明

Azure SDK Python包对Python 2.7的支持已结束，截止日期为2022年1月1日。有关更多信息及问题，请参阅https://github.com/Azure/azure-sdk-for-python/issues/20691

Azure Cosmos DB SQL API Python客户端库

Azure Cosmos DB是一种全球分布式的、多模型数据库服务，支持文档、键值、宽列和图数据库。

使用Azure Cosmos DB SQL API SDK for Python管理此NoSQL数据库服务中的数据库及其包含的JSON文档。高级功能包括

  • 创建Cosmos DB 数据库并修改其设置
  • 创建和修改用于存储JSON文档集合的容器
  • 在您的容器中创建、读取、更新和删除项目（JSON文档）
  • 使用类似SQL的语法查询数据库中的文档

SDK源代码 | 包（PyPI） | 包（Conda） | API参考文档 | 产品文档 | 示例

此SDK用于SQL API。对于所有其他API，请参阅Azure Cosmos DB文档以评估最适合您项目的SDK。

入门

关于Python 2.x支持的最新更新

此SDK的新版本将从2022年1月1日起不再支持Python 2.x。请查阅变更日志获取更多信息。

先决条件

如果您需要Cosmos DB SQL API账户，可以使用此Azure CLI命令创建

az cosmosdb create --resource-group <resource-group-name> --name <cosmos-account-name>

安装包

pip install azure-cosmos

配置虚拟环境（可选）

虽然不是必需的，但您可以使用虚拟环境将基本系统和Azure SDK环境隔离开来。执行以下命令进行配置，然后使用venv进入虚拟环境

python3 -m venv azure-cosmosdb-sdk-environment
source azure-cosmosdb-sdk-environment/bin/activate

验证客户端

Cosmos DB的交互从CosmosClient类的实例开始。您需要一个账户、其URI和其任一账户密钥来实例化客户端对象。

使用以下Azure CLI片段将数据库账户URI和其主密钥填充到两个环境变量中（您也可以在Azure门户中找到这些值）。片段格式为Bash shell。

RES_GROUP=<resource-group-name>
ACCT_NAME=<cosmos-db-account-name>

export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv)
export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv)

创建客户端

一旦填充了ACCOUNT_URI和ACCOUNT_KEY环境变量，您就可以创建CosmosClient。

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

AAD身份验证

您还可以使用服务主体的AAD凭据和azure identity包对客户端进行身份验证。您可以直接将凭据信息传递给ClientSecretCredential，或使用DefaultAzureCredential

from azure.cosmos import CosmosClient
from azure.identity import ClientSecretCredential, DefaultAzureCredential

import os
url = os.environ['ACCOUNT_URI']
tenant_id = os.environ['TENANT_ID']
client_id = os.environ['CLIENT_ID']
client_secret = os.environ['CLIENT_SECRET']

# Using ClientSecretCredential
aad_credentials = ClientSecretCredential(
    tenant_id=tenant_id,
    client_id=client_id,
    client_secret=client_secret)

# Using DefaultAzureCredential (recommended)
aad_credentials = DefaultAzureCredential()

client = CosmosClient(url, aad_credentials)

请始终确保您用于AAD身份验证的管理身份具有readMetadata权限。
有关如何设置AAD身份验证的更多信息：设置RBAC以进行AAD身份验证
有关AAD认证客户端允许的操作的更多信息：RBAC权限模型

关键概念

初始化CosmosClient后，您可以与Cosmos DB中的主要资源类型进行交互

  • 数据库：一个Cosmos DB账户可以包含多个数据库。创建数据库时，您指定交互其文档时希望使用的API：SQL、MongoDB、Gremlin、Cassandra或Azure Table。使用DatabaseProxy对象来管理其容器。

  • 容器：容器是一组JSON文档。您通过在ContainerProxy对象上使用方法来创建（插入）、读取、更新和删除容器中的项目。

  • 项目：项目是存储在容器中的JSON文档的类似字典的表示。您添加到容器的每个项目都必须包含一个具有唯一标识项目在容器内的值的id键。

有关这些资源的更多信息，请参阅使用Azure Cosmos数据库、容器和项目。

如何使用enable_cross_partition_query

关键字参数enable_cross_partition_query接受2个选项：None（默认）或True。

关于按id使用查询的说明

当使用尝试根据id值查找项目的查询时，请始终确保您传递的是字符串类型变量。Azure Cosmos DB仅允许字符串id值，如果您使用任何其他数据类型，此SDK将返回无结果且无错误消息。

关于客户端一致性级别的说明

截至版本4.3.0b3的发布，如果用户没有在客户端初始化时传递显式的一致性级别，则他们的客户端将使用数据库账户的默认级别。以前，默认级别被设置为Session一致性。如果出于某种原因您想继续这样做，您可以更改您的客户端初始化以包括此显式参数，如下所示

from azure.cosmos import CosmosClient

import os
URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY, consistency_level='Session')

限制

目前，以下功能不受支持。有关替代方案，请参阅下面的解决方案部分。

数据平面限制

  • GROUP BY查询
  • 具有COUNT从DISTINCT子查询的查询：SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
  • 直接TCP模式访问
  • 对像排序、计数和distinct这样的聚合跨分区查询的续传令牌支持。像SELECT * FROM WHERE这样的流式查询也支持续传令牌。
  • 更改流：处理器
  • 更改流：读取多个分区键值
  • 混合类型的跨分区ORDER BY
  • 启用异步查询类型方法的诊断

控制平面限制

  • 获取CollectionSizeUsage、DatabaseUsage和DocumentUsage指标
  • 创建地理空间索引
  • 获取连接字符串
  • 获取容器的最小RU/s

解决方案

控制平面限制的解决方案

通常，您可以使用Azure Portal、Azure Cosmos DB Resource Provider REST API、Azure CLI或PowerShell来处理控制平面不支持的限制。

使用异步客户端作为大量操作的解决方案

虽然SDK支持事务性批处理，但Python SDK中尚未实现对大量请求的支持。您可以使用异步客户端以及我们开发的此并发示例作为可能的解决方案的参考。

[警告]像此示例中这样使用异步客户端进行并发操作将非常快地消耗大量的RU。我们强烈建议首先在cosmos模拟器上测试此功能，以验证您的代码是否正常工作并避免产生费用。

布尔数据类型

虽然Python语言使用 "True"和"False"作为布尔类型，但Cosmos DB仅接受 "true"和"false"。换句话说，Python语言使用布尔值，其中第一个字母为大写，其余字母为小写，而Cosmos DB及其SQL语言仅使用小写字母表示相同的布尔值。如何应对这一挑战？

  • 使用Python创建的JSON文档必须使用"True"和"False"，以通过语言验证。SDK将为您将其转换为"true"和"false"。这意味着在Cosmos DB中存储的是"true"和"false"。
  • 如果您使用Cosmos DB门户的数据资源管理器检索这些文档，您将看到"true"和"false"。
  • 如果您使用此Python SDK检索这些文档，"true"和"false"值将自动转换为"True"和"False"。

SQL查询的FROM子句子项

此SDK使用query_items方法向Azure Cosmos DB提交SQL查询。

Cosmos DB SQL语言允许您使用FROM子句获取子项，以减少源为更小的子集。例如，您可以使用select * from Families.children而不是select * from Families。但请注意：

  • 对于使用query_items方法的SQL查询，此SDK要求您指定partition_key或使用enable_cross_partition_query标志。
  • 如果您正在检索子项并指定partition_key，请确保您的分区键包含在子项中，这在大多数情况下是不正确的。

最大项目数

这是query_items方法的参数，一个表示每页要返回的最大项目数的整数。可以指定None值以让服务确定最佳项目数。这是推荐配置值，也是此SDK在未设置时的默认行为。

示例

以下部分提供了几个代码片段，涵盖了Cosmos DB的一些最常见任务，包括

创建数据库

在认证您的CosmosClient后，您可以处理账户中的任何资源。下面的代码片段创建了一个SQL API数据库，这是在调用create_database时未指定API时的默认操作。

from azure.cosmos import CosmosClient, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
try:
    database = client.create_database(DATABASE_NAME)
except exceptions.CosmosResourceExistsError:
    database = client.get_database_client(DATABASE_NAME)

创建容器

此示例创建了一个具有默认设置的容器。如果数据库中已存在具有相同名称的容器（生成409 冲突错误），则将获取现有容器。

from azure.cosmos import CosmosClient, PartitionKey, exceptions
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'

try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

创建启用分析存储的容器

此示例创建了一个启用分析存储的容器，用于报告、BI、AI和高级分析，以及Azure Synapse Link。

analytical_storage_ttl的选项有：

  • 0或Null或未提供：未启用。
  • -1：数据将无限期存储。
  • 任何其他数字：实际的ttl，以秒为单位。
CONTAINER_NAME = 'products'
try:
    container = database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1)
except exceptions.CosmosResourceExistsError:
    container = database.get_container_client(CONTAINER_NAME)
except exceptions.CosmosHttpResponseError:
    raise

前面的片段还处理了CosmosHttpResponseError异常，如果容器创建失败。有关错误处理和故障排除的更多信息，请参阅故障排除部分。

获取现有容器

从数据库中检索现有容器

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

插入数据

要将项目插入到容器中，请将包含您的数据的字典传递给ContainerProxy.upsert_item。您添加到容器中的每个项目都必须包含一个id键，其值唯一标识容器内的项目。

此示例将几个项目插入到容器中，每个项目都有一个唯一的id

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for i in range(1, 10):
    container.upsert_item({
            'id': 'item{0}'.format(i),
            'productName': 'Widget',
            'productModel': 'Model {0}'.format(i)
        }
    )

删除数据

要从容器中删除项目，请使用ContainerProxy.delete_item。Cosmos DB的SQL API不支持SQL的DELETE语句。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

for item in container.query_items(
        query='SELECT * FROM products p WHERE p.productModel = "Model 2"',
        enable_cross_partition_query=True):
    container.delete_item(item, partition_key='Widget')

注意：如果您正在使用分区集合，则示例代码中partitionKey的值应设置为该特定项目的分区键值，而不是您的集合中分区键列的名称。这对于点读取和删除都适用。

查询数据库

Cosmos DB SQL API数据库支持使用类似SQL的语法通过ContainerProxy.query_items查询容器中的项目。

此示例查询具有特定id的容器。

from azure.cosmos import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

# Enumerate the returned items
import json
for item in container.query_items(
        query='SELECT * FROM mycontainer r WHERE r.id="item3"',
        enable_cross_partition_query=True):
    print(json.dumps(item, indent=True))

注意：尽管您可以在FROM子句中指定任何容器名称，但我们建议您使用容器名称以保持一致性。

通过传递包含参数及其值的字典到ContainerProxy.query_items来执行参数化查询。

discontinued_items = container.query_items(
    query='SELECT * FROM products p WHERE p.productModel = @model',
    parameters=[
        dict(name='@model', value='Model 7')
    ],
    enable_cross_partition_query=True
)
for item in discontinued_items:
    print(json.dumps(item, indent=True))

有关使用SQL API查询Cosmos DB数据库的更多信息，请参阅使用SQL查询查询Azure Cosmos DB数据。

获取数据库属性

获取并显示数据库的属性。

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
properties = database.read()
print(json.dumps(properties))

获取数据库和容器吞吐量

获取并显示数据库和具有专用吞吐量的容器的吞吐量值。

from azure.cosmos import CosmosClient
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)

# Database
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
db_offer = database.read_offer()
print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.format(db_offer.properties['id'], database.id, db_offer.properties['content']['offerThroughput']))

# Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)
container_offer = container.read_offer()
print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput']))

修改容器属性

可以修改现有容器的某些属性。此示例将容器中项目的默认生存时间（TTL）设置为10秒。

from azure.cosmos import CosmosClient, PartitionKey
import os
import json

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

database.replace_container(
    container,
    partition_key=PartitionKey(path="/productName"),
    default_ttl=10,
)
# Display the new TTL setting for the container
container_props = container.read()
print(json.dumps(container_props['defaultTtl']))

有关TTL的更多信息，请参阅Azure Cosmos DB数据的生存时间。

使用异步客户端

异步cosmos客户端是一个独立的客户端，其外观和工作方式与现有的同步客户端类似。然而，异步客户端需要单独导入，并且其方法需要使用async/await关键字。异步客户端在使用后需要初始化和关闭，这可以通过手动操作或使用上下文管理器来完成。下面的示例展示了如何手动完成这些操作。我们不推荐这种方式，因为它需要在使用客户端之前手动调用aenter()。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'    

async def create_products():
    client = CosmosClient(URL, credential=KEY)
    await client.__aenter__() # this piece is important for the SDK to cache account information
    database = client.get_database_client(DATABASE_NAME)
    container = database.get_container_client(CONTAINER_NAME)
    for i in range(10):
        await container.upsert_item({
                'id': 'item{0}'.format(i),
                'productName': 'Widget',
                'productModel': 'Model {0}'.format(i)
            }
        )
    await client.close() # the async client must be closed manually if it's not initialized in a with statement

为了避免手动打开和关闭客户端，强烈建议使用async with关键字。这会创建一个上下文管理器，它将在您离开语句后初始化并关闭客户端，以及缓存SDK需要的有关信息。下面的示例展示了如何这样做。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
DATABASE_NAME = 'testDatabase'
CONTAINER_NAME = 'products'

async def create_products():
    async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
        database = client.get_database_client(DATABASE_NAME)
        container = database.get_container_client(CONTAINER_NAME)
        for i in range(10):
            await container.upsert_item({
                    'id': 'item{0}'.format(i),
                    'productName': 'Widget',
                    'productModel': 'Model {0}'.format(i)
                }
            )

异步客户端的查询

与同步客户端不同，异步客户端在请求中没有enable_cross_partition标志。未指定分区键值的查询将默认尝试跨分区查询。

查询结果可以被迭代，但查询的原始输出返回一个异步迭代器。这意味着迭代器中的每个对象都是可等待的对象，并且尚不包含真正的查询结果。为了获取查询结果，您可以使用异步for循环，在迭代对象时等待每个结果，或者手动在迭代异步迭代器时等待每个查询结果。

由于查询结果是异步迭代器，因此不能直接将其转换为列表；相反，如果您需要从结果创建列表，请使用异步for循环或Python的列表解析来填充列表。

from azure.cosmos.aio import CosmosClient
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'products'
container = database.get_container_client(CONTAINER_NAME)

async def create_lists():
    results = container.query_items(
            query='SELECT * FROM products p WHERE p.productModel = "Model 2"')

    # iterates on "results" iterator to asynchronously create a complete list of the actual query results

    item_list = []
    async for item in results:
        item_list.append(item)

    # Asynchronously creates a complete list of the actual query results. This code performs the same action as the for-loop example above.
    item_list = [item async for item in results]
    await client.close()

使用集成缓存

集成缓存是一个内存缓存，有助于您确保在请求量增长时成本可控和低延迟。集成缓存有两个部分：一个用于点读取的项目缓存和一个用于查询的查询缓存。下面的代码片段展示了如何使用点读取和查询缓存方法来使用此功能。

使用此功能的优点是，击中集成缓存的点读取和查询不会使用任何RU。这意味着您将比后端读取具有更低的每操作成本。

如何配置Azure Cosmos DB集成缓存（预览）

import azure.cosmos.cosmos_client as cosmos_client
import os

URL = os.environ['ACCOUNT_URI']
KEY = os.environ['ACCOUNT_KEY']
client = cosmos_client.CosmosClient(URL, credential=KEY)
DATABASE_NAME = 'testDatabase'
database = client.get_database_client(DATABASE_NAME)
CONTAINER_NAME = 'testContainer'
container = database.get_container_client(CONTAINER_NAME)

def integrated_cache_snippet():
    item_id = body['id'] 
    query = 'SELECT * FROM c'

    #item cache
    container.read_item(item=item_id, partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

    #query cache   
    container.query_items(query=query,
         partition_key=item_id, max_integrated_cache_staleness_in_ms=30000)

有关集成缓存的更多信息，请参阅Azure Cosmos DB 集成缓存 - 概述。

使用事务批量操作

事务批量请求允许您在同一分区键内一次性发送多个操作。如果事务批量操作中描述的操作按顺序全部成功，则事务将被提交。然而，如果任何操作失败，整个事务将回滚。

事务批量操作的限制为每个批量100个操作，批量操作的总大小限制为1.2Mb。

事务批量操作与单个操作API非常相似，是包含（operation_type_string，args_tuple，batch_operation_kwargs_dictionary）的元组，kwargs字典是可选的。

batch_operations = [
        ("create", (item_body,), kwargs),
        ("replace", (item_id, item_body), kwargs),
        ("read", (item_id,), kwargs),
        ("upsert", (item_body,), kwargs),
        ("patch", (item_id, operations), kwargs),
        ("delete", (item_id,), kwargs),
    ]
batch_results = container.execute_item_batch(batch_operations=batch_operations, partition_key=partition_key)

批量操作kwargs字典有限，总共只能包含三个不同的键值。如果您想在批量中使用条件补丁，可以使用补丁操作的filter_predicate键，或者如果想要在任何操作中使用Etags，也可以使用if_match_etag/if_none_match_etag键。

batch_operations = [
        ("replace", (item_id, item_body), {"if_match_etag": etag}),
        ("patch", (item_id, operations), {"filter_predicate": filter_predicate, "if_none_match_etag": etag}),
    ]

我们还提供了一些示例，展示了如何在同步和异步客户端中使用这些事务批量操作。

如果批量中的操作失败，SDK将抛出CosmosBatchOperationError，告知您哪个操作失败，以及包含失败请求的失败响应列表。

有关事务批量的更多信息，请参阅Azure Cosmos DB 事务批量。

公共预览 - 矢量嵌入和矢量索引

我们为用户添加了新的功能，以便利用矢量嵌入和矢量索引，通过我们的Cosmos SDK使用矢量搜索。这两个容器级别的配置必须在账户级别开启之后才能使用。

每个矢量嵌入都应该有一个指向存储在项目中的相关矢量字段的路径，支持的数据类型（float32，int8，uint8），矢量维度以及用于该嵌入的距离函数。使用平面索引类型的索引矢量最多可以有505个维度。使用量化平面索引类型的索引矢量最多可以有4096个维度。一个示例矢量嵌入策略如下所示

vector_embedding_policy = {
    "vectorEmbeddings": [
        {
            "path": "/vector1",
            "dataType": "float32",
            "dimensions": 256,
            "distanceFunction": "euclidean"
        },
        {
            "path": "/vector2",
            "dataType": "int8",
            "dimensions": 200,
            "distanceFunction": "dotproduct"
        },
        {
            "path": "/vector3",
            "dataType": "uint8",
            "dimensions": 400,
            "distanceFunction": "cosine"
        }
    ]
}

此外，矢量索引已添加到现有的索引策略中，每个索引只需要两个字段：用于索引的相关字段的路径和索引类型（平面或量化平面）的选项。一个带有矢量索引的索引策略示例如下所示

indexing_policy = {
        "automatic": True,
        "indexingMode": "consistent",
        "compositeIndexes": [
            [
                {"path": "/numberField", "order": "ascending"},
                {"path": "/stringField", "order": "descending"}
            ]
        ],
        "spatialIndexes": [
            {"path": "/location/*", "types": [
                "Point",
                "Polygon"]}
        ],
        "vectorIndexes": [
            {"path": "/vector1", "type": "flat"},
            {"path": "/vector2", "type": "quantizedFlat"}
        ]
    }

然后，您需要将这些相关策略传递给容器创建方法，以确保使用这些配置。如果您的索引策略中包含了新的矢量索引，但忘记传递嵌入策略，则操作将失败。

database.create_container(id=container_id, partition_key=PartitionKey(path="/id"),
                          indexing_policy=indexing_policy, vector_embedding_policy=vector_embedding_policy)

注意：矢量嵌入和矢量索引不能通过容器替换操作进行编辑。它们只能直接通过创建获得。

公共预览 - 矢量搜索

随着向量索引和向量嵌入功能的增加，SDK 现在可以执行按向量搜索查询。这些查询在查询文本中指定要使用的 VectorDistance 作为度量标准。但是，由于向量搜索查询需要查看大量数据，因此必须在查询中使用 TOP 或 LIMIT 子句，否则可能会变得过于昂贵或运行时间过长。由于这些查询相对昂贵，SDK 为每个查询设置了默认的最大项数限制为 50000 - 如果您想进一步提高这个限制，可以使用 AZURE_COSMOS_MAX_ITEM_BUFFER_VECTOR_SEARCH 环境变量来做到这一点。然而，请注意，具有太多向量结果的查询可能与在服务中进行搜索相关的额外延迟。这些操作的查询语法如下所示：

VectorDistance(<embedding1>, <embedding2>, [,<exact_search>], [,<specification>])

嵌入 1 和 2 是相关嵌入的值数组，exact_search 是一个可选的布尔值，表示是否进行精确搜索而不是近似搜索（默认值为 false），而 specification 是一个可选的 Json 片段，包含嵌入规范，可以包括 dataType、dimensions 和 distanceFunction。查询中的规范将优先于之前由向量嵌入策略设置的任何配置。一个示例向量搜索查询可能看起来像这样：

    query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}]) AS " \
            "SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}])".format(embeddings_string, embeddings_string)

或者，如果您想向向量距离添加可选参数，可以这样做：

    query = "SELECT TOP 10 c.title,VectorDistance(c.embedding, [{}], true, {{'dataType': 'float32' , 'distanceFunction': 'cosine'}}) AS " \
            "SimilarityScore FROM c ORDER BY VectorDistance(c.embedding, [{}], true, {{'dataType': " \
            "'float32', 'distanceFunction': 'cosine'}})".format(embeddings_string, embeddings_string)

上面的 embeddings_string 将是您从向量嵌入创建的字符串。您可以在这里找到我们的同步示例，以及在我们的异步示例这里，以帮助您。

注意：在有限时间内，如果您的查询操作针对尚未更新的区域或模拟器，客户端可能会遇到一些问题，无法识别使向量搜索成为可能的新 NonStreamingOrderBy 功能。如果发生这种情况，您可以将 AZURE_COSMOS_DISABLE_NON_STREAMING_ORDER_BY 环境变量设置为 "True" 以选择退出此功能并继续按常规操作。

故障排除

常规

当您使用 Python SDK 与 Cosmos DB 交互时，服务返回的异常对应于 REST API 请求返回的相同 HTTP 状态代码。

Azure Cosmos DB 的 HTTP 状态代码

例如，如果您尝试使用在您的 Cosmos DB 数据库中已使用的 ID（名称）创建容器，则返回 409 错误，表示冲突。在下面的代码片段中，错误通过捕获异常并显示有关错误的附加信息被优雅地处理。

try:
    database.create_container(id=CONTAINER_NAME, partition_key=PartitionKey(path="/productName"))
except exceptions.CosmosResourceExistsError:
    print("""Error creating container
HTTP status code 409: The ID (name) provided for the container is already in use.
The container name must be unique within the database.""")

记录诊断信息

此库使用标准的 logging 库进行日志记录。HTTP 会话的基本信息（URL、标头等）以 INFO 级别记录。

启用详细 DEBUG 级别日志记录，包括请求/响应正文和未删除的标头，可以通过具有 logging_enable 参数的客户端启用。

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

同样，logging_enable 可以在单个操作中启用详细日志记录，即使它未为客户端启用。

database = client.create_database(DATABASE_NAME, logging_enable=True)

或者，您可以使用 CosmosHttpLoggingPolicy 进行日志记录，它是从 azure core HttpLoggingPolicy 扩展而来的，通过传递您的记录器到 logger 参数。默认情况下，它将使用 HttpLoggingPolicy 的行为。传递 enable_diagnostics_logging 参数将启用 CosmosHttpLoggingPolicy，并将包含有关调试 Cosmos 问题的相关信息的附加信息添加到响应中。

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

同样，可以通过将记录器传递给单个请求来为单个操作启用日志记录。但是，如果您想使用 CosmosHttpLoggingPolicy 获取更多信息，则需要在客户端构造函数中传递 enable_diagnostics_logging 参数。

# This example enables the CosmosHttpLoggingPolicy and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

遥测

Azure Core为我们的Python SDK提供了使用OpenTelemetry的能力。要使用此功能，需要安装以下包

pip install azure-core-tracing-opentelemetry
pip install opentelemetry-sdk

关于此方面的更多信息，我们建议您查看Azure Core提供的此文档，其中描述了如何设置它。我们还添加了一个示例文件，以展示如何与我们的SDK一起使用。无论您使用的是哪个Cosmos客户端，它都以相同的方式工作。

下一步

有关Cosmos DB服务的更详细文档，请参阅docs.microsoft.com上的Azure Cosmos DB文档。

贡献

此项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权，并且确实授予我们使用您的贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签、注释）。只需按照机器人提供的说明操作。您只需在整个使用我们的CLA的仓库中这样做一次。

此项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以提出任何额外的问题或评论。

发布历史

4.7.0 (2024-05-15)

新增功能

  • 添加了向量嵌入策略和向量索引策略。请参阅PR 34882。
  • 添加了对向量搜索非流式排序查询的支持。请参阅PR 35468。
  • 添加了对使用更改流查询API的起始时间选项的支持。请参阅PR 35090。

已修复的bug

  • 修复了异步客户端中的更改流查询由于大小写敏感的响应头而没有返回所有页面的问题。请参阅PR 35090。
  • 修复了在查询执行的首页发生可重试异常导致查询返回0结果的问题。请参阅PR 35090。

4.6.1 (2024-05-15)

4.6.0 (2024-03-14)

新增功能

  • 分层分区、索引指标和事务性批次的GA发布。

已修复的bug

  • 在create_container_if_not_exists()方法中没有向下传递关键字参数。请参阅PR 34286。

其他更改

  • 对SDK中使用的类型提示进行了多次更新，以提供更多细节。请参阅PR 33269、PR 33341、PR 33738。

4.5.2b5 (2024-03-02)

已修复的bug

  • 修复了异步全局端点管理器上异步锁未正确释放的bug。请参阅PR 34579。

其他更改

  • 将computed_properties关键字标记为试探性，未将continuation_token_limit标记为试探性。请参阅PR 34207。

4.5.2b4 (2024-02-02)

此版本及所有未来版本将需要Python 3.8+。

新增功能

  • 为Python SDK添加了对计算属性的支持（必须在账户级别启用后才能使用）。请参阅PR 33626。

已修复的bug

  • 在同步客户端中使用了线程安全的response_hook。请参阅PR 33790。
  • 修复了会话容器维护不当的问题。请参阅33738。

4.5.2b3 (2023-11-10)

新增功能

  • 增加了在查询操作中捕获索引指标的支持。请参阅PR 33034。

4.5.2b2 (2023-10-31)

新增功能

  • 增加了对事务批处理的支持。请参阅PR 32508。
  • 添加了对基于优先级的节流/基于优先级的执行的preview支持（必须在账户级别启用后才能使用）。请参阅PR 32441。

4.5.2b1 (2023-10-17)

新增功能

  • 增加了对分层分区（也称为子分区）的支持。请参阅PR 31121。

已修复的bug

  • 对异步客户端的create_database_if_not_exists方法中的offer_throughput选项进行了小修复，之前将其误拼为offerThroughput。请参阅PR 32076。

其他更改

  • 由于我们现在推荐使用我们的CosmosHttpLoggingPolicy进行诊断，因此将过时的diagnostics.py文件标记为弃用。有关CosmosHttpLoggingPolicy的更多信息，请参阅我们的README。

4.5.1 (2023-09-12)

已修复的bug

  • 修复了使用DISTINCT + OFFSET/LIMIT运算符进行查询时返回意外结果的问题。请参阅PR 31925。

其他更改

  • 增加了对使用特定字符创建资源时的额外检查。请参阅PR 31861。

4.5.0 (2023-08-09)

新增功能

  • 增加了对可流式传输的跨分区查询的续传令牌的支持。请参阅PR 31189。

已修复的bug

  • 修复了异步create_database_if_not_exists方法在传递offer_throughput作为选项时不起作用的问题。请参阅PR 31478。

其他更改

  • 将response_continuation_token_limit_in_kb重命名为continuation_token_limit以供GA使用。请参阅PR 31532。

4.4.1b1 (2023-07-25)

新增功能

  • 增加了在查询项时限制续传令牌大小的功能。请参阅PR 30731

已修复的bug

  • 修复了异步patch_item方法的错误。请参阅PR 30804。

4.4.0 (2023-06-09)

新增功能

  • 补丁API和按分区键删除所有项的GA发布

4.4.0b2 (2023-05-22)

新增功能

  • 增加了对补丁操作的条件修补。请参阅PR 30455。

已修复的bug

  • 修复了非英文区域导致RFC 1123日期格式错误的错误。请参阅PR 30125。

其他更改

  • 重构了我们的客户端connection_timeout和request_timeout配置。请参阅PR 30171。

4.4.0b1 (2023-04-11)

新增功能

已修复的bug

  • 修复了异步数据库客户端的create_container_if_not_exists()方法中的错误，该错误将意外的kwargs传递到内部使用的read()方法。请参阅PR 29136。
  • 修复了异步容器类中的query_items()方法中的错误，当使用分区键时，分区键和跨分区头都会被设置。请参阅PR 29366。
  • 修复了客户端无法正确显示无效凭据和权限不足的身份错误的问题。当用户在初始化客户端时遇到'NoneType has no attribute ConsistencyPolicy'错误时，现在将看到正确的身份验证异常。请参阅PR 29256。

其他更改

  • 在SDK中删除了对six包的使用。

4.3.1 (2023-02-23)

新增功能

  • 为查询操作添加了correlated_activity_id。
  • 为读取/查询计划操作添加了跨区域重试以处理服务不可用/请求超时。
  • CosmosHttpLoggingPolicy和自动扩展功能的GA发布。

已修复的bug

  • 修复了查询VALUE MAX（或任何其他聚合）的问题，如果查询在至少有一个“空”分区的容器上执行，则会遇到问题。

4.3.1b1（2022-09-19）

新增功能

  • 集成缓存功能的GA发布。有关集成缓存的信息，请参阅Azure Cosmos DB集成缓存。
  • 添加了替换容器上的分析TTL的功能。有关分析TTL的更多信息，请参阅Azure Cosmos DB分析存储。
  • 添加了CosmosHttpLoggingPolicy以替换HttpLoggingPolicy以记录HTTP会话。
  • 为同步和异步客户端添加了创建具有自动扩展属性容器和数据库的能力。
  • 添加了更新自动扩展吞吐量属性的能力。

已修复的bug

  • 修复了重载container.read()方法的参数解析。
  • 修复了validate_cache_staleness_value()方法，以允许max_integrated_cache_staleness是一个大于或等于0的整数。
  • 通过移除异步关键字修复了__aiter__()方法。

4.3.0 (2022-05-23)

新增功能

  • Async I/O API的GA发布，包括从4.3.0b1到4.3.0b4的所有更改。

重大更改

  • 方法签名已更新，以使用关键字参数而不是位置参数来替换异步客户端中大多数方法选项。
  • 错误修复：当文档体中不存在'id'值时，自动ID生成已打开upsert_items()方法。现在方法调用将需要文档体中存在'id'字段。

其他更改

  • 弃用了以offer名称命名的函数，改用新的以吞吐量命名的对应函数（read_offer -> get_throughput）。
  • 标记了GetAuthorizationHeader方法为弃用，因为将在未来的版本中不再公开。
  • 添加了示例，说明如何配置同步和异步客户端的重试选项。
  • 弃用了同步客户端中的connection_retry_policy和retry_options选项。
  • 向尝试使用populate_query_metrics选项的非查询方法添加了用户警告。

4.3.0b4（2022-04-07）

新增功能

  • 为异步客户端添加了对Azure AD身份验证的支持。
  • 为同步客户端添加了对Azure AD身份验证的支持。

其他更改

  • 修改了异步客户端中_set_partition_key的返回类型提示。

4.3.0b3（2022-03-10）

[警告] 默认Session一致性修复将对具有Bounded Staleness或Strong一致性级别且之前未在初始化客户端时将Session作为一致性_level参数发送的数据库账户的客户产生影响。同步和异步客户端的默认一致性级别不再为"Session"，而是在初始化时将设置为用户Cosmos账户设置中的一致性级别（如果客户端初始化时未传递）。请参阅Azure Cosmos DB中的一致性级别以获取有关一致性级别的详细信息，或在此更改的README部分此处。

新增功能

  • 在读取项目和查询项目API中添加了新的max_integrated_cache_staleness_in_ms参数，以便使用Cosmos DB集成缓存功能查看PR #22946。请参阅Azure Cosmos DB集成缓存以获取更多详细信息。
  • 为异步客户端添加了对分片证明查询的支持。

修复了错误。

  • 同步和异步客户端的默认一致性级别不再是Session，而是在初始化时将设置为用户Cosmos帐户设置的一致性级别，如果不传递给客户端初始化。此更改将影响客户端应用程序的RUs和延迟。依赖于默认Session一致性的用户如果其帐户一致性不同于Session，则需要显式传递它。请参阅Azure Cosmos DB中的一致性级别以获取更多详细信息。
  • 修复了在将serverScript主体参数传递给触发器、sproc和udf资源的替换操作时发送无效请求主体的问题。
  • 将异步客户端中的is_system_key逻辑移动。
  • 修复了在向客户端传递无效连接重试策略时未抛出TypeError的问题。

4.3.0b2（2022-01-25）

本版本和所有未来版本将需要Python 3.6+。Python 2.7不再受支持。我们还将删除对Python 3.6的支持，并从2022年12月开始仅支持Python 3.7+。

新增功能

  • 为同步客户端添加了对分片证明查询的支持。

其他更改

  • 为异步客户端添加了异步用户代理。

4.3.0b1（2021-12-14）

新增功能

  • 添加了语言本地异步I/O客户端。

4.2.0 (2020-10-08)

错误修复

  • 修复了当使用query_iterable按页获取结果时，不尊重继续标记的bug。问题#13265。
  • 修复了资源标记未被尊重的问题，该问题发生在文档读取和删除中。问题#13634。

新功能

  • 在查询更改流时添加了对传递partitionKey的支持。问题#11689。

4.1.0 (2020-08-10)

  • 添加了对“lazy”索引模式的弃用警告。后端不再允许使用此模式创建容器，并将它们设置为一致。

新功能

  • 在创建新容器时添加了设置分析存储TTL的能力。

错误修复

  • 修复了对get_client API的dict输入的支持。
  • 修复了查询迭代器中的Python 2/3兼容性问题。
  • 修复了类型提示错误。问题#12570 - 感谢@sl-sandy。
  • 修复了未将选项标题添加到upsert_item函数中的bug。问题#11791 - 感谢@aalapatirvbd。
  • 修复了当在项目中使用非字符串ID时引发错误的问题。现在它引发TypeError而不是AttributeError。问题#11793 - 感谢@Rabbit994。

4.0.0 (2020-05-20)

  • 稳定版本。
  • 将HttpLoggingPolicy添加到管道中，以便能够传递自定义日志记录器以传递请求和响应标题。

4.0.0b6

  • 修复了媒体API的synchronized_request中的bug。
  • 从ConnectionPolicy中删除了MediaReadMode和MediaRequestTimeout，因为不支持媒体请求。

4.0.0b5

  • 已弃用azure.cosmos.errors模块，并由azure.cosmos.exceptions替换。
  • 已弃用访问条件参数（access_condition、if_match、if_none_match），并采用单独的match_condition和etag参数。
  • 修复了路由图提供者中的bug。
  • 添加了对查询Distinct、Offset和Limit的支持。
  • 默认文档查询执行上下文现在用于
    • 更改流查询
    • 单分区查询（partitionkey、partitionKeyRangeId出现在选项中）
    • 非文档查询
  • 在启用跨分区查询设置为true的情况下，对多个分区的聚合进行错误处理，但没有“value”关键字
  • 针对其他场景调用查询计划端点以获取查询计划
  • 为Cosmos实体对象添加了__repr__支持。
  • 更新了文档。

4.0.0b4

  • 增加了对所有操作的支持，以timeout关键字参数指定绝对超时时间（以秒为单位），在此时间范围内操作必须完成。如果超时值被超过，将抛出azure.cosmos.errors.CosmosClientTimeoutError。
  • 增加了一个新的ConnectionRetryPolicy来管理HTTP连接错误期间的重试行为。
  • 增加了新的构造函数和每操作配置关键字参数
    • retry_total - 最大重试尝试次数。
    • retry_backoff_max - 最大重试等待时间（以秒为单位）。
    • retry_fixed_interval - 固定重试间隔（以毫秒为单位）。
    • retry_read - 最大套接字读取重试尝试次数。
    • retry_connect - 最大连接错误重试尝试次数。
    • retry_status - 错误状态码上的最大重试尝试次数。
    • retry_on_status_codes - 要重试的特定状态码列表。
    • retry_backoff_factor - 用于计算重试尝试之间等待时间的因子。

4.0.0b3

  • 向CosmosClient和Database分别添加了create_database_if_not_exists()和create_container_if_not_exists功能。

4.0.0b2

4.0.0b2版本是我们努力构建更Pythonic客户端库的第二次迭代。

破坏性变更

  • 客户端连接已被修改以使用在azure.core.pipeline中定义的HTTP管道。
  • 交互式对象现在已重命名为代理。这包括
    • Database -> DatabaseProxy
    • User -> UserProxy
    • Container -> ContainerProxy
    • Scripts -> ScriptsProxy
  • CosmosClient的构造函数已被更新
    • 将auth参数重命名为credential，并将直接接受身份验证类型。这意味着可以传递主键值、资源令牌的字典或权限列表。但是，仍然支持旧的字典格式。
    • 将connection_policy参数制作为一个关键字参数，尽管它仍然被支持，但策略的每个单独属性现在都可以作为显式的关键字参数传递
      • request_timeout
      • media_request_timeout
      • connection_mode
      • media_read_mode
      • proxy_config
      • enable_endpoint_discovery
      • preferred_locations
      • multiple_write_locations
  • 向CosmosClient添加了一个新的类方法构造函数，以便通过从Azure门户检索的连接字符串进行创建。
  • 一些read_all操作已被重命名为list操作
    • CosmosClient.read_all_databases -> CosmosClient.list_databases
    • Container.read_all_conflicts -> ContainerProxy.list_conflicts
    • Database.read_all_containers -> DatabaseProxy.list_containers
    • Database.read_all_users -> DatabaseProxy.list_users
    • User.read_all_permissions -> UserProxy.list_permissions
  • 所有接受request_options或feed_options参数的操作，这些参数都已移动到关键字参数。此外，尽管仍然支持这些选项字典，但字典中的每个单独选项现在都支持作为显式的关键字参数。
  • 错误层次结构现在从azure.core.AzureError继承，而不是从已删除的CosmosError继承。
    • HTTPFailure已重命名为CosmosHttpResponseError
    • JSONParseFailure已删除，并由azure.core.DecodeError替代
    • 为特定的响应代码添加了额外的错误
      • CosmosResourceNotFoundError用于状态404
      • CosmosResourceExistsError用于状态409
      • CosmosAccessConditionFailedError用于状态412
  • CosmosClient现在可以作为上下文管理器运行，以处理关闭客户端连接。
  • 可迭代响应（例如查询响应和列表响应）现在是azure.core.paging.ItemPaged类型。已将fetch_next_block方法替换为通过by_page方法访问的次要迭代器。

4.0.0b1

版本 4.0.0b1 是我们努力创建一个用户友好且具有 Python 特性的 Azure Cosmos 客户端库的第一个预览版。有关此版本及其他 Azure SDK 库的预览版本信息，请访问 https://aka.ms/azure-sdk-preview1-python。

重大变更：新的 API 设计

  • 操作现在限定在特定的客户端范围内

    • CosmosClient：此客户端处理账户级别的操作。这包括管理服务属性和列出账户中的数据库。
    • Database：此客户端处理数据库级别的操作。这包括创建和删除容器、用户和存储过程。可以通过名称从 CosmosClient 实例访问。
    • Container：此客户端处理特定容器的操作。这包括查询和插入项以及管理属性。
    • User：此客户端处理特定用户的操作。这包括添加和删除权限以及管理用户属性。

    可以通过使用 get_<child>_client 方法沿着客户端层次结构向下导航来访问这些客户端。有关新 API 的完整详细信息，请参阅参考文档。

  • 客户端通过名称而不是通过 Id 访问。无需拼接字符串来创建链接。

  • 不再需要从单个模块导入类型和方法。公共 API 表面直接在 azure.cosmos 包中可用。

  • 可以将单个请求属性作为关键字参数提供，而不是构造单独的 RequestOptions 实例。

3.0.2

  • 添加了对 MultiPolygon 数据类型的支持
  • 会话读取重试策略中的错误修复
  • 解码 base 64 字符串时的错误填充修复

3.0.1

  • LocationCache 中的错误修复
  • 端点重试逻辑错误修复
  • 修复了文档

3.0.0

  • 添加了对多区域写入的支持
  • 命名更改
    • DocumentClient 更名为 CosmosClient
    • Collection 更名为 Container
    • Document 更名为 Item
    • 包名更新为 "azure-cosmos"
    • 命名空间更新为 "azure.cosmos"

2.3.3

  • 添加了对代理的支持
  • 添加了对读取更改流的 support
  • 添加了对集合配额头 support
  • 修复了大型会话令牌问题
  • 修复了 ReadMedia API
  • 修复了分区键范围缓存问题

2.3.2

  • 添加了对连接问题默认重试的支持。

2.3.1

  • 更新文档以引用 Azure Cosmos DB 而不是 Azure DocumentDB。

2.3.0

2.2.1

  • 聚合字典错误修复
  • 资源链接中修剪斜杠的错误修复
  • Unicode 编码测试

2.2.0

  • 添加了对每分钟请求单元 (RU/m) 功能的支持。
  • 添加了对名为 ConsistentPrefix 的新一致性级别的 support。

2.1.0

  • 添加了对聚合查询（COUNT、MIN、MAX、SUM 和 AVG）的支持。
  • 添加了对在运行 DocumentDB 模拟器时禁用 SSL 验证的支持。
  • 移除了对请求模块依赖版本必须是 2.10.0 的限制。
  • 降低了分区集合的最小吞吐量从 10,100 RU/s 降至 2500 RU/s。
  • 添加了在存储过程执行期间启用脚本日志记录的 support。
  • 此版本将 REST API 版本提升到 '2017-01-19'。

2.0.1

  • 对文档注释进行了编辑性修改。

2.0.0

  • 添加了对 Python 3.5 的 support。
  • 添加了对使用 requests 模块进行连接池 support。
  • 添加了对会话一致性 support。
  • 添加了对分区集合的 TOP/ORDERBY 查询 support。

1.9.0

  • 添加了对限流请求的重试策略支持。（限流请求会收到请求速率过大的异常，错误代码429。）默认情况下，当遇到错误代码429时，DocumentDB会为每个请求重试九次，尊重响应头中的retryAfter时间。现在，如果您想忽略服务器在重试之间返回的retryAfter时间，可以将固定重试间隔时间设置为连接策略对象的RetryOptions属性。DocumentDB现在对每个正在限流的请求（无论重试次数如何）最多等待30秒，并以错误代码429返回响应。此时间也可以在连接策略对象的RetryOptions属性中覆盖。

  • DocumentDB现在在每次请求的响应头中返回x-ms-throttle-retry-count和x-ms-throttle-retry-wait-time-ms，以表示限流重试次数和请求在重试之间等待的总时间。

  • 删除了RetryPolicy类及其在document_client类上公开的对应属性（retry_policy），而是引入了RetryOptions类，该类在ConnectionPolicy类上公开RetryOptions属性，可以用来覆盖一些默认的重试选项。

1.8.0

  • 添加了对地理复制数据库账户的支持。
  • 测试修复，将全局主机和masterKey移动到单独的测试类中。

1.7.0

  • 添加了对文档Time To Live（TTL）功能的支持。

1.6.1

  • 修复了与服务器端分区相关的错误，以允许在partitionkey路径中使用特殊字符。

1.6.0

  • 添加了对服务器端分区集合功能的支持。

1.5.0

  • 将客户端分片框架添加到SDK中。实现了HashPartionResolver和RangePartitionResolver类。

1.4.2

  • 实现Upsert。添加了支持Upsert功能的新UpsertXXX方法。
  • 实现基于ID的路由。没有公共API更改，所有更改都是内部的。

1.3.0

  • 跳过发布，以使版本号与其他SDK保持一致

1.2.0

  • 支持地理空间索引。
  • 对所有资源验证id属性。资源的id不能包含？、/、#、\字符，也不能以空格结尾。
  • 将新的“索引转换进度”头添加到ResourceResponse中。

1.1.0

  • 实现V2索引策略

1.0.1

  • 支持代理连接

项目详情

已验证详情

这些详情已由PyPI验证
维护者
Avatar for azure-sdk from gravatar.com azure-sdk Avatar for Laurent.Mazuel from gravatar.com Laurent.Mazuel Avatar for microsoft from gravatar.com microsoft

未验证详情

这些详情尚未由PyPI验证
项目链接
元数据
分类器

发布历史 发布通知 | RSS源

本版本

4.7.0

4.6.1 已撤回

撤回此版本的原因

与4.6.0不兼容

4.6.0

4.5.2b5 预发布

4.5.2b4 预发布

4.5.2b3 预发布

4.5.2b2 预发布

4.5.2b1 预发布

4.5.1

4.5.0

4.4.1b1 预发布

4.4.0

4.4.0b2 预发布

4.4.0b1 预发布

4.3.1

4.3.1b1 预发布

4.3.0

4.3.0b4 预发布

4.3.0b3 预发布

4.3.0b2 预发布

4.3.0b1 预发布

4.2.0

4.1.0

4.0.0

4.0.0b6 预发布版

4.0.0b5 预发布版

4.0.0b4 预发布版

4.0.0b3 预发布版

4.0.0b2 预发布版

4.0.0b1 预发布版

4.0.0a2 预发布版

4.0.0a1 预发布版

3.2.0

3.1.2

3.1.1

3.1.0

3.0.2

3.0.1

3.0.0

下载文件

下载适用于您平台的应用程序文件。如果您不确定该选择哪个，请了解有关安装包的更多信息。

源代码发行版

azure-cosmos-4.7.0.tar.gz (382.0 kB 查看哈希值)

上传时间 源代码

构建发行版

azure_cosmos-4.7.0-py3-none-any.whl (252.1 kB 查看哈希值)

上传时间 Python 3

支持