azure-mgmt-apicenter-dotnet

用途

Azure.ResourceManager.ApiCenter 是 Azure API Center 的 .NET 管理 SDK，用于在整个组织范围内集中管理 API 清单，提供治理、版本管理与 API 发现能力。

安装与认证

安装命令：

dotnet add package Azure.ResourceManager.ApiCenter dotnet add package Azure.Identity

当前版本：v1.0.0（GA）；API 版本：2024-03-01。

环境变量：

AZURE_SUBSCRIPTION_ID=<your-subscription-id> AZURE_RESOURCE_GROUP=<your-resource-group> AZURE_APICENTER_SERVICE_NAME=<your-apicenter-service>

认证示例：

using Azure.Identity; using Azure.ResourceManager; using Azure.ResourceManager.ApiCenter;

ArmClient client = new ArmClient(new DefaultAzureCredential());

资源层级

Subscription └── ResourceGroup └── ApiCenterService # API inventory service ├── Workspace # Logical grouping of APIs │ ├── Api # API definition │ │ └── ApiVersion # Version of the API │ │ └── ApiDefinition # OpenAPI/GraphQL/etc specification │ ├── Environment # Deployment target (dev/staging/prod) │ └── Deployment # API deployed to environment └── MetadataSchema # Custom metadata definitions

主要能力与使用方式

SDK 覆盖以下核心工作流，均通过 ArmClient 与各资源的集合方法完成：

创建 API Center 服务：使用 ApiCenterServiceCollection.CreateOrUpdateAsync，可配置托管标识（如 SystemAssigned）。
创建工作区：使用 ApiCenterWorkspaceCollection.CreateOrUpdateAsync，按团队或领域分组 API。
创建 API：使用 ApiCenterApiCollection.CreateOrUpdateAsync，可设置标题、描述、Kind（Rest 等）、生命周期阶段、服务条款、外部文档、联系人，并通过 CustomProperties 添加自定义元数据。
创建 API 版本：使用 ApiCenterApiVersionCollection.CreateOrUpdateAsync，设置标题与生命周期阶段。
创建 API 定义并导入规范：使用 ApiCenterApiDefinitionCollection.CreateOrUpdateAsync 创建定义，再通过 ImportSpecificationAsync 导入 OpenAPI 等规范（支持 Inline 格式）。
导出 API 规范：使用 ExportSpecificationAsync 获取规范内容与格式。
创建环境：使用 ApiCenterEnvironmentCollection.CreateOrUpdateAsync，设置类型、管理门户 URI、入门说明与开发者门户 URI。
创建部署：使用 ApiCenterDeploymentCollection.CreateOrUpdateAsync，关联环境资源 ID 与定义资源 ID，设置状态与运行时 URI。
创建元数据架构：使用 ApiCenterMetadataSchemaCollection.CreateOrUpdateAsync，传入 JSON Schema 并指定分配实体（如 Api）与是否必填。
列举与搜索 API：通过工作区的 GetApiCenterApis、GetApiCenterEnvironments、GetApiCenterDeployments 等方法遍历 API、版本、环境与部署。

关键类型

ApiCenterServiceResource：API Center 服务实例
ApiCenterWorkspaceResource：API 的逻辑分组
ApiCenterApiResource：单个 API
ApiCenterApiVersionResource：API 版本
ApiCenterApiDefinitionResource：API 规范（OpenAPI 等）
ApiCenterEnvironmentResource：部署环境
ApiCenterDeploymentResource：API 到环境的部署
ApiCenterMetadataSchemaResource：自定义元数据架构

枚举：ApiKind（rest、graphql、grpc、soap、webhook、websocket、mcp）；ApiLifecycleStage（design、development、testing、preview、production、deprecated、retired）；ApiCenterEnvironmentKind（development、testing、staging、production）；ApiCenterDeploymentState（active、inactive）。

适用场景

适用于需要集中登记、治理与发现组织内 API 的团队，例如按团队/领域组织 API、定义自定义元数据用于治理、跟踪 API 生命周期、记录环境与入门信息、统一版本管理、导入规范以供发现、将 API 关联到运行时环境，以及使用托管标识进行安全集成。

最佳实践

用工作区组织 API（按团队、领域或产品）
使用元数据架构定义自定义治理属性
跟踪生命周期阶段（design → production → deprecated）
记录环境信息，包括入门说明与门户 URI
版本保持一致，使用语义化版本
导入规范（OpenAPI/GraphQL）以便发现
关联部署到运行时环境
启用 SystemAssigned 托管标识用于安全集成

错误处理

可使用 RequestFailedException 捕获 Azure 错误，例如 409 表示配置冲突、400 表示请求无效。

参考链接

NuGet 包：https://www.nuget.org/packages/Azure.ResourceManager.ApiCenter
API 参考：https://learn.microsoft.com/dotnet/api/azure.resourcemanager.apicenter
产品文档：https://learn.microsoft.com/azure/api-center/
GitHub 源码：https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/apicenter/Azure.ResourceManager.ApiCenter

限制

仅当任务明确匹配上述范围时使用本技能。不应将输出视为环境特定验证、测试或专家评审的替代。若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。

技能介绍

用途