使用Bicep创建基于本地数据网关的SQL API连接报错求助

问题场景 #

尝试用Bicep自动化部署包含Logic App的Azure集成项目，需创建关联本地数据网关的SQL API连接，但API连接参数无官方文档支持，且无法从UI直接导出配置。参考ARM相关讨论编写Bicep代码后，部署时触发以下错误：

连接网关实例'/subscriptions/SUB_ID/providers/Microsoft.Web/locations/northeurope/connectionGatewayInstallations/SOME_GUID'无法被引用，因为它已关联到连接网关'/subscriptions/SUB_ID/resourceGroups/RG_NAME/providers/Microsoft.Web/connectionGateways/GATEWAY_NAME'。连接网关实例一次只能关联一个连接网关。（错误代码：ConnectionGatewayInstallationUnavailable）

编写的Bicep代码如下：

resource apiConnection 'Microsoft.Web/connections@2018-07-01-preview' = {
  name: apiConnectionName
  location: 'westeurope'
  kind: 'v2'
  properties: {
     alternativeParameterValues: {}
     api: {
       id: subscriptionResourceId('Microsoft.Web/locations/managedApis', location, 'sql')
       type: 'Microsoft.Web/locations/managedApis'
     }
     displayName: apiConnectionName
     parameterValues: {
        Server: 'sqlservername'
        Database: 'dbname'
        AuthType: 'WindowsAuthentication'
        username: 'user-id'    
        password: 'user password'
        gateway: {
           id: '/subscriptions/<subid>/resourceGroups/<rg-name>/providers/Microsoft.Web/connectionGateways/<gateway-name>'
        }  
     }     
     customParameterValues: {}
 }}

解决方案 #

错误核心是直接引用网关资源ID的方式不正确，正确做法是引用网关的连接网关实例ID，而非网关资源本身。通过existing关键字关联已存在的网关资源，再读取其内置的实例ID参数即可解决问题。

修改后的Bicep代码示例：

// 引用已部署的本地数据网关资源
existing resource onPremGateway 'Microsoft.Web/connectionGateways@2016-06-01' = {
  name: gatewayName
  scope: resourceGroup(gatewayResourceGroupName)
}

resource apiConnection 'Microsoft.Web/connections@2018-07-01-preview' = {
  name: apiConnectionName
  location: location
  kind: 'v2'
  properties: {
    api: {
      id: subscriptionResourceId('Microsoft.Web/locations/managedApis', location, 'sql')
    }
    displayName: apiConnectionName
    parameterValues: {
      Server: sqlServerName
      Database: sqlDatabaseName
      AuthType: 'WindowsAuthentication'
      username: sqlUsername
      password: sqlPassword
      // 引用网关的安装实例ID，而非网关资源ID
      gateway: {
        id: onPremGateway.properties.gatewayInstallationId
      }
    }
    alternativeParameterValues: {}
    customParameterValues: {}
  }
}

关键注意事项 #

• 确保API连接的location与本地网关的部署区域一致，避免跨区域引用错误
• 敏感信息（如数据库密码）建议通过Azure Key Vault引用，不要明文写入代码
• 使用existing关键字关联已有资源，避免硬编码ID，提升代码可维护性

参数获取技巧 #

目前官方针对Bicep的相关文档较少，可通过以下方式获取正确参数：

• 用Azure CLI调用API导出已存在的API连接配置：

  az rest --method get --uri "/subscriptions/{subId}/resourceGroups/{rgName}/providers/Microsoft.Web/connections/{connectionName}?api-version=2018-07-01-preview"
  

• 尝试通过Azure Portal的「导出模板」功能查看ARM模板参数（部分API连接可能无法直接导出，但可参考生成的配置结构）

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