Azure API 管理 .NET 管理 SDK

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

Azure.ResourceManager.ApiManagement (.NET)

用于通过 Azure Resource Manager 部署和管理 Azure API Management 资源的管理平面 SDK。

> ⚠️ 管理平面 vs 数据平面
> - 本 SDK (Azure.ResourceManager.ApiManagement)：创建服务、API、产品、订阅、策略、用户、组
> - 数据平面：直接调用 APIM 网关端点的 API 请求

安装

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

当前版本：v1.3.0

环境变量

bash
AZURE_SUBSCRIPTION_ID=<your-subscription-id>

用于服务主体身份验证（可选）

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

身份验证

csharp
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ApiManagement;

// 始终使用 DefaultAzureCredential
var credential = new DefaultAzureCredential();
var armClient = new ArmClient(credential);


// 获取订阅
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
var subscription = armClient.GetSubscriptionResource(
    new ResourceIdentifier($"/subscriptions/{subscriptionId}"));

资源层级

code
ArmClient
└── SubscriptionResource
    └── ResourceGroupResource
        └── ApiManagementServiceResource
            ├── ApiResource
            │   ├── ApiOperationResource
            │   │   └── ApiOperationPolicyResource
            │   ├── ApiPolicyResource
            │   ├── ApiSchemaResource
            │   └── ApiDiagnosticResource
            ├── ApiManagementProductResource
            │   ├── ProductApiResource
            │   ├── ProductGroupResource
            │   └── ProductPolicyResource
            ├── ApiManagementSubscriptionResource
            ├── ApiManagementPolicyResource
            ├── ApiManagementUserResource
            ├── ApiManagementGroupResource
            ├── ApiManagementBackendResource
            ├── ApiManagementGatewayResource
            ├── ApiManagementCertificateResource
            ├── ApiManagementNamedValueResource
            └── ApiManagementLoggerResource

核心工作流

1. 创建 API Management 服务

csharp
using Azure.ResourceManager.ApiManagement;
using Azure.ResourceManager.ApiManagement.Models;

// 获取资源组
var resourceGroup = await subscription
    .GetResourceGroupAsync("my-resource-group");


// 定义服务
var serviceData = new ApiManagementServiceData(
    location: AzureLocation.EastUS,
    sku: new ApiManagementServiceSkuProperties(
        ApiManagementServiceSkuType.Developer, 
        capacity: 1),
    publisherEmail: "[email protected]",
    publisherName: "Contoso");


// 创建服务（长时间运行的操作 - 可能需要 30 分钟以上）
var serviceCollection = resourceGroup.Value.GetApiManagementServices();
var operation = await serviceCollection.CreateOrUpdateAsync(
    WaitUntil.Completed,
    "my-apim-service",
    serviceData);


ApiManagementServiceResource service = operation.Value;

2. 创建 API

csharp
var apiData = new ApiCreateOrUpdateContent
{
    DisplayName = "My API",
    Path = "myapi",
    Protocols = { ApiOperationInvokableProtocol.Https },
    ServiceUri = new Uri("https://backend.contoso.com/api")
};

var api

Collection = service.GetApis();
var apiOperation = await apiCollection.CreateOrUpdateAsync(
WaitUntil.Completed,
"my-api",
apiData);

ApiResource api = apiOperation.Value;

code
### 3. 创建产品
csharp
var productData = new ApiManagementProductData
{
DisplayName = "Starter",
Description = "Starter tier with limited access",
IsSubscriptionRequired = true,
IsApprovalRequired = false,
SubscriptionsLimit = 1,
State = ApiManagementProductState.Published
};

var productCollection = service.GetApiManagementProducts();
var productOperation = await productCollection.CreateOrUpdateAsync(
WaitUntil.Completed,
"starter",
productData);

ApiManagementProductResource product = productOperation.Value;

// 将 API 添加到产品中
await product.GetProductApis().CreateOrUpdateAsync(
WaitUntil.Completed,
"my-api");

code
### 4. 创建订阅
csharp
var subscriptionData = new ApiManagementSubscriptionCreateOrUpdateContent
{
DisplayName = "My Subscription",
Scope = $"/products/{product.Data.Name}",
State = ApiManagementSubscriptionState.Active
};

var subscriptionCollection = service.GetApiManagementSubscriptions();
var subOperation = await subscriptionCollection.CreateOrUpdateAsync(
WaitUntil.Completed,
"my-subscription",
subscriptionData);

ApiManagementSubscriptionResource subscription = subOperation.Value;

// 获取订阅密钥
var keys = await subscription.GetSecretsAsync();
Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}");

code
### 5. 设置 API 策略
csharp
var policyXml = @"
<policies>
<inbound>
<rate-limit calls=""100"" renewal-period=""60"" />
<set-header name=""X-Custom-Header"" exists-action=""override"">
<value>CustomValue</value>
</set-header>
<base />
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
</outbound>
<on-error>
<base />
</on-error>
</policies>";

var policyData = new PolicyContractData
{
Value = policyXml,
Format = PolicyContentFormat.Xml
};

await api.GetApiPolicy().CreateOrUpdateAsync(
WaitUntil.Completed,
policyData);

code
### 6. 备份与还原
csharp
// 备份
var backupParams = new ApiManagementServiceBackupRestoreContent(
storageAccount: "mystorageaccount",
containerName: "apim-backups",
backupName: "backup-2024-01-15")
{
AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity
};

await service.BackupAsync(WaitUntil.Completed, backupParams);

// 还原
await service.RestoreAsync(WaitUntil.Completed, backupParams);

code
## 关键类型参考


| 类型 | 用途 |
|------|---------|
| ArmClient | 所有 ARM 操作的入口点 |
| ApiManagementServiceResource | 表示一个 APIM 服务实例 |
| ApiManagementServiceCollection | 用于服务 CRUD 的集合 |
| ApiResource | 表示一个 API |
| ApiManagementProductResource | 表示一个产品 |
| ApiManagementSubscriptionResource | 表示一个订阅 |
| ApiManagementPolicyResource | 服务级策略 |
| ApiPolicyResource | API 级策略 |
| ApiManagementUserResource | 表示一个用户 |
| ApiManagementGroupResource | 表示一个组 |
| ApiManagementBackendResource | 表示一个后端服务 |
| ApiManagementGatewayResource | 表示一个自托管网关 |


SKU 类型


| SKU | 用途 | 容量 |
|-----|---------|----------|
| Developer | 开发 |
| 开发/测试（无 SLA） | 1 |
| Basic | 入门级生产环境 | 1-2 |
| Standard | 中型工作负载 | 1-4 |
| Premium | 高可用性，多区域 | 每个区域 1-12 |
| Consumption | Serverless，按调用付费 | N/A |


最佳实践


1. 对于必须在继续之前完成的操作，请使用 WaitUntil.Completed
2. 对于耗时较长的操作（如服务创建，需 30 分钟以上），请使用 WaitUntil.Started
3. 始终使用 DefaultAzureCredential —— 切勿硬编码密钥
4. 使用 RequestFailedException 处理 ARM API 错误
5. 对于幂等操作，请使用 CreateOrUpdateAsync
6. 通过 Get* 方法导航层级结构（例如 service.GetApis()）
7. 策略格式 —— 策略请使用 XML 格式；同时也支持 JSON
8. 服务创建 —— 测试时使用 Developer SKU 速度最快（约 15-30 分钟）


错误处理
csharp using Azure;

try
{
var operation = await serviceCollection.CreateOrUpdateAsync(
WaitUntil.Completed, serviceName, serviceData);
}
catch (RequestFailedException ex) when (ex.Status == 409)
{
Console.WriteLine("Service already exists");
}
catch (RequestFailedException ex) when (ex.Status == 400)
{
Console.WriteLine($"Bad request: {ex.Message}");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"ARM Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}
```

参考文件

| 文件 | 阅读时机 |
|------|--------------|
| references/service-management.md | 服务 CRUD、SKU、网络、备份/还原 |
| references/apis-operations.md | API、操作、架构、版本控制 |
| references/products-subscriptions.md | 产品、订阅、访问控制 |
| references/policies.md | 策略 XML 模式、范围、常用策略 |

相关资源

| 资源 | 用途 |
|----------|---------|
| API Management Documentation | Azure 官方文档 |
| Policy Reference | 完整策略参考 |
| SDK Reference | .NET API 参考 |

使用场景

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

局限性

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