如何通过REST API向Azure DevOps管道传递并读取机密变量

完全可以直接通过Run Pipeline REST API向运行中的管道传递机密变量，不需要依赖变量组、Azure Key Vault集成这类方案。机密变量读取为空的问题，本质是Azure DevOps对机密变量的默认安全规则限制，不是API功能不支持。

正确的API传参格式 #

调用接口触发运行时，请求体中变量部分按以下结构传参即可，不需要额外做特殊配置：

{
  "resources": {
    "repositories": {
      "self": {
        "refName": "refs/heads/main"
      }
    }
  },
  "variables": {
    "yourSecretKey": {
      "isSecret": true,
      "value": "实际传入的机密内容"
    },
    "normalCommonVar": {
      "isSecret": false,
      "value": "普通非机密变量值"
    }
  }
}

机密变量读取为空的核心原因与修复方式 #

• 机密变量默认不自动注入全局环境变量
  所有标记为机密的Azure DevOps变量（包括UI手动设置、变量组引入、API运行时传入的所有渠道），都不会像普通非机密变量那样自动注入到所有任务的环境变量列表，这是平台默认的安全设计，避免机密值被未授权的任务意外泄露。
  要在任务中使用这类变量，必须在对应任务的env配置块中显式做变量映射，映射后才能在任务执行上下文里读到对应值，示例配置：

  - task: Bash@3
    inputs:
      targetType: 'inline'
      script: |
        # 未做env映射直接读变量会拿到空值
        # 不要直接echo机密值验证，平台会自动把日志里的机密内容替换为***
        # 可通过判断变量长度验证是否传入成功
        echo "机密变量长度为: ${#API_SECRET}"
    env:
      API_SECRET: $(yourSecretKey) # 显式映射API传入的机密变量
  

• YAML中同名变量定义覆盖了传入值
  如果在管道根节点的variables块、作业级变量配置里提前定义了同名变量，会覆盖API运行时传入的机密值。如果需要提前占位同名变量，必须在YAML定义时就将该变量标记为机密，且不要设置固定默认值，示例：

  variables:
    - name: yourSecretKey
      isSecret: true
      value: '' # 留空，等待运行时API传值覆盖
  

额外排查点 #

• 确认调用API时使用的API版本不低于6.0，低于6.0的旧版REST API对运行时机密变量的支持存在已知bug，会出现参数传递后丢失的问题
• 不要在模板解析、管道校验这类编译阶段步骤中尝试读取运行时传入的机密变量，这类变量仅在作业实际运行的执行阶段可用
• 如果管道使用了跨模板参数传递，不要把API传入的机密变量直接作为模板参数透传，编译阶段无法读取到运行时机密值，会直接渲染为空

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