고급 사용자 검색
Management API를 직접 사용하여 고급 사용자 검색 조건을 활용하세요.
검색 요청 수행하기
사용자 검색을 위해 GET /api/users를 사용하세요. 이 API는 다른 Management API와 마찬가지로 인증이 필요합니다. 상호작용 방법은 Management API와 상호작용하기를 참고하세요.
예시
요청
curl \
--location \
--request GET \
'http://<your-logto-endpoint>/api/users?search=%25alice%25'
응답
User 엔티티의 배열입니다.
[
{
"id": "MgUzzDsyX0iB",
"username": "alice_123",
"primaryEmail": "alice@some.email.domain",
"primaryPhone": null,
"name": null,
"avatar": null
// ...
}
]
파라미터
검색 요청은 다음 파라미터 키로 구성됩니다:
- 검색 키워드:
search,search.* - 필드별 검색 모드:
mode,mode.*(기본값'like', 사용 가능 값['exact', 'like', 'similar_to', 'posix']) - 조인 모드:
joint또는jointMode(기본값'or', 사용 가능 값['or', 'and']) - 대소문자 구분 여부:
isCaseSensitive(기본값false)
이 API는 페이지네이션이 활성화되어 있습니다.
예시를 통해 하나씩 살펴보겠습니다. 모든 검색 파라미터는 URLSearchParams의 생성자 형식으로 작성됩니다.
검색 모드는 기본적으로 like로 설정되어 있으며, 근사 문자열 매칭 ("퍼지 검색")을 사용합니다.
모든 퍼지 검색 모드는 필드당 하나의 값만 매칭할 수 있습니다. 하나의 필드에 여러 값을 매칭하려면 "exact" 모드를 사용해야 합니다. 자세한 내용은 정확한 일치 및 대소문자 구분을 참고하세요.
기본 퍼지 검색
모든 사용 가능한 필드에 대해 퍼지 검색을 하고 싶다면, search 키에 값을 제공하면 됩니다. 내부적으로 the like 연산자를 사용합니다:
new URLSearchParams([['search', '%foo%']]);
이 검색은 사용자 검색에서 사용 가능한 모든 필드, 즉 id, primaryEmail, primaryPhone, username, name을 순회합니다.
필드 지정하기
name 필드에서만 검색을 제한하고 싶다면? 이름에 foo가 포함된 사용자를 찾으려면 . 기호로 필드를 지정하세요:
new URLSearchParams([['search.name', '%foo%']]);
중첩 필드는 지원되지 않으니 주의하세요. 예를 들어, search.name.first는 오류가 발생합니다.
여러 필드를 동시에 지정할 수도 있습니다:
new URLSearchParams([
['search.name', '%foo%'],
['search.primaryEmail', '%@gmail.com'],
]);
즉, 이름에 foo가 포함되어 있거나 OR 이메일이 @gmail.com으로 끝나는 사용자를 검색합니다.
조인 모드 변경하기
모든 조건을 만족하는 결과만 반환받고 싶다면, 조인 모드를 and로 설정하세요:
new URLSearchParams([
['search.name', '%foo%'],
['search.primaryEmail', '%@gmail.com'],
['joint', 'and'],
]);
즉, 이름에 foo가 포함되어 있고 AND 이메일이 @gmail.com으로 끝나는 사용자를 검색합니다.
정확한 일치 및 대소문자 구분
이름이 정확히 "Alice"인 사용자를 찾고 싶다면, mode.name을 exact로 설정하세요.
new URLSearchParams([
['search.name', 'Alice'],
['mode.name', 'exact'],
]);
기본값인 like 모드와 exact를 지정했을 때 효과가 같아 보일 수 있습니다. 차이점은 exact 모드는 비교에 =를 사용하고, like는 like 또는 ilike를 사용한다는 점입니다. 이론적으로 =가 더 나은 성능을 보일 수 있습니다.
또한, exact 모드에서는 여러 값을 전달할 수 있으며, 이 값들은 or로 연결됩니다:
new URLSearchParams([
['search.name', 'Alice'],
['search.name', 'Bob'],
['mode.name', 'exact'],
]);
즉, 이름이 "Alice" OR "Bob"인 사용자를 매칭합니다.
기본적으로 검색은 대소문자를 구분하지 않습니다. 더 엄밀하게 검색하려면 대소문자 구분을 활성화하세요:
new URLSearchParams([
['search.name', 'Alice'],
['search.name', 'Bob'],
['mode.name', 'exact'],
['isCaseSensitive', 'true'],
]);
isCaseSensitive는 전역 설정입니다. 따라서 모든 필드에 적용됩니다.
정규식 (RegEx)
PostgreSQL은 두 가지 유형의 정규식을 지원합니다. similar to와 posix입니다. 정규식 검색을 하려면 mode를 similar_to 또는 posix로 설정하세요:
new URLSearchParams([
['search', '^T.?m Scot+$'],
['mode', 'posix'],
]);
참고: similar_to 모드는 대소문자 구분 검색에서만 동작합니다.
매치 모드 오버라이드
기본적으로 모든 키워드는 일반 검색의 매치 모드를 상속받습니다:
new URLSearchParams([
['search', '^T.?m Scot+$'],
['mode', 'posix'],
['search.primaryEmail', 'tom%'], // Posix 모드
['joint', 'and'],
]);
특정 필드에 대해 오버라이드하려면:
new URLSearchParams([
['search', '^T.?m Scot+$'],
['mode', 'posix'],
['search.primaryEmail', 'tom%'], // Like 모드
['mode.primaryEmail', 'like'],
['search.phone', '0{3,}'], // Posix 모드
['joint', 'and'],
]);
외부 아이덴티티로 조회하기
소셜 또는 엔터프라이즈 SSO 아이덴티티에 연결된 사용자를 찾으려면, 다음 세 가지 쿼리 파라미터를 함께 전달하여 정확히 조회하세요:
identityType: 소셜 커넥터 아이덴티티는social, 엔터프라이즈 SSO 아이덴티티는sso.identityProvider: 소셜 아이덴티티의 경우 커넥터 대상(예:dingtalk), 엔터프라이즈 SSO 아이덴티티의 경우 발급자(issuer).identityId: 외부 아이덴티티 제공자가 발급한 사용자 식별자.
// DingTalk 소셜 아이덴티티에 연결된 사용자 찾기
new URLSearchParams([
['identityType', 'social'],
['identityProvider', 'dingtalk'],
['identityId', 'dingtalk-open-id'],
]);
// 엔터프라이즈 SSO 아이덴티티에 연결된 사용자 찾기
new URLSearchParams([
['identityType', 'sso'],
['identityProvider', 'https://example.com/issuer'],
['identityId', 'enterprise-user-id'],
]);
아이덴티티 필터는 다른 검색 필터와 AND 논리로 결합됩니다. 예를 들어, 키워드 검색으로 아이덴티티 조회를 더 좁힐 수 있습니다:
new URLSearchParams([
['identityType', 'social'],
['identityProvider', 'dingtalk'],
['identityId', 'dingtalk-open-id'],
['search', '%foo%'],
]);