Introdução ao Azure Cosmos DB para NoSQL usando Python
APLICA-SE A: 
NoSQL
Este artigo mostra como se conectar ao Azure Cosmos DB para NoSQL usando o SDK do Python. Uma vez conectado, você pode executar operações em bancos de dados, contêineres e itens.
Pacote (PyPi) | Exemplos | Referência | da API Código | fonte da biblioteca Enviar comentários
Pré-requisitos
- Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
- Conta do Azure Cosmos DB para NoSQL. Crie uma API para uma conta NoSQL.
- Python 3.7 ou posterior
- Interface de Linha de Comando (CLI) do Azure ou Azure PowerShell
Configure o seu projeto
Crie um ambiente no qual você possa executar código Python.
Com um ambiente virtual, você pode instalar pacotes Python em um ambiente isolado sem afetar o resto do seu sistema.
Instale o SDK do Azure Cosmos DB para NoSQL Python no ambiente virtual.
pip install azure-cosmos
Criar o aplicativo Python
Em seu ambiente, crie um novo arquivo de 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 módulos que você usará no restante do artigo.
Conectar-se ao Azure Cosmos DB para NoSQL
Para se conectar à API para NoSQL do Azure Cosmos DB, crie uma instância da CosmosClient classe. Essa classe é o ponto de partida para executar todas as operações em bancos de dados.
Para se conectar à sua API para conta NoSQL usando o Microsoft Entra, use uma entidade de segurança. O tipo exato de entidade 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 | Principal de segurança |
|---|---|
| Máquina local (desenvolvimento e testes) | Identidade do usuário ou entidade de serviço |
| Azure | Identidade gerida |
| Servidores ou clientes fora do Azure | Service principal (Principal 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 CosmosClient com implementação de credenciais padrão
Se você estiver testando em uma máquina local ou se seu aplicativo for executado nos serviços do Azure com suporte direto para identidades gerenciadas, obtenha um token OAuth criando uma DefaultAzureCredential instância.
No seu app.py:
Obtenha o ponto de extremidade para se conectar à sua conta e defina isso como a variável
COSMOS_ENDPOINTde ambiente .Importe o DefaultAzureCredential e crie uma instância dele.
Crie uma nova instância da classe CosmosClient com o ENDPOINT e a credencial como parâmetros.
from azure.identity import DefaultAzureCredential
ENDPOINT = os.environ["COSMOS_ENDPOINT"]
credential = DefaultAzureCredential()
client = CosmosClient(ENDPOINT, credential)
Importante
Para obter detalhes sobre como adicionar a função correta para permitir o DefaultAzureCredential trabalho, consulte Configurar o controle de acesso baseado em função com a ID do Microsoft Entra para sua conta do Azure Cosmos DB. Em particular, consulte a seção sobre como criar funções e atribuí-las a uma ID principal.
Compilar a aplicação
À medida que você cria seu aplicativo, seu código interage principalmente com quatro tipos de recursos:
A API para conta NoSQL, que é o namespace de nível superior exclusivo para seus dados do Azure Cosmos DB.
Bases de dados, que organizam os contentores na 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 seguinte mostra a relação entre estes 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 nó do banco de dados inclui um único nó de contêiner filho. Esse único nó de contêiner 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 | Description |
|---|---|
CosmosClient |
Essa classe fornece uma representação lógica do lado do cliente para o serviço Azure Cosmos DB. O objeto cliente é usado para configurar e executar solicitações no serviço. |
DatabaseProxy |
Uma interface para uma base de dados que pode, ou não, existir no serviço ainda. Esta classe não deve ser instanciada diretamente. Em vez disso, você deve usar o método CosmosClient get_database_client . |
ContainerProxy |
Uma interface para interagir com um contêiner específico do Cosmos DB. Esta classe não deve ser instanciada diretamente. Em vez disso, use o método DatabaseProxy get_container_client para obter um contêiner existente ou o método create_container para criar um novo contêiner. |
Os guias a seguir mostram como usar cada uma dessas classes para criar seu aplicativo.
| Guia | Description |
|---|---|
| Criar uma base de dados | Criar bases de dados |
| Criar contêiner | Criar contêineres |
| Exemplos de itens | Ponto de leitura de um item específico |