Guia de início rápido: usar o Azure Cosmos DB para NoSQL com o SDK do Azure para Python
Neste início rápido, você implanta um aplicativo básico do Azure Cosmos DB for Table usando o SDK do Azure para Python. O Azure Cosmos DB for Table é um armazenamento de dados sem esquema que permite que os aplicativos armazenem dados de tabela estruturada na nuvem. Você aprende a criar tabelas, linhas e executar tarefas básicas em seu recurso do Azure Cosmos DB usando o SDK do Azure para Python.
Documentação | de referência da API Código fonte | da biblioteca Pacote (PyPI) | Azure Developer CLI
Pré-requisitos
- Azure Developer CLI
- Área de trabalho do Docker
- Python 3.12
Se não tiver uma conta do Azure, crie uma conta gratuita antes de começar.
Inicializar o projeto
Use a CLI do Desenvolvedor do Azure (azd) para criar uma conta do Azure Cosmos DB for Table e implantar um aplicativo de exemplo em contêiner. O aplicativo de exemplo usa a biblioteca de cliente para gerenciar, criar, ler e consultar dados de exemplo.
Abra um terminal em um diretório vazio.
Se você ainda não estiver autenticado, autentique-se na CLI do Desenvolvedor do Azure usando
azd auth logino . Siga as etapas especificadas pela ferramenta para autenticar na CLI usando suas credenciais preferidas do Azure.azd auth loginUse
azd initpara inicializar o projeto.azd init --template cosmos-db-nosql-python-quickstartDurante a inicialização, configure um nome de ambiente exclusivo.
Implante a conta do Azure Cosmos DB usando
azd upo . Os modelos Bicep também implantam um aplicativo Web de exemplo.azd upDurante o processo de provisionamento, selecione sua assinatura, o local desejado e o grupo de recursos de destino. Aguarde a conclusão do processo de provisionamento. O processo pode levar aproximadamente cinco minutos.
Depois que o provisionamento dos recursos do Azure for concluído, uma URL para o aplicativo Web em execução será incluída na saída.
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.Use o URL no console para navegar até seu aplicativo Web no navegador. Observe a saída do aplicativo em execução.
Instalar a biblioteca de cliente
A biblioteca do cliente está disponível através do Python Package Index, como a azure-cosmos biblioteca.
Abra um terminal e navegue até a
/srcpasta.cd ./srcSe ainda não estiver instalado, instale o pacote usando
pip installoazure-cosmos.pip install azure-cosmosAlém disso, instale o
azure-identitypacote se ainda não estiver instalado.pip install azure-identityAbra e revise o arquivo src/requirements.txt para validar se as
azure-cosmosentradas eazure-identityexistem.
Modelo de objeto
| Nome | Descrição |
|---|---|
CosmosClient |
Essa classe é a classe de cliente principal e é usada para gerenciar metadados ou bancos de dados em toda a conta. |
DatabaseProxy |
Essa classe representa um banco de dados dentro da conta. |
ContainerProxy |
Essa classe é usada principalmente para executar operações de leitura, atualização e exclusão no contêiner ou nos itens armazenados dentro do contêiner. |
PartitionKey |
Esta classe representa uma chave de partição lógica. Essa classe é necessária para muitas operações e consultas comuns. |
Exemplos de código
- Autenticar o cliente
- Obter uma base de dados
- Obter um contentor
- Criar um item
- Obter um item
- Itens de consulta
O código de exemplo no modelo usa um banco de dados chamado cosmicworks e um contêiner chamado products. O products recipiente contém detalhes como nome, categoria, quantidade, um identificador exclusivo e um sinalizador de venda para cada produto. O contêiner usa a /category propriedade como uma chave de partição lógica.
Autenticar o cliente
Este exemplo cria uma nova instância do CosmosClient tipo e autentica usando uma DefaultAzureCredential instância.
credential = DefaultAzureCredential()
client = CosmosClient(url="<azure-cosmos-db-nosql-account-endpoint>", credential=credential)
Obter uma base de dados
Use client.get_database_client para recuperar o banco de dados existente chamado cosmicworks.
database = client.get_database_client("cosmicworks")
Obter um contentor
Recupere o contêiner existente products usando database.get_container_cliento .
container = database.get_container_client("products")
Criar um item
Crie um novo objeto com todos os membros que você deseja serializar em JSON. Neste exemplo, o tipo tem um identificador exclusivo e campos para categoria, nome, quantidade, preço e venda. Crie um item no contêiner usando container.upsert_itemo . Este método "upserts" o item efetivamente substituindo o item se ele já existe.
new_item = {
"id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
"category": "gear-surf-surfboards",
"name": "Yamba Surfboard",
"quantity": 12,
"sale": False,
}
created_item = container.upsert_item(new_item)
Ler um item
Execute uma operação de leitura pontual usando os campos identificador exclusivo (id) e chave de partição. Use container.read_item para recuperar eficientemente o item específico.
existing_item = container.read_item(
item="aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
partition_key="gear-surf-surfboards",
)
Itens de consulta
Execute uma consulta sobre vários itens em um contêiner usando container.GetItemQueryIteratoro . Encontre todos os itens dentro de uma categoria especificada usando esta consulta parametrizada:
SELECT * FROM products p WHERE p.category = @category
queryText = "SELECT * FROM products p WHERE p.category = @category"
results = container.query_items(
query=queryText,
parameters=[
dict(
name="@category",
value="gear-surf-surfboards",
)
],
enable_cross_partition_query=False,
)
Percorra os resultados da consulta.
items = [item for item in results]
output = json.dumps(items, indent=True)
Clean up resources (Limpar recursos)
Quando você não precisar mais do aplicativo ou recursos de exemplo, remova a implantação correspondente e todos os recursos.
azd down