Práticas recomendadas do Azure Cosmos DB para NoSQL no GitHub Copilot para Visual Studio Code

Aplica-se a: ✅ NoSQL

O GitHub Copilot no Visual Studio Code fornece sugestões de código inteligentes, mas essas sugestões se tornam ainda mais poderosas quando entendem o contexto específico do banco de dados. A extensão do Azure Cosmos DB para Visual Studio Code agora fornece automaticamente ao GitHub Copilot as melhores práticas e recomendações específicas do Azure Cosmos DB, permitindo a assistência à IA com reconhecimento de contexto para o desenvolvimento do banco de dados.

Quando você se conecta à sua conta do Azure Cosmos DB por meio da extensão do Visual Studio Code, ele cria automaticamente um azurecosmosdb.instructions.md arquivo na pasta de perfil do usuário. Esse arquivo atua como um provedor de contexto para o GitHub Copilot, garantindo que a IA entenda sua configuração do Azure Cosmos DB e possa fornecer sugestões otimizadas para particionamento, ajuste de desempenho, diagnóstico e muito mais.

Por que a IA com reconhecimento de contexto importa

Assistentes de codificação de IA, como o GitHub Copilot, são tão eficazes quanto o contexto que têm. Sem entender como seu aplicativo interage com o Azure Cosmos DB, como estratégias de particionamento, padrões de indexação ou design de consulta, o Copilot pode gerar sugestões que não são otimizadas para a configuração do banco de dados.

Com o azurecosmosdb.instructions.md arquivo implantado automaticamente, o Copilot obtém acesso imediato a:

Práticas recomendadas do Azure Cosmos DB para design de chave de partição e gerenciamento de taxa de transferência
Dicas de otimização de desempenho para consultas de várias partições e indexação
Recomendações para registro de diagnóstico para resolver problemas de latência ou erros
Diretrizes de configuração econômica para vários cenários, incluindo pesquisa de vetor
Padrões de uso do SDK e estratégias de tratamento de erros

Prerequisites

Visual Studio Code instalado em seu computador
Assinatura do GitHub Copilot (individual, comercial ou empresarial)
Uma conta do Azure Cosmos DB (qualquer API)
Assinatura do Azure com permissões apropriadas para acessar recursos do Cosmos DB

Etapa 1: Instalar extensões necessárias

Primeiro, verifique se você tem a extensão do Azure Cosmos DB e a extensão do GitHub Copilot instaladas:

Instalar a extensão do Azure Cosmos DB

Abrir Visual Studio Code
Vá para o modo de exibição Extensões selecionando Extensões de Exibição ou pressionando >Ctrl+Shift+X (Windows/Linux) ou Cmd+Shift+X (macOS)
Pesquise "Azure Cosmos DB" ou use a ID da extensão: ms-azuretools.vscode-cosmosdb
Selecione Instalar na extensão Azure Databases da Microsoft
Recarregar o Visual Studio Code se solicitado

Instalar o GitHub Copilot

No painel Extensões, pesquise por "GitHub Copilot"
Instalar a extensão do GitHub Copilot pelo GitHub
Entre em sua conta do GitHub quando solicitado
Ativar sua assinatura do Copilot se você ainda não tiver

Etapa 2: Conectar-se à sua conta do Azure Cosmos DB

Conecte sua conta do Azure Cosmos DB para habilitar os recursos com reconhecimento de contexto:

Para o Azure Cosmos DB para NoSQL

No Visual Studio Code, abra o painel do Azure selecionando o ícone do Azure na Barra de Atividades
Entre em sua conta do Azure usando a ID do Microsoft Entra
No modo de exibição de árvore do Azure, expanda sua assinatura
Localizar e expandir o Azure Cosmos DB
Clique com o botão direito do mouse na sua conta do Azure Cosmos DB para NoSQL ou selecione-a para se conectar

Note

Se você estiver em um ambiente corporativo com restrições de rede, talvez seja necessário configurar regras de firewall para permitir seu endereço IP. Considere inicialmente permitir todos os endereços IP (0.0.0.0 - 255.255.255.255) para teste e, em seguida, refinar a lista de permissões para uso em produção.

Etapa 3: verificar a implantação do arquivo de contexto

Depois de conectada, a extensão cria automaticamente o azurecosmosdb.instructions.md arquivo na pasta de perfil do usuário:

Localização do Windows:

%APPDATA%\Code\User\prompts\azurecosmosdb.instructions.md

Localização do macOS:

~/Library/Application Support/Code/User/prompts/azurecosmosdb.instructions.md

Localização do Linux:

~/.config/Code/User/prompts/azurecosmosdb.instructions.md

Esse arquivo é implantado automaticamente em seu perfil de usuário, disponibilizando-o em todos os workspaces do Visual Studio Code sem a necessidade de duplicação em cada projeto.

Etapa 4: Experimente sugestões sensíveis ao contexto

Agora, o GitHub Copilot fornece sugestões otimizadas para o Azure Cosmos DB. Aqui estão alguns exemplos de como o contexto aprimorado melhora sua experiência de desenvolvimento:

Sugestões de consulta otimizadas

Ao escrever consultas, o Copilot agora entende os padrões específicos do Azure Cosmos DB:

// Copilot will suggest optimized query patterns
const query = {
    query: "SELECT * FROM c WHERE c.partitionKey = @partitionKey AND c.status = @status",
    parameters: [
        { name: "@partitionKey", value: userId },
        { name: "@status", value: "active" }
    ]
};

Recomendações de práticas recomendadas

O Copilot sugere as seguintes práticas recomendadas do Azure Cosmos DB para modelagem de dados:

// Copilot suggests embedding related data for single-partition queries
const userDocument = {
    id: userId,
    partitionKey: userId, // Copilot suggests consistent partition key usage
    profile: {
        name: "John Doe",
        email: "john@example.com",
        preferences: {
            theme: "dark",
            notifications: true
        }
    },
    // Embed frequently accessed related data
    recentActivity: [
        { action: "login", timestamp: "2024-01-01T10:00:00Z" },
        { action: "purchase", timestamp: "2024-01-01T11:30:00Z" }
    ]
};

Tratamento e diagnóstico de erros

O Copilot sugere padrões adequados de tratamento de erros específicos para o Azure Cosmos DB:

try {
    const response = await container.items.create(document);
    console.log("Document created successfully");
} catch (error) {
    // Copilot suggests Azure Cosmos DB-specific error handling
    if (error.code === 429) {
        console.log("Rate limited. Retry after:", error.retryAfterInMilliseconds);
        // Implement exponential backoff
    } else if (error.code === 409) {
        console.log("Document already exists");
    } else {
        console.error("Error creating document:", error.message);
        // Log diagnostic information for troubleshooting
        console.log("Diagnostic info:", response.diagnostics);
    }
}

Benefícios do desenvolvedor

Essa integração transforma a extensão do Azure Cosmos DB em mais do que apenas uma ferramenta de gerenciamento. Ela se torna uma camada de conhecimento de IA em seu ambiente de desenvolvimento. Com assistência sensível ao contexto, você pode:

✅ Escrever consultas otimizadas e chamadas de SDK guiadas por práticas recomendadas contextuais
✅ Evitar armadilhas comuns no início do desenvolvimento
✅ Receber sugestões alinhadas com as diretrizes do Azure Cosmos DB do mundo real, não com a lógica genérica do banco de dados
✅ Melhorar o desempenho por meio de otimizações sugeridas por IA
✅ Reduzir o tempo de desenvolvimento com conclusões de código relevantes e com reconhecimento de contexto

Personalizando as diretrizes

O azurecosmosdb.instructions.md arquivo é aberto e extensível. É possível:

Examine o arquivo para entender qual contexto está sendo fornecido ao Copilot
Adicionar diretrizes específicas do projeto para os padrões de codificação da sua equipe
Contribuir com melhorias enviando solicitações de pull para o repositório GitHub
Relatar problemas ou sugestões na seção de problemas

Alternativa: Kit de Agente Azure Cosmos DB

Para uma cobertura mais abrangente, considere usar o Kit do Agente do Azure Cosmos DB como alternativa ou complementar ao arquivo de instruções. O Kit do Agente fornece:

Mais de 45 regras selecionadas em oito categorias (modelagem de dados, chaves de partição, consultas, SDKs, indexação, taxa de transferência, distribuição global e monitoramento)
Diretrizes baseadas em prioridade com regras classificadas por impacto no mundo real
Compatibilidade mais ampla com o GitHub Copilot, Claude Code, CLI do Gemini e outras ferramentas compatíveis com habilidades do agente
Contribuições da comunidade para práticas recomendadas atualizadas continuamente

Instale o Agent Kit com um único comando:

npx add-skill AzureCosmosDB/cosmosdb-agent-kit

Desabilitando o arquivo de instruções

Se você preferir usar apenas o Agent Kit ou quiser desabilitar o arquivo de instruções automáticas:

Navegue até a pasta de perfil do usuário:
- Windows: %APPDATA%\Code\User\prompts\
- macOS: ~/Library/Application Support/Code/User/prompts/
- Linux: ~/.config/Code/User/prompts/
Excluir ou renomear o azurecosmosdb.instructions.md arquivo
Opcionalmente, crie um arquivo vazio com o mesmo nome para impedir que a extensão o recrie

Note

A extensão pode recriar o arquivo de instruções quando você se reconectar à sua conta do Azure Cosmos DB. Para desabilitá-lo permanentemente, você pode criar um backup de sua configuração preferencial ou usar exclusivamente o Agent Kit.

Práticas recomendadas para o benefício máximo

Para obter o máximo dessa assistência de IA com reconhecimento de contexto:

1. Manter sua extensão atualizada

Atualize regularmente a extensão do Azure Cosmos DB para receber as melhores práticas e melhorias mais recentes.

2. Usar nomes de variáveis descritivas

O Copilot fornece melhores sugestões quando seu código usa nomes claros e descritivos que indicam conceitos do Azure Cosmos DB:

// Good - Clear Azure Cosmos DB context
const cosmosClient = new CosmosClient({ endpoint, key });
const database = cosmosClient.database("productCatalog");
const container = database.container("products");

// Less optimal - Generic naming
const client = new CosmosClient({ endpoint, key });
const db = client.database("productCatalog");
const coll = db.container("products");

3. Incluir comentários sobre seu modelo de dados

Ajude o Copilot a fornecer sugestões mais relevantes adicionando comentários sobre sua estratégia de particionamento e o modelo de dados:

// Partition by userId to ensure user data is co-located
// Embed user preferences to minimize cross-partition queries
const userDocument = {
    id: generateUserId(),
    partitionKey: userId, // Using userId as partition key for user isolation
    // ... rest of document
};

4. Usar os recursos de gerenciamento de dados da extensão

Use os recursos internos da extensão junto com o Copilot para uma experiência de desenvolvimento completa:

Editor de consultas para testar e otimizar consultas
Gerenciamento de documentos para edição em tempo real
Métricas de desempenho para entender os custos de consulta
Recursos de exportação para análise de dados

Troubleshooting

Copilot não fornece sugestões específicas para o Azure Cosmos DB

Verificar implantação de arquivo: verifique se azurecosmosdb.instructions.md existe na pasta de perfil do usuário
Reiniciar o Visual Studio Code: às vezes, uma reinicialização é necessária para que as alterações entrem em vigor
Verificar o status do GitHub Copilot: verifique se o Copilot está ativo e autenticado corretamente
Reconectar ao Azure Cosmos DB: tente desconectar e reconectar sua conta

Extensão que não está implantando o arquivo de instruções

Atualizar a extensão: verifique se você tem a versão mais recente da extensão do Azure Cosmos DB
Verificar permissões: verificar se o Visual Studio Code tem permissões de gravação na pasta de perfil do usuário
Conexão manual: tente se conectar manualmente à sua conta do Azure Cosmos DB por meio da extensão

Comentários

Esta página foi útil?

Last updated on 2026-04-27