如何通过Bicep为API添加修订版本？报错解决及示例

错误原因解析 #

你遇到的两个错误核心原因如下：

• Can't change property Name for non-current revision：非当前修订版的API无法修改基础标识属性（包括API的基础名称、path路径），这些属性属于API的核心标识，只能在初始版本或设为当前版本的修订中调整。
• API with specified name ... already exists：你指定的name格式有误，或者基础API名称已存在但未正确关联现有资源，导致系统识别为重复创建。

可行实现示例 #

场景1：在同一模板中创建初始版本+新修订版 #

先创建API的初始版本（默认rev=1），再基于该版本创建rev=2的修订：

// 定义APIM实例（若已有现有实例，可改用existing关键字引用）
resource apimInstance 'Microsoft.ApiManagement/service@2022-08-01' = {
  name: 'your-apim-service-name'
  location: 'eastus'
  properties: {
    publisherName: '你的发布商名称'
    publisherEmail: 'your-email@example.com'
    sku: {
      name: 'Developer'
      capacity: 1
    }
  }
}

// API初始版本（rev=1）
resource apiV1 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
  parent: apimInstance
  name: 'somename' // 基础名称，默认生成rev=1
  properties: {
    apiType: 'http'
    description: '初始版本'
    apiRevision: '1'
    displayName: 'Some name'
    format: 'openapi+json'
    path: 'somepath'
    protocols: ['https']
    subscriptionRequired: false
    value: loadTextContent('somefile.json')
  }
}

// 创建rev=2的修订版
resource apiV2 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
  parent: apimInstance
  name: '${apiV1.name};rev=2' // 复用基础名称，格式为「基础名;rev=修订号」
  properties: {
    apiType: 'http'
    description: '修订版本：更新了API定义'
    apiRevision: '2'
    apiRevisionDescription: 'Changed by bicep'
    displayName: 'Some name（修订版）' // displayName可修改
    format: 'openapi+json'
    path: apiV1.properties.path // 必须与初始版本path一致，不可修改
    protocols: ['https']
    subscriptionRequired: false
    value: loadTextContent('updated-somefile.json') // 可加载更新后的OpenAPI文件
    isCurrent: true // 可选：将此修订设为当前生效版本
  }
}

场景2：基于现有API创建新修订版 #

如果APIM实例和初始API已存在，直接引用现有资源创建修订：

// 引用现有APIM实例
resource apimInstance 'Microsoft.ApiManagement/service@2022-08-01' = {
  name: 'your-apim-service-name'
  location: 'eastus'
  existing: true
}

// 创建rev=2的修订版，基于现有「somename」API
resource apiV2 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
  parent: apimInstance
  name: 'somename;rev=2'
  properties: {
    apiType: 'http'
    description: 'Changed by bicep'
    apiRevision: '2'
    apiRevisionDescription: 'Updated via Bicep'
    displayName: 'Some name'
    format: 'openapi+json'
    path: 'somepath' // 必须与现有API的path完全一致
    protocols: ['https']
    subscriptionRequired: false
    value: loadTextContent('updated-somefile.json')
    isCurrent: true
  }
}

关键注意事项 #

• 修订版的name必须遵循{基础API名称};rev={修订号}格式，基础名称需与原API完全匹配。
• path属性属于API核心标识，非当前修订版无法修改，必须与原版本保持一致。
• apiRevision属性值必须与name中的修订号一致，否则会触发验证错误。
• 若需让新修订生效，设置isCurrent: true，否则原版本仍为当前生效版本。

内容的提问来源于stack exchange，提问作者Jeroen Heier