Cognito调用ListUsersRequest时如何实现多值筛选IN查询

Cognito的ListUsers接口原生不支持SQL里的IN多值匹配语法，它的Filter参数仅支持SCIM语法的有限子集，直接传入IN语句会直接返回参数校验错误，要实现多值匹配需求可以根据查询规模选择对应方案。

直接用OR拼接多个等值判断条件即可，效果和IN完全一致，Cognito原生支持这种写法。

• 注意单个Filter拼接的条件数量不能超过50个，总字符串长度不要超过4KB，否则会触发接口报错。
• 匹配的字符串值必须用双引号包裹，不能使用SQL里的单引号。
• 标准属性（比如email、phone_number）直接写属性名即可，自定义属性需要加custom:前缀。

对应你要查询两个邮箱的需求，Filter写法示例：

email = "email1@example.com" OR email = "email2@example.com"

Java SDK调用示例：

import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUsersRequest;
import software.amazon.awssdk.services.cognitoidentityprovider.model.ListUsersResponse;
import java.util.List;
import java.util.stream.Collectors;

public class CognitoListUserDemo {
    public static void main(String[] args) {
        CognitoIdentityProviderClient cognitoClient = CognitoIdentityProviderClient.create();
        // 待匹配的邮箱列表
        List<String> emailList = List.of("email1@example.com", "email2@example.com");
        
        // 拼接OR查询条件
        String filterExp = emailList.stream()
                .map(email -> String.format("email = \"%s\"", email))
                .collect(Collectors.joining(" OR "));

        ListUsersRequest request = ListUsersRequest.builder()
                .userPoolId("替换为你的用户池ID")
                .filter(filterExp)
                .attributesToGet("email", "username", "user_status") // 指定返回属性，减少冗余传输
                .limit(60) // 单页最大返回60条
                .build();
        
        ListUsersResponse response = cognitoClient.listUsers(request);
        // 处理匹配到的用户结果
        response.users().forEach(user -> System.out.println(user.username()));
        
        // 结果量较大时需要循环判断响应中的nextToken，传入下一次请求的paginationToken参数完成分页拉取
    }
}

如果待匹配的值超过50个，OR拼接的方式会触发Cognito的接口限制，这时候如果你的Cognito用户池总用户量不大（10万以内），可以直接不传Filter参数，分页拉取全量用户列表，在本地代码中做集合匹配即可。

• 这种方式实现简单，不受Filter的条件数量限制，用户量不大的情况下性能完全可以接受。
• 必须完整处理分页逻辑，直到返回的nextToken为空才停止拉取，避免漏数。

如果用户池规模在几十万以上，全量拉取的延迟和API调用成本都很高，建议提前做用户数据冗余：

• 配置Cognito用户池的触发器（PostConfirmation、PreSignUp、用户属性更新触发器），把用户核心属性实时同步到自建存储（比如MySQL、DynamoDB、OpenSearch等）。
• 后续所有多条件筛选、模糊查询、多值匹配类的需求，直接查询自建存储即可，灵活性和性能都远高于直接调用Cognito的ListUsers接口，也不会受Cognito的API查询规则限制。

• 不要尝试在Filter里写email IN ('xx','xx')语法，Cognito不支持该语法，必报错。
• 字符串值必须用双引号包裹，用单引号会触发Filter语法错误。
• 查询自定义属性时不要漏写custom:前缀，比如自定义属性user_level的过滤条件要写为custom:user_level = "1"。
• ListUsers默认不会返回所有用户属性，必须通过attributesToGet参数明确指定需要的字段。

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