如何通过Azure DevOps API为测试点分配测试人员？（参数报错）

问题背景 #

根据微软官方文档《Points - Update》（API版本7.1），可通过PATCH请求更新测试点分配测试人员，请求地址：

PATCH https://dev.azure.com/{organization}/{project}/_apis/test/Plans/{planId}/Suites/{suiteId}/points/{pointIds}?api-version=7.1

官方示例请求体：

{
  "tester": {
    "displayName": "Jamal Hartnett"
  }
}

但使用uniqueName参数时触发错误：

{
    "$id": "1",
    "innerException": null,
    "message": "Tester",
    "typeName": "System.ArgumentException, mscorlib",
    "typeKey": "ArgumentException",
    "errorCode": 0,
    "eventId": 0
}

核心疑问：

• 文档指出uniqueName已弃用，建议使用Domain+PrincipalName，不清楚是作为uniqueName的值还是新增参数？
• PrincipalName是什么？格式要求是什么？
• 如何正确通过API为测试点分配测试人员？

已确认：授权、请求头、参数配置均正常，其他测试计划相关API（提取套件、用例、创建测试点）均可正常调用，仅分配测试人员步骤失败。使用Java RestAssured框架，通过POJO构建JSON请求体。

现有请求信息：

• Base URI: https://dev.azure.com
• Base PATH: /organizationName/projectName/_apis/test/Plans/111111/Suites/222222/points/333333
• 请求体：

{"tester":{"uniqueName":"email.thatisunique@companydomain.com"}}

• 请求头：

Connection=keep-alive
Accept-Encoding=gzip,deflate
Accept=text/xml;charset=UTF-8
Accept=application/json
X-XSS-Protection=1; mode=block

• 参数：{api-version=7.1}
• 请求代码：

protected Response sendPatchRequest(Object serializedPojo, int expectedStatusCode) {
    // setup
    RestAssured.baseURI = baseURI;
    RestAssured.basePath = basePath;

    // logs
    String payloadAsString = objectMapper.writeValueAsString(serializedPojo);
    LogsHelper.log("PATCH Request payload: " + System.lineSeparator() + payloadAsString + "--------------------------------------");
    LogsHelper.log("PATCH Request Base URI: " + baseURI);
    LogsHelper.log("PATCH Request Base PATH: " + basePath);
    LogsHelper.log("PATCH Request Headers list: " + getHeaders().toString());

    // request
    ExtractableResponse<Response> extract = RestAssured
            .given()
            .queryParams(params)
            .relaxedHTTPSValidation()
            .headers(headers)
            .body(serializedPojo)
            .contentType("application/json")
            .when()
            .patch()
            .then()
            .extract();
    try {
        assertEquals("Status code not equal " + expectedStatusCode, expectedStatusCode, extract.response().getStatusCode());
    } catch (AssertionError e) {
        LogsHelper.log("PATCH Request response: " + System.lineSeparator() + extract.response().prettyPrint());
    }
    return extract.response();
}

解决方法 #

1. Domain+PrincipalName的正确用法 #

文档中提到的Domain+PrincipalName是作为uniqueName的替代值，而非新增参数。即依然使用tester对象下的uniqueName键，但值必须替换为Domain\PrincipalName格式，不能再用邮箱。

2. PrincipalName的定义与格式 #

• PrincipalName指Azure DevOps用户的SAM账户名（企业AD域中的用户名）。
• 格式要求：域名\用户名，例如CONTOSO\jamal.hartnett

3. 更可靠的替代方案：使用用户ID #

如果无法获取Domain+PrincipalName，直接使用用户的Azure DevOps GUID是最稳定的方式，请求体格式：

{
  "tester": {
    "id": "用户的Azure DevOps GUID"
  }
}

用户ID可通过Azure DevOps的用户管理接口获取，或从网页端用户详情页提取。

4. 修复后的请求体示例 #

方式一：使用Domain+PrincipalName

{
  "tester": {
    "uniqueName": "CONTOSO\\jamal.hartnett"
  }
}

方式二：使用用户ID

{
  "tester": {
    "id": "12345678-1234-1234-1234-1234567890ab"
  }
}

5. 注意事项 #

• 确保uniqueName或id对应的用户是当前Azure DevOps组织的有效成员，且具备测试点访问权限。
• 请求头Content-Type必须为application/json（你的代码已配置，无需修改）。
• 新版本API不再支持邮箱作为uniqueName的值，必须使用Domain+PrincipalName或用户ID。

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