고급 사용자 검색
Management API 를 직접 사용하여 고급 사용자 검색 조건을 활용하세요.
검색 요청 수행하기
사용자 검색을 위해 GET /api/users를 사용하세요. 다른 Management API 와 마찬가지로 인증이 필요합니다. 상호작용 방법은 Management API 와 상호작용하기를 참조하세요.
예시
요청
curl \
--location \
--request GET \
'http://<your-logto-endpoint>/api/users?search=%25alice%25'
응답
User 엔티티의 배열.
[
{
"id": "MgUzzDsyX0iB",
"username": "alice_123",
"primaryEmail": "[email protected]",
"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가 포함되거나 이메일이 @gmail.com으로 끝나는 사용자를 검색하는 것을 의미합니다.
결합 모드 변경하기
API 가 모든 조건을 만족하는 결과만 반환하도록 하려면, 결합 모드를 and로 설정하세요:
new URLSearchParams([
['search.name', '%foo%'],
['search.primaryEmail', '%@gmail.com'],
['joint', 'and'],
]);
이는 이름에 foo가 포함되고 이메일이 @gmail.com으로 끝나는 사용자를 검색하는 것을 의미합니다.
정확한 매칭 및 대소문자 구분
이름이 정확히 "Alice"인 사람을 검색하고 싶다면, mode.name을 설정하여 정확한 매칭을 사용하세요.
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" 또는 "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'],
]);
참고: Mode 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'],
]);