azure-storage

概览

azure-storage 技能能做什么

azure-storage 技能是一份聚焦 Microsoft Azure Storage Services 的实用指南，覆盖：

• Blob Storage – 面向备份、静态资源和海量数据文件的对象和文件存储
• Azure Files (File Shares) – 适合“平移式迁移（lift-and-shift）”负载的 SMB 兼容文件共享
• Queue Storage – 轻量级异步消息和后台任务队列
• Table Storage – 适用于简单、无固定模式数据的 NoSQL 键值存储
• Azure Data Lake – 带层级命名空间的大数据分析存储

此技能本身不会新增任何 SDK 或 CLI。它的作用是帮助你：

• 为你的业务场景选择合适的 Azure Storage 服务
• 使用（如可用）MCP server 工具列出账号、容器和 blob
• 安装合适的 语言 SDK（Python、JavaScript/Node.js、Java、.NET、Go、Rust）
• 遵循 身份验证最佳实践，避免在代码中硬编码机密或误用 DefaultAzureCredential

适合哪些人使用

如果你是以下角色，推荐使用 azure-storage 技能：

• 后端开发者：需要在 API、服务或后台任务中集成 Azure Storage
• 云工程师或 DevOps：希望在团队内规范 Azure Storage 的使用方式
• 数据或分析工程师：需要快速理解 Data Lake 与 Blob Storage 的区别和选型
• Agent / MCP 用户：希望构建“存储感知”的工作流（通过 azure__storage 列出 storage accounts、containers 和 blobs）

azure-storage 技能能帮你解决哪些问题

通过这个技能，你可以快速回答类似问题：

• 针对 文件 vs 消息 vs 键值数据，应该使用哪种 Azure Storage 服务？
• 如何通过 MCP server 列出 storage accounts、containers 和 blobs？
• 在我使用的语言中，Blob、Queue、File Share 或 Data Lake 应该安装哪个 SDK package？
• 如何使用托管身份和 Azure RBAC 配置 免密（passwordless）身份验证？
• 在什么情况下应该使用 DefaultAzureCredential，又在什么情况下应该避免？

什么时候适合／不适合用 azure-storage

推荐在以下场景使用 azure-storage：

• 将 Blob Storage 集成到 API 或微服务中
• 挂载或管理用于“平移式迁移（lift-and-shift）”的 file shares
• 使用 Azure Queue Storage 实现 异步队列
• 在 Table Storage 中存储和查询 简单键值或实体数据
• 使用 Azure Data Lake 存放分析型数据

不推荐在以下场景使用 azure-storage：

• 关系型 SQL 数据库（请使用 Azure SQL 或其他数据库专用技能）
• Cosmos DB 工作流（请改用 azure-prepare 和 Cosmos 专用技能）
• Event Hubs 或 Service Bus 消息场景（请使用 azure-messaging 及相关技能）

如果你的工作负载主要是事务型 SQL 或高层次事件流处理，这个技能并不是最佳的入门点。

---

使用方法

1. 安装 azure-storage 技能

要在 agent 环境中使用 azure-storage，请从 microsoft/azure-skills 仓库安装：

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

安装完成后，该技能会暴露一系列文档和参考内容，供你的 agent（或你自己在 Files 视图中）查看，包括：

• SKILL.md – 对支持的服务和工具的高层概述
• references/auth-best-practices.md – 推荐的身份验证模式
• references/sdk-usage.md – 跨语言 SDK 总览与安装命令
• references/sdk/*.md – 各语言的 Blob、Queue、File Share、Data Lake 和 Tables 快速参考

如果你的环境中启用了 Azure MCP server，该技能还会与 azure__storage 工具集成，用于账号和 blob 操作。

2. 了解可用的服务和工具

首先打开 SKILL.md。其中包含一个 Services matrix，说明每种存储服务的适用场景以及可搭配使用的工具：

• Blob Storage – 通用对象存储
  • MCP: azure__storage
  • CLI: az storage blob
• File Shares – SMB 文件共享
  • CLI: az storage file
• Queue Storage – 异步消息
  • CLI: az storage queue
• Table Storage – 键值实体
  • CLI: az storage table
• Data Lake – 分析场景与层级命名空间
  • CLI: az storage fs

这能帮助你在写代码之前先选对服务类型和 CLI 命令集。

3. 使用 MCP server 进行存储发现（如已启用）

当 Azure MCP server 配置完成后，azure-storage 技能会说明如何使用 azure__storage 工具，包括如下命令：

• storage_account_list – 列出订阅中的 storage accounts
• storage_container_list – 列出某个 storage account 下的 containers
• storage_blob_list – 列出某个 container 中的 blobs
• storage_blob_get – 下载 blob 内容

这些工具非常适合让你的 agent 在编写代码前先 检查现有存储、拉取样例数据或验证配置。

4. 为你的语言安装合适的 SDK

references/sdk-usage.md 文件提供了一张精简表格，列出了各语言、各服务对应的 SDK packages 以及安装示例命令。

例如，针对 Python 的 Blob Storage 开发：

pip install azure-storage-blob azure-identity

针对 JavaScript/Node.js 的 Blob Storage：

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

针对 Java（Maven） 的 Blob Storage：

<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 还会指出 Queue、File Share 和 Data Lake 对应的相关 SDK，帮助你在各服务之间保持技术栈一致性。

5. 遵循身份验证最佳实践

Azure Storage 集成最容易出问题的环节往往就是身份验证。azure-storage 技能中的 references/auth-best-practices.md 将 Microsoft 官方建议提炼成可操作的规则。

核心要点包括：

• 在生产环境（Azure 托管环境）使用 managed identities 和 Azure RBAC
• 生产环境优先使用 ManagedIdentityCredential，避免依赖 DefaultAzureCredential
• 在 本地开发 中，DefaultAzureCredential 方便且可接受
• 在 CI/CD 流水线中使用 AzurePipelinesCredential 或 WorkloadIdentityCredential
• 在 本地机房生产环境 中使用 ClientCertificateCredential 或 WorkloadIdentityCredential

通过这些实践，可以避免泄露机密，减少配置偏差，让不同环境中的身份验证行为更可预期。

6. 使用快速参考开始编码

在确定要使用的服务和 SDK 之后，可以通过 references/sdk/ 下的各语言快速参考文件来加速实现。例如：

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

每份快速参考通常包含：

• Install 指引：如何安装存储和身份验证相关 packages
• Quick Start 代码片段：演示如何使用 DefaultAzureCredential 构建 client（用于本地开发）
• 最佳实践：性能优化、错误处理、分区设计（针对 Tables）以及上传/下载模式等

将这些示例作为模板，你可以在遵循推荐模式的前提下，从概念快速落地到可运行代码。

7. 结合你的环境和部署模型进行调整

azure-storage 技能的设计初衷是方便你 按需调整和采用模式，而不是原样复制全部内容。在落地这些模式时，请：

• 将 https://<account>.blob.core.windows.net 等占位 URL 替换为你实际的账号 endpoint
• 根据运行环境选择合适的凭据（生产环境使用 managed identity，本地使用 DefaultAzureCredential）
• 使用 SKILL.md 中的 CLI 命令（如 az storage blob, az storage queue 等）在部署前验证账号、容器、队列及权限配置是否正确

这样可以显著减少部署后排查连接和权限问题所耗费的时间。

---

常见问题（FAQ）

azure-storage 是代码库还是文档类技能？

azure-storage 主要是一个 文档和指导类技能。它本身不提供运行时库，而是指引你使用 Azure 官方的 Storage SDK（如 Python、JavaScript/Node.js、Java、.NET、Go、Rust 等），并说明如何正确使用这些 SDK。

azure-storage 技能能帮我列出账号和 blobs 吗？

可以。如果已配置 Azure MCP server，该技能会说明如何使用 azure__storage 工具，例如 storage_account_list、storage_container_list 和 storage_blob_list 来枚举账号、containers 和 blobs，并使用 storage_blob_get 下载 blob 内容。

哪些存储场景适合用 Blob，哪些适合用 Data Lake？

azure-storage 技能的 SKILL.md 会帮你做决策：

• 当你需要通用对象存储、备份、静态网站内容或类文件工作负载时，使用 Blob Storage
• 当你需要大数据分析、层级命名空间，或需要与依赖 Data Lake 语义的分析引擎集成时，使用 Data Lake

两者运行在同一底层平台之上，因此主要区别在于你如何组织和查询数据。

我可以用 azure-storage 操作 Cosmos DB 或 SQL 数据库吗？

不可以。azure-storage 技能专注于 Azure Storage 系列服务。要管理 Cosmos DB 或更高级的数据库准备场景，仓库推荐使用 azure-prepare 及 Cosmos 专用技能；对关系型 SQL 数据库，则应使用面向 SQL 的工具或技能。

在 azure-storage 中，DefaultAzureCredential 在生产环境使用安全吗？

该技能明确建议 不要 在生产环境使用 DefaultAzureCredential。它非常适合 本地开发，但在生产环境中应改为：

• 对 Azure 托管工作负载使用 ManagedIdentityCredential
• 对本地机房工作负载使用 ClientCertificateCredential 或 WorkloadIdentityCredential
• 在 CI 环境中使用 AzurePipelinesCredential 等专用凭据

这样可以让身份验证行为更可控，减少因多重凭据回退造成的延迟，并降低攻击面。

azure-storage 是否同时覆盖 Python 和 JavaScript/Node.js？

是的。references/sdk-usage.md 以及 references/sdk/ 下的文件提供了 Python 和 JavaScript/Node.js 的快速参考和安装命令，同时也包括 Java、.NET、Go 和 Rust。如果你在使用 Python 或 Node.js 构建后端，会找到可以直接改造使用的 Blob、Queue、File Share、Data Lake 和 Tables 示例。

我如何判断 azure-storage 是否适合作为项目的起点？

在以下情况下，优先选择 azure-storage：

• 你的应用需要在 Azure 中存储或对外提供文件、对象或大规模数据集
• 你需要轻量级队列或键值存储，而不想自建和维护基础设施
• 你希望获得关于 安装哪个 SDK 以及 如何安全进行身份验证 的明确、带倾向性的指导

如果你的项目主要聚焦在关系型数据库、高吞吐事件流（Event Hubs、Service Bus）或专业分析平台，建议先从这些服务的专用技能入手，当项目增加存储相关功能时，再搭配使用 azure-storage。