refactor: flatten Microsoft skills from nested to flat directory structure
Rewrote sync_microsoft_skills.py (v4) to use each SKILL.md's frontmatter 'name' field as the flat directory name under skills/, replacing the nested skills/official/microsoft/<lang>/<category>/<service>/ hierarchy. This fixes CI failures caused by the indexing, validation, and catalog scripts expecting skills/<id>/SKILL.md (depth 1). Changes: - Rewrite scripts/sync_microsoft_skills.py for flat output with collision detection - Update scripts/tests/inspect_microsoft_repo.py for flat name mapping - Update scripts/tests/test_comprehensive_coverage.py for name uniqueness checks - Delete skills/official/ nested directory - Add 129 Microsoft skills as flat directories (e.g. skills/azure-mgmt-botservice-dotnet/) - Move attribution files to docs/ (LICENSE-MICROSOFT, microsoft-skills-attribution.json) - Rebuild skills_index.json, CATALOG.md, README.md (845 total skills)
This commit is contained in:
Ahmed Rehan
310
skills/azure-mgmt-apimanagement-dotnet/SKILL.md
Normal file
310
skills/azure-mgmt-apimanagement-dotnet/SKILL.md
Normal file
@@ -0,0 +1,310 @@
|
||||
---
|
||||
name: azure-mgmt-apimanagement-dotnet
|
||||
description: |
|
||||
Azure Resource Manager SDK for API Management in .NET. Use for MANAGEMENT PLANE operations: creating/managing APIM services, APIs, products, subscriptions, policies, users, groups, gateways, and backends via Azure Resource Manager. Triggers: "API Management", "APIM service", "create APIM", "manage APIs", "ApiManagementServiceResource", "API policies", "APIM products", "APIM subscriptions".
|
||||
package: Azure.ResourceManager.ApiManagement
|
||||
---
|
||||
|
||||
# Azure.ResourceManager.ApiManagement (.NET)
|
||||
|
||||
Management plane SDK for provisioning and managing Azure API Management resources via Azure Resource Manager.
|
||||
|
||||
> **⚠️ Management vs Data Plane**
|
||||
> - **This SDK (Azure.ResourceManager.ApiManagement)**: Create services, APIs, products, subscriptions, policies, users, groups
|
||||
> - **Data Plane**: Direct API calls to your APIM gateway endpoints
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
dotnet add package Azure.ResourceManager.ApiManagement
|
||||
dotnet add package Azure.Identity
|
||||
```
|
||||
|
||||
**Current Version**: v1.3.0
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
AZURE_SUBSCRIPTION_ID=<your-subscription-id>
|
||||
# For service principal auth (optional)
|
||||
AZURE_TENANT_ID=<tenant-id>
|
||||
AZURE_CLIENT_ID=<client-id>
|
||||
AZURE_CLIENT_SECRET=<client-secret>
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
```csharp
|
||||
using Azure.Identity;
|
||||
using Azure.ResourceManager;
|
||||
using Azure.ResourceManager.ApiManagement;
|
||||
|
||||
// Always use DefaultAzureCredential
|
||||
var credential = new DefaultAzureCredential();
|
||||
var armClient = new ArmClient(credential);
|
||||
|
||||
// Get subscription
|
||||
var subscriptionId = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID");
|
||||
var subscription = armClient.GetSubscriptionResource(
|
||||
new ResourceIdentifier($"/subscriptions/{subscriptionId}"));
|
||||
```
|
||||
|
||||
## Resource Hierarchy
|
||||
|
||||
```
|
||||
ArmClient
|
||||
└── SubscriptionResource
|
||||
└── ResourceGroupResource
|
||||
└── ApiManagementServiceResource
|
||||
├── ApiResource
|
||||
│ ├── ApiOperationResource
|
||||
│ │ └── ApiOperationPolicyResource
|
||||
│ ├── ApiPolicyResource
|
||||
│ ├── ApiSchemaResource
|
||||
│ └── ApiDiagnosticResource
|
||||
├── ApiManagementProductResource
|
||||
│ ├── ProductApiResource
|
||||
│ ├── ProductGroupResource
|
||||
│ └── ProductPolicyResource
|
||||
├── ApiManagementSubscriptionResource
|
||||
├── ApiManagementPolicyResource
|
||||
├── ApiManagementUserResource
|
||||
├── ApiManagementGroupResource
|
||||
├── ApiManagementBackendResource
|
||||
├── ApiManagementGatewayResource
|
||||
├── ApiManagementCertificateResource
|
||||
├── ApiManagementNamedValueResource
|
||||
└── ApiManagementLoggerResource
|
||||
```
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Create API Management Service
|
||||
|
||||
```csharp
|
||||
using Azure.ResourceManager.ApiManagement;
|
||||
using Azure.ResourceManager.ApiManagement.Models;
|
||||
|
||||
// Get resource group
|
||||
var resourceGroup = await subscription
|
||||
.GetResourceGroupAsync("my-resource-group");
|
||||
|
||||
// Define service
|
||||
var serviceData = new ApiManagementServiceData(
|
||||
location: AzureLocation.EastUS,
|
||||
sku: new ApiManagementServiceSkuProperties(
|
||||
ApiManagementServiceSkuType.Developer,
|
||||
capacity: 1),
|
||||
publisherEmail: "admin@contoso.com",
|
||||
publisherName: "Contoso");
|
||||
|
||||
// Create service (long-running operation - can take 30+ minutes)
|
||||
var serviceCollection = resourceGroup.Value.GetApiManagementServices();
|
||||
var operation = await serviceCollection.CreateOrUpdateAsync(
|
||||
WaitUntil.Completed,
|
||||
"my-apim-service",
|
||||
serviceData);
|
||||
|
||||
ApiManagementServiceResource service = operation.Value;
|
||||
```
|
||||
|
||||
### 2. Create an API
|
||||
|
||||
```csharp
|
||||
var apiData = new ApiCreateOrUpdateContent
|
||||
{
|
||||
DisplayName = "My API",
|
||||
Path = "myapi",
|
||||
Protocols = { ApiOperationInvokableProtocol.Https },
|
||||
ServiceUri = new Uri("https://backend.contoso.com/api")
|
||||
};
|
||||
|
||||
var apiCollection = service.GetApis();
|
||||
var apiOperation = await apiCollection.CreateOrUpdateAsync(
|
||||
WaitUntil.Completed,
|
||||
"my-api",
|
||||
apiData);
|
||||
|
||||
ApiResource api = apiOperation.Value;
|
||||
```
|
||||
|
||||
### 3. Create a Product
|
||||
|
||||
```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;
|
||||
|
||||
// Add API to product
|
||||
await product.GetProductApis().CreateOrUpdateAsync(
|
||||
WaitUntil.Completed,
|
||||
"my-api");
|
||||
```
|
||||
|
||||
### 4. Create a Subscription
|
||||
|
||||
```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;
|
||||
|
||||
// Get subscription keys
|
||||
var keys = await subscription.GetSecretsAsync();
|
||||
Console.WriteLine($"Primary Key: {keys.Value.PrimaryKey}");
|
||||
```
|
||||
|
||||
### 5. Set API Policy
|
||||
|
||||
```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);
|
||||
```
|
||||
|
||||
### 6. Backup and Restore
|
||||
|
||||
```csharp
|
||||
// Backup
|
||||
var backupParams = new ApiManagementServiceBackupRestoreContent(
|
||||
storageAccount: "mystorageaccount",
|
||||
containerName: "apim-backups",
|
||||
backupName: "backup-2024-01-15")
|
||||
{
|
||||
AccessType = StorageAccountAccessType.SystemAssignedManagedIdentity
|
||||
};
|
||||
|
||||
await service.BackupAsync(WaitUntil.Completed, backupParams);
|
||||
|
||||
// Restore
|
||||
await service.RestoreAsync(WaitUntil.Completed, backupParams);
|
||||
```
|
||||
|
||||
## Key Types Reference
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| `ArmClient` | Entry point for all ARM operations |
|
||||
| `ApiManagementServiceResource` | Represents an APIM service instance |
|
||||
| `ApiManagementServiceCollection` | Collection for service CRUD |
|
||||
| `ApiResource` | Represents an API |
|
||||
| `ApiManagementProductResource` | Represents a product |
|
||||
| `ApiManagementSubscriptionResource` | Represents a subscription |
|
||||
| `ApiManagementPolicyResource` | Service-level policy |
|
||||
| `ApiPolicyResource` | API-level policy |
|
||||
| `ApiManagementUserResource` | Represents a user |
|
||||
| `ApiManagementGroupResource` | Represents a group |
|
||||
| `ApiManagementBackendResource` | Represents a backend service |
|
||||
| `ApiManagementGatewayResource` | Represents a self-hosted gateway |
|
||||
|
||||
## SKU Types
|
||||
|
||||
| SKU | Purpose | Capacity |
|
||||
|-----|---------|----------|
|
||||
| `Developer` | Development/testing (no SLA) | 1 |
|
||||
| `Basic` | Entry-level production | 1-2 |
|
||||
| `Standard` | Medium workloads | 1-4 |
|
||||
| `Premium` | High availability, multi-region | 1-12 per region |
|
||||
| `Consumption` | Serverless, pay-per-call | N/A |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use `WaitUntil.Completed`** for operations that must finish before proceeding
|
||||
2. **Use `WaitUntil.Started`** for long operations like service creation (30+ min)
|
||||
3. **Always use `DefaultAzureCredential`** — never hardcode keys
|
||||
4. **Handle `RequestFailedException`** for ARM API errors
|
||||
5. **Use `CreateOrUpdateAsync`** for idempotent operations
|
||||
6. **Navigate hierarchy** via `Get*` methods (e.g., `service.GetApis()`)
|
||||
7. **Policy format** — Use XML format for policies; JSON is also supported
|
||||
8. **Service creation** — Developer SKU is fastest for testing (~15-30 min)
|
||||
|
||||
## Error Handling
|
||||
|
||||
```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}");
|
||||
}
|
||||
```
|
||||
|
||||
## Reference Files
|
||||
|
||||
| File | When to Read |
|
||||
|------|--------------|
|
||||
| [references/service-management.md](references/service-management.md) | Service CRUD, SKUs, networking, backup/restore |
|
||||
| [references/apis-operations.md](references/apis-operations.md) | APIs, operations, schemas, versioning |
|
||||
| [references/products-subscriptions.md](references/products-subscriptions.md) | Products, subscriptions, access control |
|
||||
| [references/policies.md](references/policies.md) | Policy XML patterns, scopes, common policies |
|
||||
|
||||
## Related Resources
|
||||
|
||||
| Resource | Purpose |
|
||||
|----------|---------|
|
||||
| [API Management Documentation](https://learn.microsoft.com/en-us/azure/api-management/) | Official Azure docs |
|
||||
| [Policy Reference](https://learn.microsoft.com/en-us/azure/api-management/api-management-policies) | Complete policy reference |
|
||||
| [SDK Reference](https://learn.microsoft.com/en-us/dotnet/api/azure.resourcemanager.apimanagement) | .NET API reference |
|
||||
Reference in New Issue
Block a user