含变音符号的Google Sheets工作表调用API报错解决方案咨询

问题重现 #

请求含变音符号的法语工作表名称Opérations 2023时，API返回400错误：

{"code": 400,"errors": [{"domain": "global","message": "Unable to parse range: Op%C3%A9rations%202023!A2%3AE2","reason": "badRequest"}],"message": "Unable to parse range: Op%C3%A9rations%202023!A2%3AE2","status": "INVALID_ARGUMENT"}

原请求代码片段：

public static void main(String... args) throws IOException, GeneralSecurityException {
    // Build a new authorized API client service.
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    final String spreadsheetId = "ID";
    final String range = "Opérations 2023!A2:E2";
    Sheets service =
        new Sheets.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
            .setApplicationName(APPLICATION_NAME)
            .build();
    ValueRange response = service.spreadsheets().values()
        .get(spreadsheetId, range)
        .execute();
    // 后续处理逻辑...
}

解决方案 #

方法1：用单引号包裹工作表名称 #

Google Sheets API要求包含特殊字符、空格或非ASCII字符的工作表名称必须用单引号括起来，这样API能正确识别名称边界。修改range变量：

final String range = "'Opérations 2023'!A2:E2";

这是最简单直接的修复方式，适用于大多数场景。

方法2：使用工作表ID替代名称 #

如果单引号方法仍有问题，可通过工作表ID（数字标识）来构建范围，完全规避字符编码问题：

public static void main(String... args) throws IOException, GeneralSecurityException {
    final NetHttpTransport HTTP_TRANSPORT = GoogleNetHttpTransport.newTrustedTransport();
    final String spreadsheetId = "ID";
    Sheets service =
        new Sheets.Builder(HTTP_TRANSPORT, JSON_FACTORY, getCredentials(HTTP_TRANSPORT))
            .setApplicationName(APPLICATION_NAME)
            .build();

    // 获取所有工作表信息，找到目标工作表ID
    Spreadsheet spreadsheet = service.spreadsheets().get(spreadsheetId).execute();
    String range = null;
    for (Sheet sheet : spreadsheet.getSheets()) {
        SheetProperties props = sheet.getProperties();
        if ("Opérations 2023".equals(props.getTitle())) {
            // 用工作表ID构建范围，格式为 gid=ID!单元格范围
            range = String.format("gid=%d!A2:E2", props.getSheetId());
            break;
        }
    }

    if (range != null) {
        ValueRange response = service.spreadsheets().values()
            .get(spreadsheetId, range)
            .execute();
        List<List<Object>> values = response.getValues();
        // 后续处理逻辑...
    }
}

原理说明 #

当工作表名称包含非ASCII字符（如é）或空格时，直接传入字符串会被自动URL编码为Op%C3%A9rations%202023，但Google Sheets API无法正确解析这种编码后的名称与单元格范围的组合。用单引号包裹名称能让API明确区分工作表名称和范围部分；使用工作表ID则完全绕开了字符编码的问题，因为ID是数字，不存在解析歧义。

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