지원되는 쿼리, 필터, 페이징 옵션 | Graph API concepts(Graph API 개념)
이 항목에서는 Azure AD(Active Directory) Graph API에 사용할 수 있는 쿼리 옵션, 필터 및 페이징 작업을 보여 줍니다. 마지막 섹션에서는 Azure AD Graph API를 사용하여 수행할 수 있는 일반적인 쿼리의 몇 가지 예제를 제공합니다.
중요
Azure Active Directory 리소스에 액세스하려면 Azure AD Graph가 아닌 Microsoft Graph를 사용하는 것이 좋습니다.우리는 현재 Microsoft Graph 개발에 집중하고 있으며 앞으로 Azure AD Graph API에 대한 개선 작업은 계획이 없습니다.아직까지 Azure AD Graph API가 적합할 수 있는 시나리오는 매우 제한적입니다. 자세한 내용은 Office 개발자 센터의 Microsoft Graph 또는 Azure AD Graph 블로그 게시물을 참조하십시오.
주소 지정
아래의 쿼리는 모두 도메인 이름을 사용하여 테넌트의 주소를 지정합니다. contoso.com을 테넌트의 등록된 도메인 이름 중 하나, 테넌트의 ID(GUID) 또는 MyOrganization 별칭(위임된 액세스의 경우)으로 바꿀 수 있습니다. 경우에 따라 me 별칭을 사용할 수도 있습니다. 테넌트의 주소를 지정하는 방법에 대한 자세한 내용은 작업 개요를 참조하세요.
지원되는 쿼리 옵션
Graph에서는 $filter, $orderby, $expand, $top 및 $format 쿼리 옵션을 지원합니다. 현재 $count, $inlinecount 및 $skip 쿼리 옵션은 지원되지 않습니다.
$filter
필터를 포함하는 쿼리에 다음 일반 제한 사항이 적용됩니다.
$filter는 $orderby 식과 결합할 수 없습니다.
DirectoryRole 또는 SubscribedSku 디렉터리 개체의 쿼리에 대해서는 필터링이 지원되지 않습니다.
지원되는 디렉터리 개체의 속성 중 일부는 필터 식에 사용할 수 없습니다. 지원되는 유형의 필터링 가능한 속성에 대한 자세한 내용은 User, Group 및 Contact를 참조하세요.
필터 식에는 다음 제한 사항이 적용됩니다.
논리 연산자: and 및 or가 지원됩니다. 예를 들면 다음과 같습니다.
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')비교 연산자: eq(같음), ge(크거나 같음) 및 le(작거나 같음)가 지원됩니다.
startswith가 지원됩니다. 예를 들면 다음과 같습니다.
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')다중값 속성을 쿼리할 때 any가 지원됩니다. 예를 들면 다음과 같습니다.
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')산술 연산자: 지원되지 않습니다.
함수: 지원되지 않습니다.
null 값은 필터 식의 피연산자로 지원되지 않습니다. 예를 들어 설정되지 않은 속성을 필터링하기 위해 null 값을 지정할 수는 없습니다.
$orderby
$orderby는 지정된 매개 변수별로 반환된 개체를 정렬합니다. $orderby 옵션을 이용한 예제 요청은 다음과 같습니다.
| 요청 | 설명 |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
표시 이름 기준으로 정렬된 사용자 목록을 반환합니다. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
표시 이름 기준으로 정렬된 첫 50명의 사용자 목록을 반환합니다. |
$orderby 식에는 다음 제한 사항이 적용됩니다.
현재 두 가지 정렬 순서가 지원됩니다. 하나는 User 및 Group 개체에 대한 DisplayName이며, 다른 하나는 User 개체에 대한 UserPrincipalName입니다. 사용자는 기본적으로 UserPrincipalName순으로 정렬됩니다.
$orderby는 $filter 식과 결합할 수 없습니다.
$expand
$expand는 개체 및 이와 연결된 개체를 반환합니다. $expand 옵션을 이용한 예제 요청은 다음과 같습니다.
| 요청 | 설명 |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
그룹 개체를 비롯해 그 구성원도 반환합니다. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
사용자 개체를 비롯해 그 부하 직원도 반환합니다. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
사용자 개체를 비롯해 그 관리자도 반환합니다. |
$expand 식에는 다음 제한 사항이 적용됩니다.
- 요청에 대하여 반환되는 최대 개체 수는 20개입니다.
$top
DirectoryRole 또는 SubscribedSku 디렉터리 개체의 쿼리에 대해서는 $top이 지원되지 않습니다.
페이징 지원
Graph에서 앞 뒤 페이지로 이동할 수 있습니다. 페이징 결과를 포함한 응답에는 다음 결과 페이지로 이동할 수 있는 skip 토큰(odata.nextLink)이 포함됩니다. 이 skip 토큰은 뒤 페이지로 이동하기 위한 previous-page=true 쿼리 인수와 결합될 수 있습니다.
다음 예제 요청은 페이지를 앞으로 이동하는 것을 보여줍니다.
| 요청 | 설명 |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
이전 응답의 $skiptoken 매개 변수가 포함되며 이를 통해 다음 결과 페이지로 이동할 수 있습니다. |
다음 예제 요청은 페이지를 뒤로 이동하는 것을 보여줍니다.
| 요청 | 설명 |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
이전 응답의 $skiptoken 매개 변수가 포함됩니다. 이와 &previous-page=true 매개 변수를 결합하면 이전 결과 페이지가 검색됩니다. |
다음 단계는 페이지를 앞 뒤로 이동하기 위한 요청/응답 흐름을 보여줍니다.
- 15명의 사용자 중 처음 10명의 사용자 목록을 가져오기 위한 요청이 수행됩니다. 응답에는 10명 사용자의 마지막 페이지를 나타내는 skip 토큰이 포함됩니다.
- 최종 5명을 얻기 위해 이전 응답에서 반환된 skip 토큰을 포함한 또 다른 요청을 수행합니다.
- 뒤 페이지로 이동하려면 1단계에서 반환된 skip 토큰을 사용하여 요청을 수행하고 &previous-page=true 매개 변수를 요청에 추가합니다.
- 응답에는 이전(첫) 페이지의 사용자 10명이 포함됩니다. 더 많은 페이지가 남아 있는 다른 시나리오에서는 새 skip 토큰이 반환됩니다. 다시 뒤 페이지로 이동하기 위해 &previous-page=true와 함께 이 새 skip 토큰을 요청에 추가할 수 있습니다.
다음 제한 사항이 페이징 요청에 적용됩니다.
- 기본 페이지 크기는 100입니다. 최대 페이지 크기는 999입니다.
- 역할에 대한 쿼리는 페이징을 지원하지 않습니다. 여기에는 역할 개체 자신뿐 아니라 역할 멤버의 읽기도 포함됩니다.
- 테넌트의 모든 사용자 검색(/users) 같은 리소스 목록은 쿼리에서 페이징을 지원합니다. 예:
https://graph.windows.net/contoso.com/users?api-version=1.6. 그러나 모든 유형에 대해 필터가 적용되는 경우에는 페이징이 지원되지 않으며 결과의 첫 번째 페이지만 반환됩니다. - 페이징은 그룹 구성원 쿼리와 같은 링크 검색에 대해서는 지원되지 않습니다. 예:
https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.
정렬 순서
- 모든 사용자에 대한 쿼리의 결과 집합은 UserPrincipalName 속성을 기준으로 정렬됩니다. 예:
https://graph.windows.net/contoso.com/users?api-version=1.6. - 그룹, 연락처 등의 다른 모든 최상위 리소스의 쿼리 결과 집합은 objectId 속성을 기준으로 정렬됩니다. 예:
https://graph.windows.net/contoso.com/groups?api-version=1.6. - 최상위 리소스 이외의 쿼리 결과의 순서는 확정적이지 않습니다.
일반적인 쿼리
다음 섹션에서는 Graph API를 사용하여 수행할 수 있는 일반적인 쿼리의 몇 가지 예제를 보여 줍니다.
최상위 리소스 쿼리
다음 쿼리는 contoso.com을 예제 테넌트로 사용하여 Graph API로 최상위 리소스에 액세스하는 방법을 보여 줍니다. 테넌트에 대해 쿼리를 실행하려면 Azure AD에서 받은 유효한 전달자 토큰을 포함하는 Authorization 헤더가 필요합니다.
| 최상위 리소스 | 쿼리 결과 | URI(contoso.com의 경우) |
|---|---|---|
| 최상위 리소스 | 아래에도 나와 있는 디렉터리 서비스에 대한 최상위 리소스의 URI 목록을 반환합니다. | https://graph.windows.net/contoso.com?api-version=1.6 |
| 회사 정보 | 회사 정보를 반환합니다. | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| 연락처 | 조직 연락처 정보를 반환합니다. | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| 사용자 | 사용자 정보를 반환합니다. | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| 그룹 | 그룹 데이터를 반환합니다. | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| 디렉터리 역할 | 테넌트의 활성화된 모든 디렉터리 역할을 반환합니다. | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | 테넌트의 구독을 반환합니다. | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| 디렉터리 메타데이터 | 데이터 모델을 설명하는 서비스 메타데이터 문서(즉, 디렉터리 리소스의 구조 및 구성)를 반환합니다. | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
기타 쿼리 작업
다음 표에는 contoso.com을 예제 테넌트로 사용하는 몇 가지 추가 예제 Graph API 쿼리가 나와 있습니다.
| 쿼리 작업 | URI(contoso.com의 경우) |
|---|---|
| 모든 사용자 및 그룹 나열 | https://graph.windows.net/contoso.com/users?api-version=1.6로 변환해야 합니다. https://graph.windows.net/contoso.com/groups?api-version=1.6로 변환해야 합니다. |
| objectId 또는 userPrincipalName을 지정하여 개별 사용자 검색 | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6로 변환해야 합니다. https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6로 변환해야 합니다. |
| displayName이 “Jon Doe”인 사용자에 대한 요청 및 필터링 | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| firstName이 “Jon”인 특정 사용자에 대한 요청 및 필터링 | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| givenName 및 surname 값에 대한 필터링 | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| objectId를 지정하여 개별 그룹 검색 | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| 사용자의 관리자 검색 | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| 사용자의 부하 직원 목록 검색 | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| 사용자의 부하 직원에 대한 링크 목록 검색 | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| 그룹의 멤버 자격 목록 검색 | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| 그룹의 멤버에 대한 링크 목록 검색 | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| 사용자의 그룹 멤버 자격 검색(비전이적) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| 사용자가 멤버인 그룹의 목록 검색(비전이적) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| displayName >= "az" and <= "dz"인 그룹에 대한 요청 및 필터링 | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Azure Active Directory B2C 테넌트의 모든 로컬 계정 사용자 반환 | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Azure Active Directory B2C 테넌트에서 로그인 이름이 "joe@example.com"인 로컬 계정 사용자 반환 | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
참고: 쿼리 문자열의 공백은 요청을 보내기 전에 URL로 인코딩해야 합니다. 예를 들어 쿼리 문자열, https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6은 https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6과 같이 URL로 인코딩되어야 합니다.
추가 리소스
getMemberObjects [getObjectsByObjectIds]: ../api/functions-and-actions.md#getObjectsByObjectIds [isMemberOf]: ../api/functions-and-actions.md#isMemberOf [restore]: ../api/functions-and-actions.md#restore