Introdução ao Azure Cosmos DB for NoSQL usando Python
APLICA-SE A: 
NoSQL
Este artigo mostra como se conectar ao Azure Cosmos DB for NoSQL usando o SDK do Python. Depois de conectado, você pode executar operações em bancos de dados, contêineres e itens.
Pacote (PyPi) | Amostras | Referência da API | Código de origem da biblioteca | Fornecer feedback
Pré-requisitos
- Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
- Conta do Azure Cosmos DB for NoSQL. Criar uma conta da API para o NoSQL.
- Python 3.7 ou posterior
- CLI (interface de linha de comando) do Azure ou Azure PowerShell
Configurar o seu projeto
Crie um ambiente no qual você possa executar o código Python.
Com um ambiente virtual, você pode instalar pacotes do Python em um ambiente isolado sem afetar o restante do sistema.
Instale o SDK do Python do Azure Cosmos DB for NoSQL no ambiente virtual.
pip install azure-cosmos
Criar o aplicativo do Python
Em seu ambiente, crie um novo arquivo app.py e adicione o seguinte código a ele:
import json
import os
import sys
import uuid
from azure.core.exceptions import AzureError
from azure.cosmos import CosmosClient, PartitionKey
O código anterior importa os módulos que você usará no restante do artigo.
Conectar-se ao Azure Cosmos DB for NoSQL
Para se conectar à API do NoSQL para o Azure Cosmos DB, crie uma instância da classe CosmosClient. Essa classe é o ponto de partida para executar todas as operações em bancos de dados.
Para se conectar à conta da API para NoSQL usando o Microsoft Entra, use uma entidade de segurança. O tipo exato de entidade de segurança dependerá de onde você hospeda o código do aplicativo. A tabela abaixo serve como um guia de referência rápida.
| Onde o aplicativo é executado | Entidade de segurança |
|---|---|
| Computador local (desenvolvimento e teste) | Identidade do usuário ou entidade de serviço |
| Azure | Identidade gerenciada |
| Servidores ou clientes fora do Azure | Entidade de serviço |
Importar Azure.Identity
O pacote azure-identity contém a funcionalidade de autenticação principal que é compartilhada entre todas as bibliotecas do SDK do Azure.
Importe o pacote azure-identity para seu ambiente.
pip install azure-identity
Criar o CosmosClient com implementação de credencial padrão
Se você estiver testando em um computador local ou seu aplicativo será executado nos serviços do Azure com suporte direto para identidades gerenciadas, obtenha um token OAuth criando uma instância DefaultAzureCredential.
Em seu app.py:
Conecte o ponto de extremidade à conta e defina-o como a variável de ambiente
COSMOS_ENDPOINT.Importe o DefaultAzureCredential e crie uma instância dele.
Crie uma instância da classe CosmosClient com ENDPOINT e credential como parâmetros.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Importante
Para ver os detalhes de como adicionar a função correta para habilitar o funcionamento de DefaultAzureCredential, confira Configurar o controle de acesso baseado em função com o Microsoft Entra ID para sua conta do Azure Cosmos DB. Em particular, consulte a seção sobre como criar funções e atribuí-las a uma ID de entidade de segurança.
Crie seu aplicativo
Conforme você compila seu aplicativo, seu código interagirá principalmente com quatro tipos de recursos:
A conta da API para o NoSQL, que é o namespace exclusivo de nível superior dos dados do Azure Cosmos DB.
Bancos de dados, que organizam os contêineres em sua conta.
Contêineres, que contêm um conjunto de itens individuais em seu banco de dados.
Itens, que representam um documento JSON em seu contêiner.
O diagrama a seguir mostra a relação entre esses recursos.
Diagrama hierárquico mostrando uma conta do Azure Cosmos DB na parte superior. A conta tem dois nós de banco de dados filho. Um dos nós de banco de dados inclui dois nós de contêiner filho. O outro inclui um único nó de contêiner filho. Esse nó de contêiner único tem três nós de item filho.
Cada tipo de recurso é representado por uma ou mais classes Python associadas. Aqui está uma lista das classes mais comuns para programação síncrona. (Há classes semelhantes para programação assíncrona no namespace azure.cosmos.aio).
| Classe | Descrição |
|---|---|
CosmosClient |
Esta classe fornece a representação lógica do lado do cliente para o serviço do Azure Cosmos DB. Esse objeto do cliente é usado para configurar e executar solicitações no serviço. |
DatabaseProxy |
Uma interface para um banco de dados que pode ou não existir no serviço ainda. Essa classe não deve ser instanciada diretamente. Em vez disso, você deve usar o método get_database_client do CosmosClient. |
ContainerProxy |
Uma interface para interagir com um contêiner específico do Cosmos DB. Essa classe não deve ser instanciada diretamente. Em vez disso, use o método get_container_client do DatabaseProxy para obter um contêiner existente ou o método create_container para criar um contêiner. |
Os guias a seguir mostram como usar cada uma dessas classes para compilar seu aplicativo.
| Guia | Descrição |
|---|---|
| Criar um banco de dados | Criar bancos de dados |
| Criar contêiner | Crie contêineres |
| Exemplos de item | Leitura pontual de um item específico |