AgentSkillsCN

apim-bicep

Azure API Management(APIM)及相关 Azure 服务的 Bicep 文件构建指南。适用于当用户希望创建、修改或理解 APIM 实例、API、后端、订阅、策略、产品、日志记录器、诊断功能,以及 MCP 服务器的 Bicep 模板时使用。本技能提供 Bicep 语法、来自 Azure Verified Modules 的常见模式,以及本仓库中的示例。

SKILL.md
--- frontmatter
name: apim-bicep
description: Guide for building Bicep files for Azure API Management (APIM) and related Azure services. Use when users want to create, modify, or understand Bicep templates for APIM instances, APIs, backends, subscriptions, policies, products, loggers, diagnostics, and MCP servers. This skill provides Bicep syntax, patterns from Azure Verified Modules, and examples from this repository.

APIM Bicep

This skill provides guidance for creating Azure Bicep templates for API Management and related services.

Quick Start - Basic APIM Instance

bicep
@description('The name of the API Management service instance')
param apiManagementServiceName string = 'apim-${uniqueString(resourceGroup().id)}'

@description('The email address of the publisher')
param publisherEmail string

@description('The name of the publisher')
param publisherName string

@description('The pricing tier of this API Management service')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium'])
param sku string = 'Basicv2'

@description('Location for all resources')
param location string = resourceGroup().location

resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' = {
  name: apiManagementServiceName
  location: location
  sku: {
    name: sku
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: publisherEmail
    publisherName: publisherName
  }
}

output apimId string = apimService.id
output apimName string = apimService.name
output gatewayUrl string = apimService.properties.gatewayUrl
output principalId string = apimService.identity.principalId

Resource Types Reference

Resource TypeAPI VersionPurpose
Microsoft.ApiManagement/service2024-06-01-previewAPIM service instance
Microsoft.ApiManagement/service/apis2024-06-01-previewAPI definitions
Microsoft.ApiManagement/service/apis/operations2024-06-01-previewAPI operations
Microsoft.ApiManagement/service/apis/policies2024-06-01-previewAPI-level policies
Microsoft.ApiManagement/service/backends2024-06-01-previewBackend services
Microsoft.ApiManagement/service/subscriptions2024-06-01-previewAPI subscriptions
Microsoft.ApiManagement/service/products2024-06-01-previewAPI products
Microsoft.ApiManagement/service/loggers2024-06-01-previewLogging configuration
Microsoft.ApiManagement/service/apis/diagnostics2024-06-01-previewAPI diagnostics

Essential Patterns

Backend with Managed Identity

bicep
resource backend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'my-backend'
  parent: apimService
  properties: {
    description: 'Backend with managed identity auth'
    url: 'https://my-service.azure.com'
    protocol: 'http'
    credentials: {
      managedIdentity: {
        resource: 'https://cognitiveservices.azure.com'
      }
    }
  }
}

Backend Pool (Load Balancing)

bicep
resource backendPool 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'inference-backend-pool'
  parent: apimService
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [for (config, i) in backendsConfig: {
        id: '/backends/${backends[i].name}'
        priority: config.?priority ?? 1
        weight: config.?weight ?? 1
      }]
    }
  }
}

API with OpenAPI Spec

bicep
resource api 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  name: 'my-api'
  parent: apimService
  properties: {
    displayName: 'My API'
    description: 'API description'
    path: 'api/v1'
    protocols: ['https']
    subscriptionRequired: true
    subscriptionKeyParameterNames: {
      header: 'api-key'
      query: 'api-key'
    }
    format: 'openapi+json'
    value: string(loadJsonContent('./openapi.json'))
  }
}

API Policy from File

bicep
resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2024-06-01-preview' = {
  name: 'policy'
  parent: api
  properties: {
    format: 'rawxml'
    value: loadTextContent('policy.xml')
  }
}

Subscription

bicep
@batchSize(1)
resource subscription 'Microsoft.ApiManagement/service/subscriptions@2024-06-01-preview' = [for sub in subscriptionsConfig: {
  name: sub.name
  parent: apimService
  properties: {
    displayName: sub.displayName
    scope: '/apis'  // or '/apis/{apiId}' or '/products/{productId}'
    state: 'active'
    allowTracing: true
  }
}]

MCP Server Patterns

Native MCP API (type: 'mcp')

Create an MCP server API that wraps existing API operations:

bicep
resource mcp 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp'
  properties: {
    type: 'mcp'
    displayName: 'Weather MCP'
    description: 'MCP for weather data'
    subscriptionRequired: false
    path: 'weather-mcp'
    protocols: ['https']
    mcpTools: [
      {
        name: operation.name
        operationId: operation.id
        description: operation.properties.description
      }
    ]
  }
}

Streamable MCP with Backend

Create an MCP server with a backend service:

bicep
resource mcpBackend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp-backend'
  properties: {
    protocol: 'http'
    url: '${mcpServiceUrl}/mcp'
    tls: {
      validateCertificateChain: true
      validateCertificateName: true
    }
    type: 'Single'
  }
}

resource mcp 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp'
  properties: {
    type: 'mcp'
    displayName: 'Weather MCP'
    subscriptionRequired: false
    backendId: mcpBackend.name
    path: 'weather'
    protocols: ['https']
    mcpProperties: {
      transportType: 'streamable'
    }
  }
}

MCP with Custom Operations

bicep
resource mcpApi 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apimService
  name: 'agent-mcp'
  properties: {
    displayName: 'Agent MCP Server'
    description: 'Model Context Protocol API endpoints'
    subscriptionRequired: false
    path: 'agent'
    protocols: ['https']
    serviceUrl: containerAppUrl
  }
}

resource mcpSseOp 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = {
  parent: mcpApi
  name: 'mcp-sse'
  properties: {
    displayName: 'MCP SSE Endpoint'
    method: 'GET'
    urlTemplate: '/sse'
    description: 'Server-Sent Events endpoint'
  }
}

resource mcpMessageOp 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = {
  parent: mcpApi
  name: 'mcp-message'
  properties: {
    displayName: 'MCP Message Endpoint'
    method: 'POST'
    urlTemplate: '/message'
    description: 'Message endpoint for MCP Server'
  }
}

Diagnostics and Logging

Azure Monitor Logger

bicep
resource apimLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  parent: apimService
  name: 'azuremonitor'
  properties: {
    loggerType: 'azureMonitor'
    isBuffered: false
  }
}

Application Insights Logger

bicep
resource appInsightsLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  name: 'appinsights-logger'
  parent: apimService
  properties: {
    loggerType: 'applicationInsights'
    credentials: {
      instrumentationKey: appInsightsInstrumentationKey
    }
    description: 'APIM Logger for Application Insights'
    isBuffered: false
    resourceId: appInsightsId
  }
}

API Diagnostics with LLM Logging

bicep
resource apiDiagnostics 'Microsoft.ApiManagement/service/apis/diagnostics@2024-06-01-preview' = {
  parent: api
  name: 'azuremonitor'
  properties: {
    alwaysLog: 'allErrors'
    verbosity: 'verbose'
    logClientIp: true
    loggerId: apimLogger.id
    sampling: {
      samplingType: 'fixed'
      percentage: 100
    }
    largeLanguageModel: {
      logs: 'enabled'
      requests: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
      responses: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
    }
  }
}

Bicep Best Practices

Use Existing Resources

bicep
resource apim 'Microsoft.ApiManagement/service@2024-06-01-preview' existing = {
  name: apimServiceName
}

Parameter Validation

bicep
@description('The pricing tier')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium'])
param sku string = 'Basicv2'

@minLength(1)
@maxLength(50)
param apiManagementName string

Load External Content

bicep
// Load JSON for OpenAPI specs
value: string(loadJsonContent('./specs/openapi.json'))

// Load XML for policies
value: loadTextContent('policy.xml')

// Load and parameterize policy
var updatedPolicy = replace(loadTextContent('policy.xml'), '{backend-id}', backendName)

Output Secrets Safely

bicep
#disable-next-line outputs-should-not-contain-secrets
output subscriptionKey string = subscription.listSecrets().primaryKey

Reference Documentation

For detailed patterns and examples, see:

Official Documentation