通过POST请求与HttpsURLConnection为Firestore文档添加字段

我之前也踩过Firestore REST API部分更新的坑，折腾了好一阵才弄明白怎么正确添加单个字段。结合你给出的PATCH函数框架，我来帮你把细节补全，应该就能解决问题了：

首先得搞清楚Firestore REST API的PATCH规则——它支持两种方式做部分更新：一种是JSON Patch格式，另一种是用updateMask参数指定要更新的字段，后者对单个字段更新来说更简单直接，我推荐用这个方式。

1. 构造符合要求的请求体 #

要添加单个字段，请求体必须严格遵循Firestore的字段格式：每个字段都要指定对应的类型（比如字符串用stringValue、数字用integerValue）。比如你要给文档加一个userNickname字段，值为"JRRoy"，请求体应该是这样的：

{
  "fields": {
    "userNickname": {
      "stringValue": "JRRoy"
    }
  }
}

2. 完善你的PATCH函数 #

结合你已有的代码，需要补充请求头、updateMask参数和响应处理的细节，完整代码如下：

private void PATCHRequest(String document_path, String theData) throws IOException, JSONException {
    // 构建URL时添加updateMask参数，指定要更新的字段
    String FirestoreURL = REST_HEADER + "projects/" + PROJECT_ID + "/databases/(default)/documents/" + document_path + "?updateMask=fields.userNickname";
    URL cloudFirestoreEndPoint = new URL(FirestoreURL);

    // 打开连接并配置请求属性
    HttpURLConnection connection = (HttpURLConnection) cloudFirestoreEndPoint.openConnection();
    connection.setRequestMethod("PATCH");
    connection.setRequestProperty("Content-Type", "application/json");
    // 替换成你的有效OAuth2访问令牌，权限需要包含datastore或cloud-platform
    connection.setRequestProperty("Authorization", "Bearer " + YOUR_ACCESS_TOKEN);
    connection.setDoOutput(true);

    // 写入请求体
    try (OutputStream os = connection.getOutputStream()) {
        byte[] input = theData.getBytes(StandardCharsets.UTF_8);
        os.write(input, 0, input.length);
    }

    // 处理响应结果
    int responseCode = connection.getResponseCode();
    if (responseCode == HttpURLConnection.HTTP_OK) {
        try (BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
            String inputLine;
            StringBuilder response = new StringBuilder();
            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            System.out.println("字段添加成功：" + response.toString());
        }
    } else {
        System.err.println("更新失败，响应码：" + responseCode);
        // 读取错误详情便于排查
        try (BufferedReader errIn = new BufferedReader(new InputStreamReader(connection.getErrorStream()))) {
            String errLine;
            StringBuilder errResponse = new StringBuilder();
            while ((errLine = errIn.readLine()) != null) {
                errResponse.append(errLine);
            }
            System.err.println("错误详情：" + errResponse.toString());
        }
    }
}

3. 关键注意事项（帮你避坑） #

• updateMask参数不能少：这是很多人在API Explorer里失败的原因，必须明确指定要更新的字段路径，格式是fields.字段名，嵌套字段比如profile.age就写成fields.profile.age。
• 访问令牌要有效：你需要获取带有https://www.googleapis.com/auth/datastore或https://www.googleapis.com/auth/cloud-platform权限的OAuth2令牌，否则会返回权限错误。
• API Explorer测试技巧：在测试时，记得在「请求参数」里填updateMask=fields.你的字段名，同时请求体严格按照Firestore的字段格式填写，不能直接传原始值。

按照这个方式调整后，不管是代码里的请求还是API Explorer里的测试，都能成功给Firestore文档添加单个字段了。

内容的提问来源于stack exchange，提问作者Jean-Romain Roy