Azure 管理中心 API (.NET)

azure-mgmt-apicenter-dotnet
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.20/5
使用3.4K

Azure.ResourceManager.ApiCenter (.NET)

用于在组织范围内管理 API 的集中式 API 资产和治理 SDK。

安装

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

当前版本: v1.0.0 (GA)
API 版本: 2024-03-01

环境变量

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

身份验证

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

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

资源层级

code
Subscription (订阅)
└── ResourceGroup (资源组)
    └── ApiCenterService                    # API 资产服务
        ├── Workspace                       # API 的逻辑分组
        │   ├── Api                         # API 定义
        │   │   └── ApiVersion              # API 版本
        │   │       └── ApiDefinition       # OpenAPI/GraphQL 等规范
        │   ├── Environment                 # 部署目标 (dev/staging/prod)
        │   └── Deployment                  # 部署到环境的 API
        └── MetadataSchema                  # 自定义元数据定义

核心工作流

1. 创建 API Center 服务

csharp
using Azure.ResourceManager.ApiCenter;
using Azure.ResourceManager.ApiCenter.Models;

ResourceGroupResource resourceGroup = await client
    .GetDefaultSubscriptionAsync()
    .Result
    .GetResourceGroupAsync("my-resource-group");


ApiCenterServiceCollection services = resourceGroup.GetApiCenterServices();


ApiCenterServiceData data = new ApiCenterServiceData(AzureLocation.EastUS)
{
    Identity = new ManagedServiceIdentity(ManagedServiceIdentityType.SystemAssigned)
};


ArmOperation<ApiCenterServiceResource> operation = await services
    .CreateOrUpdateAsync(WaitUntil.Completed, "my-api-center", data);


ApiCenterServiceResource service = operation.Value;

2. 创建工作区 (Workspace)

csharp
ApiCenterWorkspaceCollection workspaces = service.GetApiCenterWorkspaces();

ApiCenterWorkspaceData workspaceData = new ApiCenterWorkspaceData
{
    Title = "Engineering APIs",
    Description = "工程团队拥有的 API"
};


ArmOperation<ApiCenterWorkspaceResource> operation = await workspaces
    .CreateOrUpdateAsync(WaitUntil.Completed, "engineering", workspaceData);


ApiCenterWorkspaceResource workspace = operation.Value;

3. 创建 API

csharp
ApiCenterApiCollection apis = workspace.GetApiCenterApis();

ApiCenterApiData apiData = new ApiCenterApiData
{
    Title = "Orders API",
    Description = "用于管理客户订单的 API",
    Kind = ApiKind.Rest,
    LifecycleStage = ApiLifecycleStage.Production,
    TermsOfService = new ApiTermsOfService
    {
        Uri = new Uri("https://example.com/terms")
    },
    ExternalDocumentation = 
    {
        new ApiExternalDocumentation
        {
            Title = "Documentation",
            Uri = new Uri("https://docs.example.com/orders")
        }
    },
    Contacts =
    {
        new ApiContact
        {
            Name = "API Support",
            Email = "[email protected]"

}
}
};

// 添加自定义元数据
apiData.CustomProperties = BinaryData.FromObjectAsJson(new
{
team = "orders-team",
costCenter = "CC-1234"
});

ArmOperation<ApiCenterApiResource> operation = await apis
.CreateOrUpdateAsync(WaitUntil.Completed, "orders-api", apiData);

ApiCenterApiResource api = operation.Value;

code
### 4. 创建 API 版本
csharp
ApiCenterApiVersionCollection versions = api.GetApiCenterApiVersions();

ApiCenterApiVersionData versionData = new ApiCenterApiVersionData
{
Title = "v1.0.0",
LifecycleStage = ApiLifecycleStage.Production
};

ArmOperation<ApiCenterApiVersionResource> operation = await versions
.CreateOrUpdateAsync(WaitUntil.Completed, "v1-0-0", versionData);

ApiCenterApiVersionResource version = operation.Value;

code
### 5. 创建 API 定义（上传 OpenAPI 规范）
csharp
ApiCenterApiDefinitionCollection definitions = version.GetApiCenterApiDefinitions();

ApiCenterApiDefinitionData definitionData = new ApiCenterApiDefinitionData
{
Title = "OpenAPI Specification",
Description = "Orders API OpenAPI 3.0 definition"
};

ArmOperation<ApiCenterApiDefinitionResource> operation = await definitions
.CreateOrUpdateAsync(WaitUntil.Completed, "openapi", definitionData);

ApiCenterApiDefinitionResource definition = operation.Value;

// 导入规范
string openApiSpec = await File.ReadAllTextAsync("orders-api.yaml");

ApiSpecImportContent importContent = new ApiSpecImportContent
{
Format = ApiSpecImportSourceFormat.Inline,
Value = openApiSpec,
Specification = new ApiSpecImportSpecification
{
Name = "openapi",
Version = "3.0.1"
}
};

await definition.ImportSpecificationAsync(WaitUntil.Completed, importContent);

code
### 6. 导出 API 规范
csharp
ApiCenterApiDefinitionResource definition = await client
.GetApiCenterApiDefinitionResource(definitionResourceId)
.GetAsync();

ArmOperation<ApiSpecExportResult> operation = await definition
.ExportSpecificationAsync(WaitUntil.Completed);

ApiSpecExportResult result = operation.Value;

// result.Format - 例如 "inline"
// result.Value - 规范内容

code
### 7. 创建环境
csharp
ApiCenterEnvironmentCollection environments = workspace.GetApiCenterEnvironments();

ApiCenterEnvironmentData envData = new ApiCenterEnvironmentData
{
Title = "Production",
Description = "Production environment",
Kind = ApiCenterEnvironmentKind.Production,
Server = new ApiCenterEnvironmentServer
{
ManagementPortalUris = { new Uri("https://portal.azure.com") }
},
Onboarding = new EnvironmentOnboardingModel
{
Instructions = "Contact platform team for access",
DeveloperPortalUris = { new Uri("https://developer.example.com") }
}
};

ArmOperation<ApiCenterEnvironmentResource> operation = await environments
.CreateOrUpdateAsync(WaitUntil.Completed, "production", envData);

code
### 8. 创建部署
csharp
ApiCenterDeploymentCollection deployments = workspace.GetApiCenterDeployments();

// 获取环境资源 ID
ResourceIdentifier envResourceId = ApiCenterEnvironmentResource.CreateResourceIdentifier(
subscriptionId, resourceGroupName, serviceName, workspaceName, "production");

// 获取 API 定义资源 ID
ResourceIdentifier definitionResourceId = ApiCenterApiDefinitionResource.CreateResourceIdentifier(
subscriptionId, resourceGroupName, serviceName, workspaceName,
"orders-api",

code
"v1-0-0", "openapi");


ApiCenterDeploymentData deploymentData = new ApiCenterDeploymentData
{
    Title = "Orders API - Production",
    Description = "Production deployment of Orders API v1.0.0",
    EnvironmentId = envResourceId,
    DefinitionId = definitionResourceId,
    State = ApiCenterDeploymentState.Active,
    Server = new ApiCenterDeploymentServer
    {
        RuntimeUris = { new Uri("https://api.example.com/orders") }
    }
};


ArmOperation<ApiCenterDeploymentResource> operation = await deployments
    .CreateOrUpdateAsync(WaitUntil.Completed, "orders-api-prod", deploymentData);

9. 创建元数据架构 (Metadata Schema)

csharp
ApiCenterMetadataSchemaCollection schemas = service.GetApiCenterMetadataSchemas();

string jsonSchema = """
{
    "type": "object",
    "properties": {
        "team": {
            "type": "string",
            "title": "Owning Team"
        },
        "costCenter": {
            "type": "string",
            "title": "Cost Center"
        },
        "dataClassification": {
            "type": "string",
            "enum": ["public", "internal", "confidential"],
            "title": "Data Classification"
        }
    },
    "required": ["team"]
}
""";


ApiCenterMetadataSchemaData schemaData = new ApiCenterMetadataSchemaData
{
    Schema = jsonSchema,
    AssignedTo =
    {
        new MetadataAssignment
        {
            Entity = MetadataAssignmentEntity.Api,
            Required = true
        }
    }
};


ArmOperation<ApiCenterMetadataSchemaResource> operation = await schemas
    .CreateOrUpdateAsync(WaitUntil.Completed, "api-metadata", schemaData);

10. 列出并搜索 API

csharp
// 列出工作区中的所有 API
ApiCenterWorkspaceResource workspace = await client
    .GetApiCenterWorkspaceResource(workspaceResourceId)
    .GetAsync();

await foreach (ApiCenterApiResource api in workspace.GetApiCenterApis())
{
    Console.WriteLine($"API: {api.Data.Title}");
    Console.WriteLine($"  Kind: {api.Data.Kind}");
    Console.WriteLine($"  Stage: {api.Data.LifecycleStage}");
    
    // 列出版本
    await foreach (ApiCenterApiVersionResource version in api.GetApiCenterApiVersions())
    {
        Console.WriteLine($"  Version: {version.Data.Title}");
    }
}


// 列出环境
await foreach (ApiCenterEnvironmentResource env in workspace.GetApiCenterEnvironments())
{
    Console.WriteLine($"Environment: {env.Data.Title} ({env.Data.Kind})");
}


// 列出部署
await foreach (ApiCenterDeploymentResource deployment in workspace.GetApiCenterDeployments())
{
    Console.WriteLine($"Deployment: {deployment.Data.Title}");
    Console.WriteLine($"  State: {deployment.Data.State}");
}

关键类型参考

| 类型 | 用途 |
|------|---------|
| 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 | ac
有效，无效 |

最佳实践

1. 使用工作区组织 — 按团队、领域或产品对 API 进行分组
2. 使用元数据架构 — 定义自定义属性以进行治理
3. 跟踪生命周期阶段 — 保持 API 状态实时更新（设计 $\rightarrow$ 生产 $\rightarrow$ 弃用）
4. 记录环境 — 包含引导指令和门户 URI
5. 保持版本一致性 — 对 API 版本使用语义化版本控制
6. 导入规范 — 上传 OpenAPI/GraphQL 规范以便于发现
7. 关联部署 — 将 API 连接到其运行时环境
8. 使用托管标识 — 启用 SystemAssigned 标识以实现安全集成

错误处理

csharp
using Azure;

try
{
    ArmOperation<ApiCenterApiResource> operation = await apis
        .CreateOrUpdateAsync(WaitUntil.Completed, "my-api", apiData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
    Console.WriteLine("API 已存在且配置冲突");
}
catch (RequestFailedException ex) when (ex.Status == 400)
{
    Console.WriteLine($"请求无效: {ex.Message}");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Azure 错误: {ex.Status} - {ex.Message}");
}

相关 SDK

| SDK | 用途 | 安装 |
|-----|---------|---------|
| Azure.ResourceManager.ApiCenter | API Center 管理（本 SDK） | dotnet add package Azure.ResourceManager.ApiCenter |
| Azure.ResourceManager.ApiManagement | API 网关和策略 | dotnet add package Azure.ResourceManager.ApiManagement |

参考链接

| 资源 | URL |
|----------|-----|
| 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 |

适用场景

本技能适用于执行概述中描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。