Azure Cosmos DB Python

ANÁLISE EDITORIAL

Azure Cosmos DB Python é uma Skill oficial da Microsoft para orientar a criação de uma camada de persistência em Cosmos DB for NoSQL com Python e FastAPI. O foco não é ensinar apenas uma chamada de leitura ou escrita. O roteiro reúne autenticação, ciclo de vida do cliente, escolha de chave de partição, consultas parametrizadas, separação entre API e serviço, tratamento de erros e testes.

A versão auditada está no repositório microsoft/skills, caminho .github/plugins/azure-sdk-python/skills/azure-cosmos-db-py, commit e20084b9d230c6f3b46ce36f011e6c3e50f79f8a. O repositório tinha 2.916 estrelas na consulta de 18 de agosto de 2026. O SKILL.md declara versão 1.0.0, pacote azure-cosmos, autoria Microsoft e licença MIT.

O pacote local foi montado após auditoria estática. Ele contém somente SKILL.md, LICENSE e ORIGEM.md. Não inclui modelos Python, scripts, executáveis, dependências, endpoints, tokens, credenciais, dados nem conexão com uma conta Azure.

Imagem editorial exclusiva do Bastidores da IA. Não é captura do portal Azure, interface real nem evidência de banco criado ou consulta executada.

O que esta Skill faz de verdade

A Skill organiza um fluxo para construir serviços Python que acessam Azure Cosmos DB for NoSQL. Ela começa pela instalação de azure-cosmos e azure-identity, exige endpoint, banco e contêiner explícitos e recomenda DefaultAzureCredential para autenticação com Microsoft Entra ID. O uso de chave fica restrito ao emulador ou a um cenário aprovado de desenvolvimento local.

O documento também propõe uma camada de serviço entre o roteador FastAPI e o cliente do banco. Essa separação ajuda a concentrar conversão de documentos, validação, operações CRUD e tratamento de indisponibilidade. Há exemplos de modelos Pydantic, consultas, mocks e testes com pytest.

O ponto mais importante é o particionamento. Em Cosmos DB, a chave de partição determina onde os itens ficam, como as requisições são distribuídas e quais consultas podem ser roteadas de forma eficiente. A Skill pede que acesso e autorização usem a mesma chave quando o caso permitir. Isso reduz consultas entre partições e evita tratar a chave como um detalhe decidido depois.

Ela não provisiona uma conta, não cria permissões e não prova que o modelo proposto é adequado à carga real. Também não substitui a documentação do SDK. O próprio repositório Microsoft está em evolução, portanto exemplos precisam ser comparados com a versão instalada e com a documentação atual antes de virar código de produção.

Para quem serve

A entrada serve a desenvolvedores Python, equipes de API e responsáveis por arquitetura que precisam adicionar persistência NoSQL a um serviço FastAPI. É útil para projetos que armazenam documentos por usuário, espaço de trabalho, cliente ou outro limite lógico e precisam manter autenticação, consulta e teste consistentes.

Também ajuda em revisões de código. Um revisor pode usar o checklist para detectar chave embutida no código, consulta construída por concatenação, leitura sem chave de partição, cliente sem fechamento, mistura de caminhos síncronos e assíncronos ou mock que não representa a chamada real.

Ela não repete a Skill de boas práticas do Supabase Postgres. A página do Supabase cobre um banco relacional e recursos específicos daquela plataforma. Aqui o assunto é Cosmos DB for NoSQL, documentos, unidades de requisição, partições e autenticação do SDK Python.

Compatibilidade e pré-requisitos

O pacote segue o formato Agent Skills e pode ser lido por Codex, GitHub Copilot, Claude Code e outros clientes compatíveis. A ativação varia por ferramenta. A versão auditada cita Python, FastAPI, Pydantic, azure-cosmos, azure-identity e pytest. As versões exatas do projeto devem ser verificadas no ambiente antes de copiar qualquer exemplo.

Para uma revisão documental, basta o código do projeto e a Skill. Para testar de verdade, você precisa de uma conta Azure Cosmos DB for NoSQL ou do emulador, um banco, um contêiner, uma chave de partição definida, rede disponível e uma identidade com acesso ao plano de dados. A permissão de criar ou administrar a conta é diferente da permissão de ler e gravar itens.

Antes do primeiro uso, registre o endpoint, o nome do banco, o contêiner, a chave de partição, as operações permitidas, a região, o volume esperado, os dados pessoais envolvidos e quem pode aprovar escrita ou mudança de schema lógico. Não coloque valores reais em uma conversa pública, em SKILL.md ou em um repositório.

Instalação controlada

Abra o diretório oficial fixado no commit e leia o SKILL.md auditado. O repositório documenta a instalação pelo Skills CLI com npx skills add microsoft/skills.

O instalador oferece várias Skills Microsoft. Selecione somente azure-cosmos-db-py e confira o diretório instalado antes de ativar. Para uma cópia manual, preserve o arquivo principal e os recursos que ele referencia. O ZIP do Bastidores é documental e propositalmente não contém os modelos Python e as referências adicionais, por isso não representa a instalação completa.

Faça a primeira instalação em uma pasta de teste, sem segredos e sem acesso de produção. Compare os arquivos com o commit auditado. Depois, instale as dependências Python conforme o gerenciador do projeto e registre as versões no arquivo de dependências ou lockfile. Não execute automaticamente modelos de código recebidos de uma origem diferente.

Configuração antes do primeiro uso

A Skill cita COSMOS_ENDPOINT, COSMOS_DATABASE_NAME e COSMOS_CONTAINER_ID. Para produção com DefaultAzureCredential, ela também recomenda restringir a cadeia de credenciais com AZURE_TOKEN_CREDENTIALS. O valor COSMOS_KEY aparece apenas para emulador ou autenticação por chave explicitamente aprovada.

Prefira uma identidade gerenciada ou identidade de carga com papel de plano de dados limitado ao banco ou contêiner necessário. Os papéis internos de leitor e colaborador do Cosmos DB simplificam casos comuns, mas ainda precisam de escopo correto. Não conceda administração da conta só para liberar leitura de itens.

Defina o ciclo de vida do cliente junto com o ciclo da aplicação. Em FastAPI, um cliente mantido durante a vida do processo deve ser fechado no encerramento. Se o projeto usar o cliente assíncrono, mantenha credencial e cliente no mesmo modelo assíncrono. Misturar uma API síncrona com funções async sem isolamento pode bloquear o event loop ou esconder vazamento de conexão.

Primeiro uso seguro

1. Escolha um contêiner de teste ou o emulador e confirme que não há dados reais.
2. Descreva o padrão de acesso antes de escolher a chave de partição.
3. Peça à Skill um plano, sem executar comandos ou criar recursos.
4. Confirme endpoint, banco, contêiner e identidade fora do texto gerado.
5. Implemente primeiro um ponto de leitura com id e chave de partição conhecidos.
6. Use consulta parametrizada quando uma consulta for realmente necessária.
7. Registre a carga de unidades de requisição e o número de partições consultadas.
8. Teste sucesso, item ausente, permissão insuficiente, limite, timeout e indisponibilidade.
9. Revise logs para garantir que documentos, tokens e chaves não foram gravados.
10. Só depois avalie escrita, atualização e exclusão com dados descartáveis.

Resultado esperado

Uma boa execução entrega uma camada de acesso pequena e verificável. Ela identifica o cliente usado, o modo de autenticação, a chave de partição, o escopo das consultas, o ciclo de vida da conexão e os testes. Cada operação deve dizer quais dados lê ou altera e como trata falha.

O resultado também deve separar comportamento confirmado de hipótese. Um código que compila não demonstra distribuição equilibrada, custo aceitável ou ausência de partição quente. Esses pontos exigem dados representativos, métricas do Azure Monitor e observação da carga real.

A Skill sugere degradação graciosa quando Cosmos DB fica indisponível. Esse padrão não deve ser aplicado cegamente. Retornar None ou lista vazia pode transformar falha do banco em resposta enganosa. Em fluxos críticos, prefira erro explícito, telemetria, política de repetição limitada e decisão de negócio documentada.

Permissões e riscos

• Plano de dados: ler, consultar, criar, alterar e excluir itens são permissões distintas da administração da conta. Conceda somente o necessário.
• Segredos: chaves e tokens não devem entrar em código, prompt, log, fixture ou ZIP. Use identidade e armazenamento de segredo apropriados.
• Partição: uma escolha ruim pode concentrar tráfego, aumentar consultas entre partições e exigir migração para outro contêiner.
• Consultas: concatenação de entrada cria risco e comportamento imprevisível. Use parâmetros com a notação @.
• Custos: leitura ampla, paginação sem limite e repetição automática podem aumentar consumo de unidades de requisição.
• Disponibilidade: esconder erro como resultado vazio pode levar a decisão incorreta. Defina quando falhar de forma visível.
• Emulador: desabilitar verificação TLS só é aceitável no ambiente local controlado. Não transporte essa configuração para produção.
• Modelos prontos: os arquivos oficiais são ponto de partida, não código aprovado para qualquer arquitetura.

Erros comuns

• 401 ou 403: confira a identidade ativa, o papel de plano de dados e o escopo da atribuição. Não troque para chave administrativa como atalho.
• Item não encontrado: valide ao mesmo tempo o id e o valor da chave de partição.
• Consulta cara: reduza colunas e período, inclua a chave no filtro quando fizer sentido e examine continuação e unidades consumidas.
• Partição quente: verifique cardinalidade, distribuição de armazenamento e consumo por valor antes de mudar o código.
• Event loop bloqueado: confirme se o cliente é síncrono ou assíncrono e mantenha o modelo consistente em toda a chamada.
• Conexões abertas: use gerenciador de contexto ou feche cliente e credencial no encerramento da aplicação.
• Teste passa e produção falha: revise diferenças de endpoint, TLS, identidade, chave de partição e comportamento do mock.
• Skill não ativa: confira nome da pasta, frontmatter, caminho instalado e suporte do cliente ao formato Agent Skills.

Versão auditada e download local

A referência desta página é o commit e20084b9d230c6f3b46ce36f011e6c3e50f79f8a, consultado em 18 de agosto de 2026. O repositório oficial tinha 2.916 estrelas. O arquivo declara versão 1.0.0, autoria Microsoft, pacote azure-cosmos e licença MIT.

O ZIP local possui 3 arquivos, 5.645 bytes e SHA-256 ff7b5e39451658633af39a9f9badc32a9425f1587d6e6c64ca40e3af999e9005. A licença e o registro de origem foram preservados. O pacote exclui scripts, modelos Python, referências extensas, dependências, credenciais e qualquer conexão funcional.

Use o download próprio para auditoria e preservação da versão curada. Para instalação completa, mudanças posteriores e arquivos referenciados, abra o repositório oficial em ação separada. O catálogo de Skills do Bastidores mantém opções com finalidades diferentes.

Resultado esperado e limite final

Azure Cosmos DB Python é útil quando força decisões que costumam ficar espalhadas: identidade, partição, consulta, ciclo de vida e teste. Ela reduz a chance de um agente gerar apenas um cliente global com chave fixa e consultas sem escopo.

O limite é claro. A Skill não conhece a distribuição real dos seus dados, não mede unidades de requisição e não decide sozinha se Cosmos DB é a tecnologia correta. A aprovação final precisa considerar carga, custo, privacidade, recuperação e operação. Use o texto como roteiro de revisão, não como autorização automática para criar recursos ou alterar dados.

Fontes primárias

• Diretório oficial no commit auditado
• SKILL.md oficial
• Licença MIT
• Início rápido oficial com o SDK Python
• Particionamento e escala horizontal
• Acesso ao plano de dados com Microsoft Entra ID e RBAC
• Consultas parametrizadas no Cosmos DB for NoSQL