azure-mgmt-apimanagement-dotnet

# 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 | Service CRUD, SKUs, networking, backup/restore | | references/apis-operations.md | APIs, operations, schemas, versioning | | references/products-subscriptions.md | Products, subscriptions, access control | | 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 | ## When to Use This skill is applicable to execute the workflow or actions described in the overview. ## Diff History - **v00.33.0**: Ingested from antigravity-awesome-skills community repo --- ## Why This Skill Exists Implement — Azure Resource Manager SDK for API Management in .NET. <!-- SR_40: auto-generated from frontmatter `purpose`/`description` (OPP-Phase3). Expand with domain-specific rationale. --> ## What If Fails - condition: Código não disponível para análise <!-- SR_40: auto-generated from frontmatter `what_if_fails` (OPP-Phase3). -->