创建APIM实例时配置托管证书自定义域名报错求助

问题场景 #

使用Bicep同时创建APIM实例并配置带有托管证书的自定义域名时，部署执行报错；但先完成APIM实例创建，再单独运行自定义域名配置代码则可成功。

报错信息 #

HostnameConfiguration configured with New Managed Certificate Request is not supported while activating APIM service [name].

原Bicep代码 #

resource apiManagement 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  ...
  properties: {
    publisherEmail: '...'
    publisherName: '...'
    hostnameConfigurations: [
      {
        type: 'Proxy'
        hostName: 'api.my-domain.com'
        negotiateClientCertificate: false
        defaultSslBinding: true
        certificateSource: 'Managed'
      }
    ]
  }
}

原因分析 #

APIM服务首次激活（创建）流程中，不支持同时发起新的托管证书请求。托管证书的生成与绑定依赖已完全激活的APIM实例，因此必须分阶段操作。

解决方案 #

将APIM实例创建与自定义域名（托管证书）配置拆分为两个独立部署步骤：

步骤1：创建基础APIM实例 #

resource apiManagement 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: 'your-apim-name'
  location: 'your-region'
  sku: {
    name: 'Developer' // 按需选择对应SKU
    capacity: 1
  }
  properties: {
    publisherEmail: 'your-publisher-email@example.com'
    publisherName: 'your-publisher-name'
    // 暂不配置hostnameConfigurations
  }
}

步骤2：配置自定义域名及托管证书 #

等待APIM实例完全激活（通常需5-10分钟）后，运行以下代码：

resource apiManagement 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: 'your-apim-name'
  location: 'your-region'
  sku: {
    name: 'Developer'
    capacity: 1
  }
  properties: {
    publisherEmail: 'your-publisher-email@example.com'
    publisherName: 'your-publisher-name'
    hostnameConfigurations: [
      {
        type: 'Proxy'
        hostName: 'api.my-domain.com'
        negotiateClientCertificate: false
        defaultSslBinding: true
        certificateSource: 'Managed'
      }
    ]
  }
}

也可在同一Bicep文件中通过依赖声明强制顺序执行（部分场景仍需等待实例激活完成后再部署）：

// 先创建基础APIM实例
resource apiManagementBase 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: 'your-apim-name'
  location: 'your-region'
  sku: {
    name: 'Developer'
    capacity: 1
  }
  properties: {
    publisherEmail: 'your-publisher-email@example.com'
    publisherName: 'your-publisher-name'
  }
}

// 依赖基础实例完成后，更新配置自定义域名
resource apiManagementWithCustomDomain 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: apiManagementBase.name
  location: apiManagementBase.location
  sku: apiManagementBase.sku
  properties: {
    publisherEmail: apiManagementBase.properties.publisherEmail
    publisherName: apiManagementBase.properties.publisherName
    hostnameConfigurations: [
      {
        type: 'Proxy'
        hostName: 'api.my-domain.com'
        negotiateClientCertificate: false
        defaultSslBinding: true
        certificateSource: 'Managed'
      }
    ]
  }
  dependsOn: [apiManagementBase]
}

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