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

  • Artigo

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

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 classe CosmosClient . Essa classe é o ponto de partida para executar todas as operações em bancos de dados. Há três maneiras de se conectar a uma API para conta NoSQL usando a classe CosmosClient :

Conecte-se 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 COSMOS_ENDPOINT variável de ambiente API para ponto de extremidade NoSQL a ser usado para todas as solicitações.
credential COSMOS_KEY variável de ambiente Chave de conta ou token de recurso a ser usado ao autenticar.

Recuperar o ponto final e a chave da sua 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 para recuperar o az cosmosdb list 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 de ponto de extremidade da API para NoSQL para a conta usando o az cosmosdb show comando.

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

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

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

  5. Registre os valores de URI e CHAVE PRIMÁRIA . Você usará essas credenciais mais tarde.

Para usar os valores URI e PRIMARY KEY dentro do código Python, persista-os para 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>"

Crie o CosmosClient com o ponto final e a chave da conta

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

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

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

Conectar-se 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 COSMOS_CONNECTION_STRING variável de ambiente A cadeia de conexão para a API para conta NoSQL.
credential COSMOS_KEY variável de ambiente Uma chave de conta alternativa opcional ou token de recurso para usar em vez daquele na cadeia de conexão.

Recuperar a cadeia de conexão da sua conta

  1. Use o comando para recuperar o az cosmosdb list 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. Encontre a CADEIA DE CONEXÃO PRIMÁRIA na lista de cadeias de conexão da conta com o az-cosmosdb-keys-list comando.

    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 PRIMARY CONNECTION STRING dentro do código Python, persista-o 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 CosmosClient com cadeia de conexão

Crie uma nova instância da classe CosmosClient com a COSMOS_CONNECTION_STRING variável de ambiente 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 API para conta NoSQL usando a plataforma de identidade da Microsoft e o Microsoft Entra ID, 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 ao qual se conectar, conforme mostrado na seção acima, para Conectar com um ponto de extremidade e uma chave , 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.

Criar CosmosClient com uma implementação de credencial personalizada

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

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

No seu app.py:

  • Obtenha as informações de credenciais 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, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft.

  • Importe o ClientSecretCredential e crie uma instância com as TENANT_IDvariáveis , CLIENT_IDe environment CLIENT_SECRET como parâmetros.

  • Crie uma nova instância da classe CosmosClient com o ENDPOINT e a credencial 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)

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.

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 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 Descrição
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

Consulte também

Próximos passos

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

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