使用Bicep+YAML部署APIM OpenAPI v3 JSON失败，手动导入正常

核心原因 #

部署报错syntax error near unexpected token '('是因为OpenAPI JSON内容中的特殊字符（如括号、单引号）在Bash命令行中未被正确转义，导致Bash将这些字符解析为命令语法而非字符串内容。手动导入正常是因为APIM门户直接读取文件，不存在命令行参数解析的问题；另一个API能成功部署是因为其JSON不含触发Bash语法错误的特殊字符。

解决方案 #

方案1：Base64编码传输（最可靠） #

通过Base64编码将JSON转换为无特殊字符的字符串，避免所有转义问题：

修正PowerShell任务（编码JSON）

- task: PowerShell@2
  name: getDefinitionContent
  displayName: 'Load and Encode File Content'
  inputs:
    targetType: 'inline'
    script: |
      # 修复路径中的多余双引号
      $content = Get-Content -Path "../sourceArtifact/resources/apimanagement/resources/apis/Internal API.openapi+json.json" -Raw
      # 将JSON转为Base64编码字符串
      $bytes = [System.Text.Encoding]::UTF8.GetBytes($content)
      $base64Content = [System.Convert]::ToBase64String($bytes)
      Write-Output "##vso[task.setvariable variable=fileContent;isoutput=true]$base64Content"

修正AzureCLI任务（解码并传递参数）

steps:
  - task: AzureCLI@2
    displayName: 'Add API : ${{ parameters.name }}'
    inputs:
      azureSubscription: ${{ parameters.azureServiceConnection }}
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        # 将Base64编码解码回JSON
        definitionContent=$(echo '${{ parameters.definitionContent }}' | base64 -d)
        
        az deployment group create \
          --resource-group '${{ parameters.resourceGroupName }}' \
          --name 'iac.${{ parameters.apiManagementServiceName }}' \
          --template-file '../sourceArtifact/resources/apimanagement/cli/apis/APIM.AddApiFromDefinition.bicep' \
          --parameters 'apimServiceName=${{ parameters.apiManagementServiceName }}' \
          --parameters 'name=${{ parameters.name }}' \
          --parameters 'definitionFormat=${{ parameters.definitionFormat }}' \
          --parameters "definitionContent='$definitionContent'" \
          --parameters 'apiPath=${{ parameters.apiPath }}'

方案2：转义JSON中的单引号 #

针对Bash的单引号语法，转义JSON内的单引号：

修正PowerShell任务

- task: PowerShell@2
  name: getDefinitionContent
  displayName: 'Load File Content'
  inputs:
    targetType: 'inline'
    script: |
      # 修复路径中的多余双引号
      $content = Get-Content -Path "../sourceArtifact/resources/apimanagement/resources/apis/Internal API.openapi+json.json" -Raw
      # 转义单引号以适配Bash单引号字符串
      $escapedContent = $content -replace "'", "'\''"
      Write-Output "##vso[task.setvariable variable=fileContent;isoutput=true]$escapedContent"

AzureCLI任务无需修改，保持原参数传递方式即可。

方案3：通过临时文件传递JSON #

将JSON写入临时文件，避免命令行参数解析问题：

修正AzureCLI任务

steps:
  - task: AzureCLI@2
    displayName: 'Add API : ${{ parameters.name }}'
    inputs:
      azureSubscription: ${{ parameters.azureServiceConnection }}
      scriptType: bash
      scriptLocation: inlineScript
      inlineScript: |
        # 将JSON内容写入临时文件
        echo '${{ parameters.definitionContent }}' > temp_openapi.json
        
        az deployment group create \
          --resource-group '${{ parameters.resourceGroupName }}' \
          --name 'iac.${{ parameters.apiManagementServiceName }}' \
          --template-file '../sourceArtifact/resources/apimanagement/cli/apis/APIM.AddApiFromDefinition.bicep' \
          --parameters 'apimServiceName=${{ parameters.apiManagementServiceName }}' \
          --parameters 'name=${{ parameters.name }}' \
          --parameters 'definitionFormat=${{ parameters.definitionFormat }}' \
          --parameters "definitionContent=`$(cat temp_openapi.json)" \
          --parameters 'apiPath=${{ parameters.apiPath }}'
        
        # 清理临时文件
        rm temp_openapi.json

额外注意事项 #

• 务必修复PowerShell任务中文件路径的多余双引号，避免读取文件失败。
• 若选择方案2或3，需确保JSON中的换行符不会影响Bash命令执行（Base64方案无此问题）。

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