Azure DevOps流水线中为Azure APIM的API分配标签失败求助

问题描述 #

通过Azure DevOps CI/CD流水线将API接入Azure APIM时，API部署成功但标签未被正确分配。尝试过--tags "myproject" "myapp"和--tags "myproject=true" "myapp=true"两种写法，均未生效。

所用AzureCLI@2任务代码 #

- task: AzureCLI@2
  displayName: Deploy API Specification (Create or Update) and Configure Diagnostics
  inputs:
    azureSubscription: $(AzureServiceConnection)
    scriptType: bash
    scriptLocation: inlineScript
    inlineScript: |
      echo "Checking if API $(ApiName) exists in APIM..."
      API_EXISTS=$(az apim api show \
        --resource-group "$(ResourceGroup)" \
        --service-name "$(InstanceName)" \
        --api-id "$(ApiName)" 2>/dev/null || echo "not found")

      FILE_PATH="$(System.DefaultWorkingDirectory)/myapp/myapp-api.spec.json"
      TEMP_FILE_PATH="$(System.DefaultWorkingDirectory)/myapp/myapp-api-temp.spec.json"

      if [[ ! -f "$FILE_PATH" ]]; then
        echo "Error: API specification file not found at $FILE_PATH"
        exit 1
      fi

      echo "Replacing server URL with pipeline variable..."
      sed "s|{{myapp_API_URL}}|$(myappApiUrl)|g" "$FILE_PATH" > "$TEMP_FILE_PATH"

      if [[ "$API_EXISTS" == "not found" ]]; then
        echo "API not found. Importing as a new API..."
        result=$(az apim api import \
          --resource-group "$(ResourceGroup)" \
          --service-name "$(InstanceName)" \
          --path "$(ApiSuffix)" \
          --api-id "$(ApiName)" \
          --specification-format OpenApi \
          --specification-path "$TEMP_FILE_PATH" \
          --subscription-key-header-name "Ocp-Apim-myapp-Subscription-Key" \
          --subscription-key-query-param-name "myapp-subscription-key" 2>&1)

        if [[ $? -ne 0 ]]; then
          echo "Error importing API:"
          echo "$result"
          exit 1
        fi
        echo "API imported successfully."
      else
        echo "API exists. Updating API specification..."
        result=$(az apim api update \
          --resource-group "$(ResourceGroup)" \
          --service-name "$(InstanceName)" \
          --api-id "$(ApiName)" \
          --set subscriptionKeyParameterNames.header="Ocp-Apim-myapp-Subscription-Key" \
          --set subscriptionKeyParameterNames.query="myapp-subscription-key" \
          --set apiRevision="2" \
          --set description="Updated API specification" \
          --set format="OpenApi" \
          --set value="$TEMP_FILE_PATH" 2>&1)

        if [[ $? -ne 0 ]]; then
          echo "Error updating API:"
          echo "$result"
          exit 1
        fi
        echo "API updated successfully."
      fi

      # Add tags to API (works for both new and existing APIs)
      az apim api update \
        --resource-group "$(ResourceGroup)" \
        --service-name "$(InstanceName)" \
        --api-id "$(ApiName)" \
        --tags "myproject" "myapp"  # Explicit values

      # Verify tags
      echo "Current API Tags:"
      az apim api show \
        --resource-group "$(ResourceGroup)" \
        --service-name "$(InstanceName)" \
        --api-id "$(ApiName)" \
        --query "{Tags:tags}" -o json

      # Cleanup
      rm -f "$TEMP_FILE_PATH"

解决方案 #

1. 修正az apim api update的标签参数格式 #

az apim api update命令中，直接使用--tags参数在更新场景下不会生效，需通过--set指定标签数组：

az apim api update \
  --resource-group "$(ResourceGroup)" \
  --service-name "$(InstanceName)" \
  --api-id "$(ApiName)" \
  --set tags='["myproject", "myapp"]'

若需保留原有标签并追加新标签，可先获取现有标签再合并更新（需提前安装jq工具）：

# 获取现有标签
EXISTING_TAGS=$(az apim api show --resource-group "$(ResourceGroup)" --service-name "$(InstanceName)" --api-id "$(ApiName)" --query tags -o json)
# 合并新标签并去重
UPDATED_TAGS=$(echo "$EXISTING_TAGS" | jq -c '. + ["myproject", "myapp"] | unique')
# 更新标签
az apim api update \
  --resource-group "$(ResourceGroup)" \
  --service-name "$(InstanceName)" \
  --api-id "$(ApiName)" \
  --set tags="$UPDATED_TAGS"

2. 使用通用资源标签命令替代 #

改用az resource tag命令，支持直接覆盖或合并标签，兼容性更强：

# 覆盖现有标签，仅保留指定标签
az resource tag \
  --resource-group "$(ResourceGroup)" \
  --name "$(ApiName)" \
  --resource-type "Microsoft.ApiManagement/service/apis" \
  --tags "myproject" "myapp"

# 合并标签，保留原有标签并添加新标签
az resource tag \
  --resource-group "$(ResourceGroup)" \
  --name "$(ApiName)" \
  --resource-type "Microsoft.ApiManagement/service/apis" \
  --tags "myproject" "myapp" \
  --operation merge

3. 检查服务连接权限 #

确保Azure DevOps使用的服务连接（$(AzureServiceConnection)）拥有ApiManagement Service Contributor或更高权限，缺少标签写入权限会导致更新操作静默失败。

4. 增加命令错误检查 #

在标签更新命令后添加错误捕获，确保命令执行成功：

echo "Adding tags to API..."
tag_result=$(az apim api update \
  --resource-group "$(ResourceGroup)" \
  --service-name "$(InstanceName)" \
  --api-id "$(ApiName)" \
  --set tags='["myproject", "myapp"]' 2>&1)
if [[ $? -ne 0 ]]; then
  echo "Error adding tags:"
  echo "$tag_result"
  exit 1
fi

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