Share via

Introdução ao Azure Cosmos DB for NoSQL usando Python

  • Artigo

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

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. Há três maneiras principais de se conectar a uma conta da API do NoSQL usando a classe CosmosClient:

Conexão com um ponto de extremidade e uma chave

O construtor para CosmosClient tem dois parâmetros necessários:

Parâmetro Valor de exemplo Descrição
url A variável de ambiente COSMOS_ENDPOINT Ponto de extremidade da API do NoSQL a ser usado para todas as solicitações.
credential A variável de ambiente COSMOS_KEY Chave de conta ou token de recurso a ser usado ao autenticar.

Recuperar o ponto de extremidade e a chave da conta

  1. Crie uma variável de shell para resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-python-howto-rg"

  2. Use o comando az cosmosdb list para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Obtenha o URI do ponto de extremidade da API para o NoSQL para a conta usando o comando az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Localize a CHAVE PRIMÁRIA na lista de chaves da conta com o comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Registre os valores do URI e da PRIMARY KEY. Você usará dessas credenciais depois.

Para usar os valores URI e PRIMARY KEY em seu código Python, persista-os em novas variáveis de ambiente na máquina local que executa o aplicativo.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Criar o CosmosClient com o ponto de extremidade e a chave da conta

Crie uma nova instância da classe CosmosClient com as variáveis de ambiente COSMOS_ENDPOINT e COSMOS_KEY como parâmetros.

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
KEY = os.environ["COSMOS_KEY"]

client = CosmosClient(url=ENDPOINT, credential=KEY)

Conexão com uma cadeia de conexão

A classe CosmosClient tem um método from_connection_string que você pode usar para se conectar com um parâmetro necessário:

Parâmetro Valor de exemplo Descrição
conn_str A variável de ambiente COSMOS_CONNECTION_STRING Cadeia de conexão com a conta da API do NoSQL.
credential A variável de ambiente COSMOS_KEY Uma chave de conta alternativa opcional ou token de recurso a ser usado em vez daquele na cadeia de conexão.

Recuperar sua conta cadeia de conexão

  1. Use o comando az cosmosdb list para recuperar o nome da primeira conta do Azure Cosmos DB em seu grupo de recursos e armazená-lo na variável de shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Localize a CADEIA DE CONEXÃO PRIMÁRIA na lista de cadeias de conexão da conta com o comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Para usar o valor CADEIA DE CONEXÃO PRIMÁRIA dentro de seu código Python, persista em uma nova variável de ambiente na máquina local que executa o aplicativo.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Criar o CosmosClient com cadeia de conexão

Crie uma nova instância da classe CosmosClient com as variáveis de ambiente COSMOS_CONNECTION_STRING como o único parâmetro.

CONN_STR = os.environ["COSMOS_CONNECTION_STRING"]

client = CosmosClient.from_connection_string(conn_str=CONN_STR)

Conectar-se usando a plataforma de identidade da Microsoft

Para se conectar à sua conta da API para NoSQL usando a plataforma de identidade da Microsoft e o Microsoft Entra ID, 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:

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.

Criar o CosmosClient com implementação de credencial personalizada

Se você planeja implantar o aplicativo fora do Azure, você pode obter um token OAuth usando outras classes na biblioteca de clientes do Azure.Identity para Python. Essas outras classes também derivam da classe TokenCredential.

Para este exemplo, criamos uma instância ClientSecretCredential usando identificadores de cliente e locatário, juntamente com um segredo do cliente.

Em seu app.py:

  • Obtenha as informações de credencial de variáveis de ambiente para uma entidade de serviço. Você pode obter a ID do cliente, a ID do locatário e o segredo do cliente ao registrar um aplicativo no Microsoft Entra ID. Para obter mais informações sobre como registrar aplicativos do Microsoft Entra, confira Registrar um aplicativo na plataforma de identidade da Microsoft.

  • Importe o ClientSecretCredential e crie uma instância com as variáveis de ambiente TENANT_ID, CLIENT_ID e CLIENT_SECRET como parâmetros.

  • Crie uma instância da classe CosmosClient com ENDPOINT e credential como parâmetros.

from azure.identity import ClientSecretCredential

ENDPOINT = os.environ["COSMOS_ENDPOINT"]
TENANT_ID = os.environ["TENANT_ID"]
CLIENT_ID = os.environ["CLIENT_ID"]
CLIENT_SECRET = os.environ["CLIENT_SECRET"]

credential = ClientSecretCredential(
    tenant_id=TENANT_ID, client_id=CLIENT_ID, client_secret=CLIENT_SECRET
)

client = CosmosClient(ENDPOINT, credential)

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.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

Confira também

Próximas etapas

Agora que você se conectou a uma conta da API de NoSQL, use o próximo guia para criar e gerenciar bancos de dados.

Criar um banco de dados no Azure Cosmos DB for NoSQL usando Python