@ngxtm/devkit 3.14.0 → 3.16.0

package/merged-commands/azure-mgmt-apimanagement-dotnet.md

@@ -0,0 +1,315 @@
+---
+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
+risk: unknown
+source: community
+---
+
+# 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.

package/merged-commands/azure-mgmt-apimanagement-py.md

@@ -0,0 +1,283 @@
+---
+name: azure-mgmt-apimanagement-py
+description: "|"
+  Azure API Management SDK for Python. Use for managing APIM services, APIs, products, subscriptions, and policies.
+  Triggers: "azure-mgmt-apimanagement", "ApiManagementClient", "APIM", "API gateway", "API Management".
+package: azure-mgmt-apimanagement
+risk: unknown
+source: community
+---
+
+# Azure API Management SDK for Python
+
+Manage Azure API Management services, APIs, products, and policies.
+
+## Installation
+
+```bash
+pip install azure-mgmt-apimanagement
+pip install azure-identity
+```
+
+## Environment Variables
+
+```bash
+AZURE_SUBSCRIPTION_ID=your-subscription-id
+```
+
+## Authentication
+
+```python
+from azure.identity import DefaultAzureCredential
+from azure.mgmt.apimanagement import ApiManagementClient
+import os
+
+client = ApiManagementClient(
+    credential=DefaultAzureCredential(),
+    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
+)
+```
+
+## Create APIM Service
+
+```python
+from azure.mgmt.apimanagement.models import (
+    ApiManagementServiceResource,
+    ApiManagementServiceSkuProperties,
+    SkuType
+)
+
+service = client.api_management_service.begin_create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    parameters=ApiManagementServiceResource(
+        location="eastus",
+        publisher_email="admin@example.com",
+        publisher_name="My Organization",
+        sku=ApiManagementServiceSkuProperties(
+            name=SkuType.DEVELOPER,
+            capacity=1
+        )
+    )
+).result()
+
+print(f"Created APIM: {service.name}")
+```
+
+## Import API from OpenAPI
+
+```python
+from azure.mgmt.apimanagement.models import (
+    ApiCreateOrUpdateParameter,
+    ContentFormat,
+    Protocol
+)
+
+api = client.api.begin_create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    api_id="my-api",
+    parameters=ApiCreateOrUpdateParameter(
+        display_name="My API",
+        path="myapi",
+        protocols=[Protocol.HTTPS],
+        format=ContentFormat.OPENAPI_JSON,
+        value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {"/health": {"get": {"responses": {"200": {"description": "OK"}}}}}}'
+    )
+).result()
+
+print(f"Imported API: {api.display_name}")
+```
+
+## Import API from URL
+
+```python
+api = client.api.begin_create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    api_id="petstore",
+    parameters=ApiCreateOrUpdateParameter(
+        display_name="Petstore API",
+        path="petstore",
+        protocols=[Protocol.HTTPS],
+        format=ContentFormat.OPENAPI_LINK,
+        value="https://petstore.swagger.io/v2/swagger.json"
+    )
+).result()
+```
+
+## List APIs
+
+```python
+apis = client.api.list_by_service(
+    resource_group_name="my-resource-group",
+    service_name="my-apim"
+)
+
+for api in apis:
+    print(f"{api.name}: {api.display_name} - {api.path}")
+```
+
+## Create Product
+
+```python
+from azure.mgmt.apimanagement.models import ProductContract
+
+product = client.product.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    product_id="premium",
+    parameters=ProductContract(
+        display_name="Premium",
+        description="Premium tier with unlimited access",
+        subscription_required=True,
+        approval_required=False,
+        state="published"
+    )
+)
+
+print(f"Created product: {product.display_name}")
+```
+
+## Add API to Product
+
+```python
+client.product_api.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    product_id="premium",
+    api_id="my-api"
+)
+```
+
+## Create Subscription
+
+```python
+from azure.mgmt.apimanagement.models import SubscriptionCreateParameters
+
+subscription = client.subscription.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    sid="my-subscription",
+    parameters=SubscriptionCreateParameters(
+        display_name="My Subscription",
+        scope=f"/products/premium",
+        state="active"
+    )
+)
+
+print(f"Subscription key: {subscription.primary_key}")
+```
+
+## Set API Policy
+
+```python
+from azure.mgmt.apimanagement.models import PolicyContract
+
+policy_xml = """
+<policies>
+    <inbound>
+        <rate-limit calls="100" renewal-period="60" />
+        <set-header name="X-Custom-Header" exists-action="override">
+            <value>CustomValue</value>
+        </set-header>
+    </inbound>
+    <backend>
+        <forward-request />
+    </backend>
+    <outbound />
+    <on-error />
+</policies>
+"""
+
+client.api_policy.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    api_id="my-api",
+    policy_id="policy",
+    parameters=PolicyContract(
+        value=policy_xml,
+        format="xml"
+    )
+)
+```
+
+## Create Named Value (Secret)
+
+```python
+from azure.mgmt.apimanagement.models import NamedValueCreateContract
+
+named_value = client.named_value.begin_create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    named_value_id="backend-api-key",
+    parameters=NamedValueCreateContract(
+        display_name="Backend API Key",
+        value="secret-key-value",
+        secret=True
+    )
+).result()
+```
+
+## Create Backend
+
+```python
+from azure.mgmt.apimanagement.models import BackendContract
+
+backend = client.backend.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    backend_id="my-backend",
+    parameters=BackendContract(
+        url="https://api.backend.example.com",
+        protocol="http",
+        description="My backend service"
+    )
+)
+```
+
+## Create User
+
+```python
+from azure.mgmt.apimanagement.models import UserCreateParameters
+
+user = client.user.create_or_update(
+    resource_group_name="my-resource-group",
+    service_name="my-apim",
+    user_id="newuser",
+    parameters=UserCreateParameters(
+        email="user@example.com",
+        first_name="John",
+        last_name="Doe"
+    )
+)
+```
+
+## Operation Groups
+
+| Group | Purpose |
+|-------|---------|
+| `api_management_service` | APIM instance management |
+| `api` | API operations |
+| `api_operation` | API operation details |
+| `api_policy` | API-level policies |
+| `product` | Product management |
+| `product_api` | Product-API associations |
+| `subscription` | Subscription management |
+| `user` | User management |
+| `named_value` | Named values/secrets |
+| `backend` | Backend services |
+| `certificate` | Certificates |
+| `gateway` | Self-hosted gateways |
+
+## Best Practices
+
+1. **Use named values** for secrets and configuration
+2. **Apply policies** at appropriate scopes (global, product, API, operation)
+3. **Use products** to bundle APIs and manage access
+4. **Enable Application Insights** for monitoring
+5. **Use backends** to abstract backend services
+6. **Version your APIs** using APIM's versioning features
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.