azure-storage

Visão geral

O que a skill azure-storage faz

A skill azure-storage é um guia focado nos Microsoft Azure Storage Services, cobrindo:

• Blob Storage – armazenamento de objetos e arquivos para backups, assets estáticos e arquivos de dados grandes
• Azure Files (File Shares) – compartilhamentos de arquivos compatíveis com SMB para workloads de lift-and-shift
• Queue Storage – filas leves de mensagens assíncronas e tarefas em background
• Table Storage – armazenamento NoSQL chave-valor para dados simples, sem esquema
• Azure Data Lake – armazenamento para big data analytics com namespaces hierárquicos

Essa skill não adiciona um novo SDK ou CLI por si só. Em vez disso, ela ajuda você a:

• Escolher o serviço Azure Storage certo para o seu cenário
• Usar as ferramentas do MCP server (quando disponíveis) para listar contas, containers e blobs
• Instalar os SDKs de linguagem adequados (Python, JavaScript/Node.js, Java, .NET, Go, Rust)
• Seguir boas práticas de autenticação para não vazar segredos nem usar DefaultAzureCredential de forma inadequada

Para quem é esta skill

Use a skill azure-storage se você é:

• Desenvolvedor backend integrando Azure Storage em APIs, serviços ou workers em background
• Engenheiro de cloud ou DevOps padronizando como seu time usa Azure Storage
• Engenheiro de dados ou de analytics precisando de uma orientação rápida sobre Data Lake versus Blob Storage
• Usuário de Agent / MCP que quer fluxos de trabalho com noção de storage (listar contas de storage, containers e blobs via azure__storage)

Problemas que a skill azure-storage ajuda a resolver

Com esta skill você consegue responder rapidamente perguntas como:

• Qual serviço Azure Storage devo usar para arquivos vs mensagens vs dados chave-valor?
• Como listar contas de storage, containers e blobs via MCP server?
• Qual pacote de SDK devo instalar para Blob, Queue, File Share ou Data Lake na minha linguagem?
• Como configurar autenticação sem senha usando managed identities e Azure RBAC?
• Quando devo usar DefaultAzureCredential e quando devo evitá-lo?

Quando azure-storage é ou não uma boa opção

Use azure-storage para:

• Integrar Blob Storage em APIs ou microsserviços
• Montar ou gerenciar file shares para workloads de lift-and-shift
• Implementar filas assíncronas usando Azure Queue Storage
• Armazenar e consultar dados simples chave-valor ou entidades em Table Storage
• Trabalhar com Azure Data Lake para dados analíticos

Não use azure-storage para:

• Bancos de dados relacionais SQL (use Azure SQL ou outra skill específica de banco de dados)
• Workloads com Cosmos DB (consulte azure-prepare e skills específicas de Cosmos)
• Mensageria com Event Hubs ou Service Bus (use azure-messaging e skills relacionadas)

Se sua carga de trabalho é principalmente SQL transacional ou streaming de eventos em alto nível, esta skill não é o melhor ponto de partida.

---

Como usar

1. Instalar a skill azure-storage

Para disponibilizar azure-storage no ambiente do seu agent, instale a partir do repositório microsoft/azure-skills:

npx skills add https://github.com/microsoft/azure-skills --skill azure-storage

Após a instalação, a skill expõe documentação e referências que seu agent (ou você, via Files view) pode inspecionar, incluindo:

• SKILL.md – descrição de alto nível dos serviços e ferramentas suportados
• references/auth-best-practices.md – padrões recomendados de autenticação
• references/sdk-usage.md – visão geral dos SDKs entre linguagens e comandos de instalação
• references/sdk/*.md – referências rápidas por linguagem para Blob, Queue, File Share, Data Lake e Tables

Se você tem o Azure MCP server habilitado no seu ambiente, a skill também se integra às ferramentas azure__storage para operações em contas e blobs.

2. Entender os serviços e ferramentas disponíveis

Abra primeiro o SKILL.md. Ele inclui uma tabela de serviços que explica quando usar cada serviço de storage e quais ferramentas funcionam com ele:

• Blob Storage – armazenamento geral de objetos
  • MCP: azure__storage
  • CLI: az storage blob
• File Shares – compartilhamentos de arquivos SMB
  • CLI: az storage file
• Queue Storage – mensagens assíncronas
  • CLI: az storage queue
• Table Storage – entidades chave-valor
  • CLI: az storage table
• Data Lake – analytics e namespace hierárquico
  • CLI: az storage fs

Isso ajuda você a escolher o serviço correto e o conjunto de comandos CLI antes de começar a codificar.

3. Usar o MCP server para descoberta de storage (se habilitado)

Quando o Azure MCP server está configurado, a skill azure-storage explica como usar as ferramentas azure__storage, incluindo comandos como:

• storage_account_list – lista contas de storage na sua assinatura
• storage_container_list – lista containers dentro de uma conta de storage
• storage_blob_list – lista blobs dentro de um container
• storage_blob_get – faz download do conteúdo de um blob

Essas ferramentas são ideais quando você quer que seu agent inspecione o storage existente, puxe dados de exemplo ou valide a configuração antes de escrever código.

4. Instalar os SDKs corretos para sua linguagem

O arquivo references/sdk-usage.md traz uma tabela compacta de quais pacotes de SDK instalar por linguagem e serviço, junto com exemplos de comandos de instalação.

Por exemplo, para desenvolvimento de Blob Storage em Python:

pip install azure-storage-blob azure-identity

Para Blob Storage em JavaScript/Node.js:

npm install @azure/storage-blob @azure/identity

Para Blob Storage em Java (Maven):

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
</dependency>

references/sdk-usage.md também destaca os SDKs relacionados para Queue, File Share e Data Lake, para que você mantenha sua stack consistente entre os serviços.

5. Seguir as melhores práticas de autenticação

Autenticação é frequentemente o ponto mais crítico nas integrações com Azure Storage. A skill azure-storage inclui references/auth-best-practices.md, que destila as orientações da Microsoft em regras práticas.

Os pontos principais incluem:

• Usar managed identities e Azure RBAC em produção (ambientes hospedados no Azure)
• Preferir ManagedIdentityCredential em produção; evitar depender de DefaultAzureCredential nesse contexto
• Para desenvolvimento local, DefaultAzureCredential é aceitável e conveniente
• Para pipelines de CI/CD, use AzurePipelinesCredential ou WorkloadIdentityCredential
• Para produção on-premises, use ClientCertificateCredential ou WorkloadIdentityCredential

Isso ajuda a evitar o envio de segredos, reduz divergências de configuração e torna o comportamento de autenticação previsível em todos os ambientes.

6. Começar a codificar com as referências rápidas

Depois de saber qual serviço e SDK você precisa, use os arquivos de referência rápida por linguagem em references/sdk/ para acelerar sua implementação. Por exemplo:

• references/sdk/azure-storage-blob-py.md – Blob Storage com Python
• references/sdk/azure-storage-blob-ts.md – Blob Storage com TypeScript/Node.js
• references/sdk/azure-storage-file-share-py.md e azure-storage-file-share-ts.md – Azure Files
• references/sdk/azure-storage-queue-py.md e azure-storage-queue-ts.md – Queue Storage
• references/sdk/azure-storage-file-datalake-py.md – Data Lake Storage com Python
• references/sdk/azure-data-tables-py.md e azure-data-tables-java.md – Table Storage

Cada referência rápida normalmente contém:

• Instruções de instalação para os pacotes de storage e identity
• Um trecho de Quick Start mostrando como criar um client com DefaultAzureCredential (para desenvolvimento local)
• Boas práticas de performance, tratamento de erros, design de partição (para Tables) e padrões de upload/download

Usando esses arquivos como modelos, você passa do conceito ao código funcionando com o mínimo de atrito, ainda seguindo os padrões recomendados.

7. Adaptar à sua realidade e modelo de deploy

A skill azure-storage foi pensada para ser adaptada, não simplesmente copiada. Ao adotar os padrões:

• Substitua URLs de exemplo como https://<account>.blob.core.windows.net pelos endpoints reais da sua conta
• Ajuste a escolha de credenciais conforme o ambiente (managed identity em produção, DefaultAzureCredential localmente)
• Use os comandos de CLI (az storage blob, az storage queue, etc.) presentes em SKILL.md para validar se sua conta, containers, filas e permissões estão configurados corretamente antes do deploy

Isso reduz o tempo gasto depurando problemas de conexão e permissão após a implantação.

---

FAQ

azure-storage é uma biblioteca de código ou uma skill de documentação?

azure-storage é principalmente uma skill de documentação e orientação. Ela não fornece bibliotecas de runtime próprias; em vez disso, aponta para os SDKs oficiais do Azure Storage para linguagens como Python, JavaScript/Node.js, Java, .NET, Go e Rust, e documenta como usá-los corretamente.

A skill azure-storage me ajuda a listar contas e blobs?

Sim. Se você tiver o Azure MCP server configurado, a skill explica como usar as ferramentas azure__storage, como storage_account_list, storage_container_list e storage_blob_list para enumerar contas, containers e blobs, além de storage_blob_get para baixar o conteúdo de um blob.

Quais cenários de storage são mais adequados para Blob vs Data Lake?

O SKILL.md da skill azure-storage ajuda você a decidir:

• Use Blob Storage para armazenamento de objetos em geral, backups, conteúdo de sites estáticos e workloads baseadas em arquivos
• Use Data Lake quando precisar de analytics em grande escala, namespaces hierárquicos ou integração com mecanismos de analytics que esperam semântica de Data Lake

Ambos rodam sobre a mesma plataforma subjacente; a diferença está principalmente em como você organiza e consulta os dados.

Posso usar azure-storage para Cosmos DB ou bancos de dados SQL?

Não. A skill azure-storage é focada apenas nos serviços Azure Storage. Para Cosmos DB e preparação de banco de dados mais avançada, o repositório recomenda usar azure-prepare e skills específicas de Cosmos. Para bancos de dados relacionais SQL, você deve usar ferramentas ou skills voltadas para SQL.

DefaultAzureCredential é seguro para usar em produção com azure-storage?

A skill recomenda explicitamente não usar DefaultAzureCredential em produção. Ele é ideal para desenvolvimento local, mas em produção você deve usar:

• ManagedIdentityCredential para workloads hospedadas no Azure
• ClientCertificateCredential ou WorkloadIdentityCredential para workloads on-premises
• Credenciais específicas de CI, como AzurePipelinesCredential, quando apropriado

Isso mantém a autenticação determinística, reduz a latência causada por tentativas de credenciais que falham em cascata e limita sua superfície de ataque.

azure-storage cobre tanto Python quanto JavaScript/Node.js?

Sim. references/sdk-usage.md e os arquivos em references/sdk/ incluem referências rápidas e comandos de instalação para Python e JavaScript/Node.js, além de Java, .NET, Go e Rust. Se você está construindo um backend em Python ou Node.js, encontrará exemplos prontos para adaptar para Blob, Queue, File Share, Data Lake e Tables.

Como decidir se azure-storage é o ponto de partida certo para o meu projeto?

Escolha azure-storage se:

• Sua aplicação precisa armazenar ou servir arquivos, objetos ou grandes volumes de dados a partir do Azure
• Você precisa de filas leves ou storage chave-valor sem administrar sua própria infraestrutura
• Você quer orientações claras e opinativas sobre qual SDK instalar e como autenticar com segurança

Se o foco do seu projeto é principalmente bancos relacionais, streaming de eventos de alto throughput (Event Hubs, Service Bus) ou plataformas de analytics especializadas, comece pelas skills dedicadas a esses serviços e complemente com azure-storage apenas quando adicionar recursos centrados em storage.