Clause d’exclusion de responsabilité

La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691

Bibliothèque cliente d’API SQL Azure Cosmos DB pour Python - version 4.5.1

Azure Cosmos DB est un service de base de données multimodèle globalement distribué qui prend en charge les bases de données de documents, de valeurs clés, à colonne large et de graphiques.

Utilisez le Kit de développement logiciel (SDK) de l’API SQL Azure Cosmos DB pour Python pour gérer les bases de données et les documents JSON qu’elles contiennent dans ce service de base de données NoSQL. Les fonctionnalités de haut niveau sont les suivantes :

• Créer des bases de données Cosmos DB et modifier leurs paramètres
• Créer et modifier des conteneurs pour stocker des collections de documents JSON
• Créer, lire, mettre à jour et supprimer les éléments (documents JSON) dans vos conteneurs
• Interroger les documents de votre base de données à l’aide d’une syntaxe de type SQL

Code | source du KIT de développement logiciel (SDK)Package (PyPI) | Package (Conda) | Documentation de référence sur les | API | Documentation produitÉchantillons

Ce Kit de développement logiciel (SDK) est utilisé pour l’API SQL. Pour toutes les autres API, case activée la documentation d’Azure Cosmos DB pour évaluer le meilleur KIT de développement logiciel (SDK) pour votre projet.

Prise en main

Mise à jour importante sur la prise en charge de Python 2.x

Les nouvelles versions de ce kit SDK ne prendront pas en charge Python 2.x à compter du 1er janvier 2022. Consultez le JOURNAL DES MODIFICATIONS pour plus d’informations.

Prérequis

• Abonnement Azure - Créer un compte gratuit
• Compte Azure Cosmos DB - API SQL
• Python 3.6+

Si vous avez besoin d’un compte d’API SQL Cosmos DB, vous pouvez en créer un avec cette commande Azure CLI :

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

Installer le package

pip install azure-cosmos

Configurer un environnement virtuel (facultatif)

Bien que cela ne soit pas obligatoire, vous pouvez maintenir votre environnement système de base et celui du SDK Azure séparés en utilisant un environnement virtuel. Exécutez les commandes suivantes pour configurer, puis entrer un environnement virtuel avec venv :

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

Authentifier le client

L’interaction avec Cosmos DB commence par un instance de la classe CosmosClient. Vous avez besoin d’un compte, de son URI et d’une de ses clés de compte pour instancier l’objet client.

Utilisez l’extrait de code Azure CLI ci-dessous pour remplir deux variables d’environnement avec l’URI du compte de base de données et sa clé master principale (vous trouverez également ces valeurs dans le Portail Azure). L’extrait de code est mis en forme pour l’interpréteur de commandes Bash.

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)

Création du client

Une fois que vous avez renseigné les ACCOUNT_URI variables d’environnement et ACCOUNT_KEY , vous pouvez créer le CosmosClient.

from azure.cosmos import CosmosClient

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

Authentification AAD

Vous pouvez également authentifier un client à l’aide des informations d’identification AAD de votre principal de service et du package d’identité Azure. Vous pouvez passer directement les informations d’identification à ClientSecretCredential, ou utiliser 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)

Vérifiez toujours que l’identité managée que vous utilisez pour l’authentification AAD dispose d’autorisations readMetadata .
Plus d’informations sur la configuration de l’authentification AAD : Configurer RBAC pour l’authentification AAD
Plus d’informations sur les opérations autorisées pour les clients authentifiés AAD : Modèle d’autorisation RBAC

Concepts clés

Une fois que vous avez initialisé un CosmosClient, vous pouvez interagir avec les principaux types de ressources dans Cosmos DB :

• Base de données : un compte Cosmos DB peut contenir plusieurs bases de données. Quand vous créez une base de données, vous spécifiez l’API que vous voulez utiliser pour l’interaction avec ses documents : SQL, MongoDB, Gremlin, Cassandra ou Azure Table. Utilisez l’objet DatabaseProxy pour gérer ses conteneurs.

• Conteneur : un conteneur est une collection de documents JSON. Vous créez (insérer), lire, mettre à jour et supprimer des éléments dans un conteneur à l’aide de méthodes sur l’objet ContainerProxy .

• Élément : Un élément est la représentation de type dictionnaire d’un document JSON stocké dans un conteneur. Chaque élément que vous ajoutez à un conteneur doit inclure une id clé avec une valeur qui identifie de manière unique l’élément dans le conteneur.

Pour plus d’informations sur ces ressources, consultez Utilisation des bases de données, des conteneurs et des éléments Azure Cosmos.

Comment utiliser enable_cross_partition_query

L’argument enable_cross_partition_query mot clé accepte 2 options : None (par défaut) ou True.

Remarque sur l’utilisation des requêtes par ID

Lorsque vous utilisez des requêtes qui tentent de trouver des éléments en fonction d’une valeur d’id , assurez-vous toujours que vous transmettez une variable de type chaîne. Azure Cosmos DB autorise uniquement les valeurs d’ID de chaîne et si vous utilisez un autre type de données, ce KIT de développement logiciel (SDK) ne retourne aucun résultat ni aucun message d’erreur.

Remarque sur les niveaux de cohérence du client

À compter de la version 4.3.0b3, si un utilisateur ne passe pas un niveau de cohérence explicite à son initialisation client, son client utilise le niveau par défaut de son compte de base de données. Auparavant, la valeur par défaut était définie sur Session la cohérence. Si, pour une raison quelconque, vous souhaitez continuer à effectuer cette opération, vous pouvez modifier l’initialisation de votre client pour inclure le paramètre explicite pour ceci, comme indiqué :

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')

Limites

Actuellement, les fonctionnalités ci-dessous ne sont pas prises en charge. Pour obtenir d’autres options, case activée la section Solutions de contournement ci-dessous.

Limitations du plan de données :

• Requêtes Group By
• Requêtes avec COUNT à partir d’une sous-requête DISTINCT : SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C)
• Traitement par lots en bloc/transactionnel
• Accès direct au mode TCP
• Prise en charge des jetons de continuation pour les requêtes d’agrégation entre partitions telles que le tri, le comptage et les distincts. Les requêtes streamables telles que SELECT * FROM WHEREprennent en charge les jetons de continuation.
• Flux de modification : Processeur
• Flux de modification : lire les valeurs de clé de plusieurs partitions
• Flux de modification : heure de lecture spécifique
• Flux de modification : lu depuis le début
• Flux de modification : modèle d’extraction
• Inter-partitionNEMENT ORDER BY pour les types mixtes
• Activation diagnostics pour les méthodes de type requête asynchrone

Limitations du plan de contrôle :

• Obtenir les métriques CollectionSizeUsage, DatabaseUsage et DocumentUsage
• Créer un index géospatial
• Obtenir la chaîne de connexion
• Obtenir les RU/s minimales d’un conteneur

Solutions de contournement

Solution de contournement de limitation du traitement en bloc

Si vous souhaitez utiliser le Kit de développement logiciel (SDK) Python pour effectuer des insertions en bloc dans Cosmos DB, la meilleure alternative consiste à utiliser des procédures stockées pour écrire plusieurs éléments avec la même clé de partition.

Solution de contournement des limitations du plan de contrôle

En règle générale, vous pouvez utiliser le portail Azure, l’API REST du fournisseur de ressources Azure Cosmos DB, Azure CLI ou PowerShell pour les limitations non prises en charge du plan de contrôle.

Booléen (type de données)

Alors que le langage Python utilise « True » et « False » pour les types booléens, Cosmos DB accepte uniquement « true » et « false ». En d’autres termes, le langage Python utilise des valeurs booléennes avec la première lettre majuscule et toutes les autres lettres minuscules, tandis que Cosmos DB et son langage SQL utilisent uniquement des lettres minuscules pour ces mêmes valeurs booléennes. Comment faire face à ce défi ?

• Vos documents JSON créés avec Python doivent utiliser « True » et « False » pour réussir la validation du langage. Le Kit de développement logiciel (SDK) le convertit en « true » et « false » pour vous. Ce qui signifie que « vrai » et « faux » sont les éléments qui seront stockés dans Cosmos DB.
• Si vous récupérez ces documents avec le Data Explorer du portail Cosmos DB, vous verrez « true » et « false ».
• Si vous récupérez ces documents avec ce Kit de développement logiciel (SDK) Python, les valeurs « true » et « false » seront automatiquement converties en « True » et « False ».

Sous-éléments de clause SQL requêtes x FROM

Ce Kit de développement logiciel (SDK) utilise la méthode query_items pour envoyer des requêtes SQL à Azure Cosmos DB.

Le langage SQL Cosmos DB vous permet d’obtenir des sous-éléments à l’aide de la clause FROM, afin de réduire la source à un sous-ensemble plus petit. Par exemple, vous pouvez utiliser select * from Families.children au lieu de select * from Families. Notez toutefois que :

• Pour les requêtes SQL utilisant la query_items méthode , ce Kit de développement logiciel (SDK) vous demande de spécifier ou partition_key d’utiliser l’indicateur enable_cross_partition_query .
• Si vous obtenez des sous-éléments et spécifiez le partition_key, assurez-vous que votre clé de partition est incluse dans les sous-éléments, ce qui n’est pas vrai dans la plupart des cas.

Nombre maximum d’éléments

Il s’agit d’un paramètre de la méthode query_items, un entier indiquant le nombre maximal d’éléments à retourner par page. La None valeur peut être spécifiée pour permettre au service de déterminer le nombre d’éléments optimal. Il s’agit de la valeur de configuration recommandée et du comportement par défaut de ce Kit de développement logiciel (SDK) lorsqu’il n’est pas défini.

Exemples

Les sections suivantes fournissent plusieurs extraits de code qui couvrent quelques-unes des tâches Cosmos DB les plus courantes, notamment :

• Créer une base de données
• Créer un conteneur
• Créer un conteneur compatible avec le magasin analytique
• Obtenir un conteneur existant
• Insérer des données
• Supprimer des données
• Interroger la base de données
• Obtenir les propriétés de la base de données
• Obtenir les débits de base de données et de conteneur
• Modifier les propriétés du conteneur
• Utilisation du client asynchrone

Création d'une base de données

Après avoir authentifié votre CosmosClient, vous pouvez utiliser n’importe quelle ressource dans le compte. L’extrait de code ci-dessous crée une base de données d’API SQL, qui est la valeur par défaut quand aucune API n’est spécifiée lorsque create_database est appelée.

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)

Créez un conteneur.

Cet exemple crée un conteneur avec les paramètres par défaut. Si un conteneur portant le même nom existe déjà dans la base de données (ce qui génère une 409 Conflict erreur), le conteneur existant est obtenu à la place.

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

Créer un conteneur avec le magasin analytique activé

Cet exemple crée un conteneur avec le magasin analytique activé, pour la création de rapports, le décisionnel, l’IA et l’analytique avancée avec Azure Synapse Link.

Les options pour analytical_storage_ttl sont les suivantes :

• 0 ou Null ou non informé : non activé.
• -1 : Les données seront stockées à l’infini.
• Tout autre nombre : le ttl réel, en secondes.

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

Les extraits de code précédents gèrent également l’exception CosmosHttpResponseError si la création du conteneur a échoué. Pour plus d’informations sur la gestion et la résolution des erreurs, consultez la section .

Obtenir un conteneur existant

Récupérez un conteneur existant de la base de données :

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)

Insertion des données

Pour insérer des éléments dans un conteneur, transmettez un dictionnaire contenant vos données à ContainerProxy.upsert_item. Chaque élément que vous ajoutez à un conteneur doit inclure une id clé avec une valeur qui identifie de manière unique l’élément dans le conteneur.

Cet exemple montre comment insérer plusieurs éléments dans le conteneur, chacun avec un unique 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)
        }
    )

Suppression de données

Pour supprimer des éléments d’un conteneur, utilisez ContainerProxy.delete_item. L’API SQL dans Cosmos DB ne prend pas en charge l’instruction 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')

REMARQUE : Si vous utilisez une collection partitionnée, la valeur de dans partitionKey l’exemple de code ci-dessus doit être définie sur la valeur de la clé de partition pour cet élément particulier, et non sur le nom de la colonne de clé de partition dans votre collection. Cela vaut pour les lectures de points et les suppressions.

Interroger la base de données

Une base de données d’API SQL Cosmos DB prend en charge l’interrogation des éléments d’un conteneur avec ContainerProxy.query_items à l’aide d’une syntaxe de type SQL.

Cet exemple interroge un conteneur pour des éléments avec un spécifique 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))

REMARQUE : bien que vous puissiez spécifier n’importe quelle valeur pour le nom du conteneur dans la FROM clause, nous vous recommandons d’utiliser le nom du conteneur pour la cohérence.

Exécutez des requêtes paramétrables en passant un dictionnaire contenant les paramètres et leurs valeurs à 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))

Pour plus d’informations sur l’interrogation des bases de données Cosmos DB avec l’API SQL, consultez Interroger des données Azure Cosmos DB avec des requêtes SQL.

Obtenir les propriétés de la base de données

Obtenez et affichez les propriétés d’une base de données :

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))

Obtenir les débits de base de données et de conteneur

Obtenez et affichez les valeurs de débit d’une base de données et d’un conteneur avec un débit dédié :

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']))

Modifier les propriétés du conteneur

Certaines propriétés d’un conteneur existant peuvent être modifiées. Cet exemple montre comment définir la durée de vie (TTL) par défaut pour les éléments du conteneur sur 10 secondes :

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']))

Pour plus d’informations sur la durée de vie, consultez Durée de vie des données Azure Cosmos DB.

Utilisation du client asynchrone

Le client cosmos asynchrone est un client distinct qui ressemble et fonctionne de la même manière que le client synchrone existant. Toutefois, le client asynchrone doit être importé séparément et ses méthodes doivent être utilisées avec les mots clés async/await. Le client Async doit être initialisé et fermé après utilisation, ce qui peut être effectué manuellement ou à l’aide d’un gestionnaire de contexte. L’exemple ci-dessous montre comment procéder manuellement.

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)
    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

Au lieu d’ouvrir et de fermer manuellement le client, il est vivement recommandé d’utiliser les async with mots clés. Cela crée un gestionnaire de contexte qui initialisera puis fermera le client une fois que vous êtes hors de l’instruction. L’exemple ci-dessous montre comment procéder.

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)
                }
            )

Requêtes avec le client asynchrone

Contrairement au client synchrone, le client asynchrone n’a pas d’indicateur enable_cross_partition dans la demande. Les requêtes sans valeur de clé de partition spécifiée tentent d’effectuer une requête de partition croisée par défaut.

Les résultats de la requête peuvent être itérés, mais la sortie brute de la requête retourne un itérateur asynchrone. Cela signifie que chaque objet de l’itérateur est un objet pouvant être attendu et ne contient pas encore le vrai résultat de la requête. Pour obtenir les résultats de la requête, vous pouvez utiliser une boucle async for, qui attend chaque résultat à mesure que vous itérer sur l’objet, ou attendre manuellement chaque résultat de requête pendant que vous itérer sur l’itérateur asynchrone.

Étant donné que les résultats de la requête sont un itérateur asynchrone, ils ne peuvent pas être convertis directement en listes ; à la place, si vous devez créer des listes à partir de vos résultats, utilisez une boucle async for ou la compréhension de liste de Python pour remplir une liste :

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()

Utilisation du cache intégré

Un cache intégré est un cache en mémoire qui vous permet de garantir des coûts gérables et une faible latence à mesure que votre volume de demandes augmente. Le cache intégré comprend deux parties : un cache d’éléments pour les lectures de points et un cache de requête pour les requêtes. L’extrait de code ci-dessous vous montre comment utiliser cette fonctionnalité avec les méthodes de mise en cache de lecture ponctuelle et de requête.

L’avantage de cette utilisation est que le point de lecture et les requêtes qui atteignent le cache intégré n’utilisent pas d’unités de requête. Cela signifie que vous aurez un coût par opération beaucoup plus faible que les lectures à partir du back-end.

Comment configurer le cache intégré Azure Cosmos DB (préversion)

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)

Pour plus d’informations sur le cache intégré, consultez Cache intégré Azure Cosmos DB - Vue d’ensemble.

Dépannage

Général

Lorsque vous interagissez avec Cosmos DB à l’aide du Kit de développement logiciel (SDK) Python, les exceptions retournées par le service correspondent aux mêmes codes de status HTTP retournés pour les demandes d’API REST :

Codes d’état HTTP pour Azure Cosmos DB

Par exemple, si vous essayez de créer un conteneur à l’aide d’un ID (nom) déjà utilisé dans votre base de données Cosmos DB, une 409 erreur est retournée, indiquant le conflit. Dans l’extrait suivant, l’erreur est prise en charge correctement via l’interception de l’exception et l’affichage d’informations supplémentaires sur l’erreur en question.

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.""")

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

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

Vous pouvez également journaliser à l’aide de CosmosHttpLoggingPolicy, qui s’étend à partir d’Azure Core HttpLoggingPolicy, en passant votre journalisation à l’argument logger . Par défaut, il utilise le comportement de HttpLoggingPolicy. Le passage de l’argument enable_diagnostics_logging active CosmosHttpLoggingPolicy et contient des informations supplémentaires dans la réponse concernant le débogage des problèmes 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)

De même, la journalisation peut être activée pour une seule opération en passant un enregistreur d’événements à la requête unique. Toutefois, si vous souhaitez utiliser CosmosHttpLoggingPolicy pour obtenir des informations supplémentaires, l’argument enable_diagnostics_logging doit être transmis au constructeur client.

# 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)

Télémétrie

Azure Core permet à nos sdk Python d’utiliser OpenTelemetry avec eux. Les seuls packages qui doivent être installés pour utiliser cette fonctionnalité sont les suivants :

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

Pour plus d’informations à ce sujet, nous vous recommandons de consulter ce document à partir d’Azure Core qui décrit comment le configurer. Nous avons également ajouté un exemple de fichier pour montrer comment il peut être utilisé avec notre SDK. Cela fonctionne de la même façon quel que soit le client Cosmos que vous utilisez.

Étapes suivantes

Pour une documentation plus complète sur le service Cosmos DB, consultez la documentation du service Cosmos DB sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.