작업 개요 | Graph API concepts(Graph API 개념)
Azure AD (Active Directory) Graph API는 테넌트에서 사용자, 그룹, 연락처와 같은 개체를 읽고 수정하는 데 사용할 수 있는 OData 3.0 규격 서비스입니다. Azure AD Graph API는 서비스를 사용하여 작업을 수행하기 위해 HTTP 요청을 전송하는 REST 끝점을 표시합니다. 다음 섹션에서는 Graph API를 사용하여 디렉터리 리소스 읽기 및 쓰기, 디렉터리 함수 또는 동작 호출, 디렉터리에 대한 쿼리 등을 수행할 때 요청 형식을 지정하는 방법과 예상되는 응답에 대한 일반적인 정보를 제공합니다. 디렉터리 리소스에 특정 작업을 수행하는 방법에 대한 자세한 내용은 Azure AD Graph API 참조의 해당 작업 항목을 참조하십시오.
Graph API에 대한 요청에 성공하려면 주소가 유효한 끝점으로 지정되어 있고 올바른 형식으로 되어 있어야 합니다. 즉, 요청 본문에 필수 헤더가 모두 포함되어 있고 필요한 경우에는 JSON 페이로드도 포함되어 있어야 합니다. 요청을 만드는 응용 프로그램에는 요청의 대상 리소스에 액세스할 권한이 부여되었음을 입증할 수 있도록 Azure AD에서 받은 토큰을 포함해야 합니다. 응용 프로그램에서는 Graph API에서 받은 모든 응답을 처리할 수 있어야 합니다.
이 항목의 섹션은 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 블로그 게시물을 참조하십시오.
인증 및 권한 부여
Graph API에 대한 모든 요청에 Azure Active Directory에서 발급한 전달자 토큰이 첨부되어 있어야 합니다. 토큰에는 애플리케이션, 로그인한 사용자(위임된 권한의 경우), 디랙터리에서 응용 프로그램이 수행하도록 권한이 부여된 작업에 대한 정보가 포함됩니다. 이 토큰은 요청의 Authorization 헤더를 통해 전달됩니다. 예(간결성을 위해 토큰 축소):
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Graph API는 토큰에 있는 OAuth 2.0 권한 범위에 따라 권한 부여를 수행합니다. Graph API를 표시하는 사용 권한 범위에 대한 자세한 내용은 Graph API 사용 권한 범위를 참조하십시오.
응용 프로그램이 Azure AD에서 인증을 받고 Graph API를 호출하도록 하려면 테넌트에 응용 프로그램을 추가한 후 Microsoft Azure Active Directory에 대한 권한을 요청하도록 구성해야 합니다(OAuth 2.0 권한 범위). 응용 프로그램을 추가 및 구성하는 방법에 대한 자세한 내용은 Azure Active Directory와 응용 프로그램 통합을 참조하십시오.
Azure AD에서는 OAuth 2.0 인증 프로토콜을 사용합니다. 지원되는 흐름 및 액세스 토큰을 비롯한 Azure AD의 OAuth 2.0에 대한 자세한 내용은 Azure AD의 OAuth 2.0에서 확인할 수 있습니다.
끝점 주소 지정
Graph API를 사용하여 작업을 수행하려면 GET, POST, PATCH, PUT, DELETE 등의 지원되는 방법을 통해 서비스, 리소스 컬렉션, 개별 리소스, 리소스, 리소스의 탐색 속성 또는 서비스에서 표시하는 함수나 동작을 대상으로 하는 끝점으로 HTTP 요청을 보냅니다. 끝점은 URL로 표현됩니다.
다음은 Graph API 끝점의 기본 형식에 대한 설명입니다.
https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}
URL을 구성하는 구성 요소는 다음과 같습니다.
- 서비스 루트: 모든 Graph API 요청에 대한 서비스 루트는
https://graph.windows.net입니다. - 테넌트 식별자 {tenant_id}: 요청의 대상 테넌트 식별자입니다.
- 리소스 경로 {resource_path}: 요청의 대상 리소스(예: 사용자 또는 그룹) 경로입니다.
- Graph API 버전 {api_version}: 요청의 대상 Graph API 버전입니다. 쿼리 매개 변수로 표현되며 필수입니다.
참고: 경우에 따라, 리소스 컬렉션을 읽을 때 요청에 OData 쿼리 매개 변수를 추가하여 결과 집합을 필터링하고 순서와 페이지를 지정할 수 있습니다. 자세한 내용은 이 항목의 OData 쿼리 매개 변수 섹션을 참조하십시오.
테넌트 식별자 {tenant_id}
네 가지 방법 중 하나로 요청의 대상 테넌트를 지정할 수 있습니다.
테넌트 개체 ID 사용. 테넌트를 만들 떄 할당한 GUID입니다. TenantDetail 개체의 objectId 속성에서 찾을 수 있습니다. 다음 URL에서는 테넌트 개체 ID를 사용하여 사용자 리소스 컬렉션에 주소를 지정하는 방법을 보여 줍니다.
https://graph.windows.net/12345678-9abc-def0-1234-56789abcde/users?api-version=1.6.확인된(등록된) 도메인 이름 사용. 테넌트에 대해 등록된 도메인 이름 중 하나입니다. TenantDetail 개체의 verifiedDomains 속성에서 찾을 수 있습니다. 다음 URL에는 contoso.com이라는 도메인이 포함된 테넌트의 사용자 리소스 컬렉션에 주소를 지정하는 방법이 나와 있습니다.
https://graph.windows.net/contoso.com/users?api-version=1.6.myOrganization별칭 사용. OAuth 인증 코드 권한 유형(3각) 인증을 사용하는 경우, 즉 위임된 권한 범위를 사용하는 경우에만 이 별칭을 사용할 수 있습니다. 이 별칭은 대/소문자를 구분하지 않으며, URL에서 개체 ID 또는 테넌트 도메인을 바꿉니다. 이 별칭을 사용할 경우 Graph API가 요청에 연결된 토큰에 있는 클레임에서 테넌트를 파생시킵니다. 다음 URL에는 이 별칭을 사용하여 테넌트의 사용자 리소스 컬렉션에 주소를 지정하는 방법이 나와 있습니다.
https://graph.windows.net/myorganization/users?api-version=1.6.me별칭 사용. OAuth 인증 코드 권한 유형(3각) 인증을 사용하는 경우, 즉 위임된 권한 범위를 사용하는 경우에만 이 별칭을 사용할 수 있습니다. 이 별칭은 대/소문자를 구분하지 않으며, URL에서 개체 ID 또는 테넌트 도메인을 바꿉니다. 이 별칭을 사용할 경우 Graph API가 요청에 연결된 토큰에 있는 클레임에서 사용자를 파생시킵니다. 다음 URL에서 이 별칭을 사용하여 로그인한 사용자 처리:https://graph.windows.net/me?api-version=1.6.
참고: me 별칭은 로그인한 사용자에 대한 작업의 대상을 지정하는 용도로만 사용합니다. 자세한 내용은 로그인한 사용자 작업을 참조하십시오.
리소스 경로 {resource_path}
리소스 컬렉션, 개별 리소스, 리소스의 탐색 속성, 테넌트에 표시된 함수 또는 동작, 리소스에 표시된 함수 또는 동작 중에서 어떤 것을 대상으로 지정하는지에 따라 {resource_path}를 다르게 지정합니다.
| 대상 | 경로 | 설명 |
|---|---|---|
| 서비스 메타데이터 | /$metadata |
서비스 메타데이터 문서를 반환합니다. 다음 예에서는 contoso.com 테넌트를 사용하여 서비스 메타데이터의 대상을 지정합니다. https://graph.windows.net/contoso.com/$metadata?api-version=1.6 참고: 서비스 메타데이터를 읽는 데에는 인증이 필요 없습니다. |
| 리소스 컬렉션 | /{resource_collection} |
테넌트의 사용자나 그룹과 같은 리소스 컬렉션을 대상으로 합니다. 이 경로를 사용하여 컬렉션에 있는 리소스를 읽을 수 있으며, 리소스 유형에 따라 테넌트에 새 리소스를 만들 수 있습니다. 대부분의 경우 읽기에서 반환되는 결과 집합에 쿼리 매개 변수를 추가하여 결과를 필터링하거나 순서 또는 페이지를 지정하면 결과 집합을 상세하게 조정할 수 있습니다. 다음 예에서는 사용자 컬렉션을 대상으로 합니다. https://graph.windows.net/myorganization/users?api-version=1.6 |
| 단일 리소스 | /{resource_collection}/{resource_id} |
테넌트에서 사용자, 조직 연락처, 그룹과 같은 특정 리소스를 대상으로 지정합니다. 대부분의 리소스에서 resource_id는 개체 ID입니다. 일부 리소스에서는 추가 지정자를 사용할 수 있습니다. 예를 들어, 사용자는 UPN(사용자 계정 이름)으로 지정할 수도 있습니다. 리소스에 따라, 이 경로를 사용하여 리소스의 선언된 속성을 가져오거나, 선언된 속성을 수정하거나, 리소스를 삭제할 수 있습니다. 다음 예에서는 사용자 john@contoso.com을 대상으로 합니다. https://graph.windows.net/contoso.com/users/john@contoso.com?api-version=1.6 |
| 탐색 속성(개체) | /{resource_collection}/{resource_id}/{property_name} |
사용자의 관리자나 그룹 멤버 자격 또는 그룹 구성원과 같은 특정 리소스의 탐색 속성을 대상으로 합니다. 이 경로를 사용하여 대상 탐색 속성에서 참조된 개체를 반환할 수 있습니다. 다음 예에서는 john@contoso.com의 관리자를 대상으로 합니다. https://graph.windows.net/contoso.com/users/john@contoso.com/manager?api-version=1.6 참고: 이 주소 지정 형식은 읽기에만 사용할 수 있습니다. |
| 탐색 속성(링크) | /{resource_collection}/{resource_id}/$links/{property_name} |
사용자의 관리자나 그룹 멤버 자격 또는 그룹 구성원과 같은 특정 리소스의 탐색 속성을 대상으로 합니다. 이 주소 지정 형식을 사용하여 탐색 속성을 읽고 수정하는 작업을 모두 수행할 수 있습니다. 읽을 때 속성에서 참조하는 개체는 응답 본문에서 하나 이상의 링크로 반환됩니다. 쓸 때 개체는 요청 본문에 하나 이상의 링크로 지정됩니다. 다음 예에서는 john@contoso.com의 관리자 속성을 대상으로 합니다. https://graph.windows.net/contoso.com/users/john@contoso.com/$links/manager?api-version=1.6 |
| 테넌트에 표시되는 함수 또는 동작 | /{function_name} |
테넌트에 표시되는 함수 또는 동작을 대상으로 합니다. 함수 및 동작은 일반적으로 POST 요청으로 호출하며 요청 본문을 포함할 수 있습니다. 다음 예에서는 [isMemberOf] 함수를 대상으로 합니다. https://graph.windows.net/myorganization/isMemberOf?api-version=1.6. |
| 함수 또는 도작이 리소스에 표시됩니다. | /{resource_collection}/{resource_id}/{function_name} |
리소스에 표시되는 함수 또는 동작을 대상으로 합니다. 함수 및 동작은 일반적으로 POST 요청으로 호출하며 요청 본문을 포함할 수 있습니다. 다음 예에서는 getMemberGroups 함수를 대상으로 합니다. https://graph.windows.net/myorganization/users/john@contoso.com/getMemberGroups?api-version=1.6. |
Graph API 버전 {api-version}
특정 버전의 Graph API를 작업의 대상으로 지정하려면 api-version 쿼리 매개 변수를 사용합니다. 이 매개 변수는 필수입니다.
api-version 매개 변수의 값은 다음 중 하나일 수 있습니다.
- "beta"
- "1.6"
- "1.5"
- "2013/11/08"
- "2013/04/05"
예를 들어, 다음 URL은 Graph API 버전 1.6을 사용하는 사용자 컬렉션을 대상으로 합니다.
https://graph.windows.net/myorganization/users?api-version=1.6
버전과 버전 간의 기능 변경에 대한 자세한 내용은 버전 관리를 참조하십시오.
OData 쿼리 매개 변수
리소스 컬렉션을 읽을 때 요청에 OData 쿼리 매개 변수를 첨부해서 결과 집합을 필터링하거나 정렬, 페이징할 수 있는 경우가 많습니다.
Graph API에서는 다음 OData 쿼리 매개 변수를 지원합니다.
- $filter
- $batch
- $expand
- $orderby
- $top
- $skiptoken 및 previous-page
지원되는 OData 쿼리 매개 변수와 Graph API에서의 제한에 대한 자세한 내용은 지원되는 쿼리, 필터, 페이징 옵션을 참조하십시오.
요청 및 응답 헤더
다음 표에서는 Graph API에서의 요청에 사용되는 일반적인 HTTP 헤더를 보여 줍니다. 이 설명은 포괄적인 설명이 아닙니다.
| 요청 헤더 | 설명 |
|---|---|
| 권한 부여 | 필수 사항입니다. Azure Active Directory에서 발급한 전달자 토큰입니다. 자세한 내용은 이 항목의 인증 및 권한 부여를 참조하십시오. |
| Content-Type | 요청 본문이 있으면 필수입니다. 요청 본문에 있는 콘텐츠의 미디어 유형입니다. application/json을 사용합니다. 미디어 유형에 매개 변수가 포함될 수 있습니다. 참고: application/atom+xml과 application/xml(링크의 경우)은 지원되지만, 성능이 떨어지고 이후 릴리스에서 XML 지원이 중단될 예정이기 때문에 권장되지 않습니다. |
| Content-Length | 요청 본문이 있으면 필수입니다. 요청의 길이(바이트 수)입니다. |
다음 표에서는 Graph API에서의 응답으로 반환되는 일반적인 HTTP 헤더를 보여 줍니다. 이 설명은 포괄적인 설명이 아닙니다.
| 응답 헤더 | 설명 |
|---|---|
| Content-Type | 응답 본문에 있는 콘텐츠의 미디어 유형입니다. 기본값은 application/json입니다. 사용자의 축소판 사진 요청에 대해서는 기본적으로 image/jpeg가 반환됩니다. |
| 위치 | 디렉터리에 새로운 리소스(개체)를 만드는 POST 요청에 대한 응답에서 반환됩니다. 새로 만든 리소스의 URI를 포함합니다. |
| ocp-aad-diagnostics-server-name | 요청한 작업을 수행한 서버의 식별자입니다. |
| ocp-aad-session-key | 디렉터리 서비스로 현재 세션을 식별하는 키입니다. |
각 요청에 대해 최소한 다음을 수행하는 것이 좋습니다.
- 요청 제출 타임스탬프를 정확하게 기록합니다.
client-request-id를 보내고 기록합니다.- HTTP 응답 코드 및
request-id를 기록합니다.
이러한 기록에 정보를 제공하면 도움이나 지원을 요청할 때 Microsoft에서 문제 해결을 더 쉽게 도울 수 있습니다.
요청 및 응답 본문
POST, PATCH 및 PUT 요청의 요청 본문은 JSON 또는 XML 페이로드로 보낼 수 있습니다. 서버 응답은 JSON 또는 XML 페이로드로 반환할 수 있습니다. 페이로드는 Content-Type 요청 헤더를 사용하여 요청 본문에 지정하고 Accept 요청 헤더를 사용하여 응답에 지정할 수 있습니다.
Graph API의 요청 및 응답에 JSON 페이로드를 사용하는 것이 좋습니다. XML은 이후 릴리스에서 중단될 예정이며 성능도 저하되기 때문입니다.
고급 기능
앞의 섹션에서는 Graph API의 기본 요청 및 응답 형식을 설명했습니다. 고급 기능은 추가 쿼리 문자열 매개 변수를 더하거나 이 항목의 앞부분에서 설명한 기본 작업과 요청 및 응답 본문이 크게 다를 수도 있습니다.
ÀÌ·¯ÇÑ ±â´É¿¡´Â ´ÙÀ½ÀÌ Æ÷ÇԵ˴ϴÙ.
- 일괄 처리: Graph API에서는 일괄 처리를 지원합니다. 일괄 처리로 요청을 보내면 서버 왕복을 줄여서 네트워크 오버헤드를 줄일 수 있으므로 작업을 더 빨리 완료하는 데 도움이 됩니다. Graph API에서의 일괄 처리에 대한 자세한 내용은 일괄 처리를 참조하십시오.
- 차등 쿼리: Graph API에서는 차등 쿼리 수행을 지원합니다. 차등 쿼리를 사용하면 서로 다른 시간에 발급된 요청 사이에서 테넌트에 있는 특정 엔터티의 변경 사항을 반환할 수 있습니다. 이 기능은 테넌트의 변경 사항이 있는 로컬 저장소를 동기화할 때 주로 사용됩니다. Graph API의 차등 쿼리에 대한 자세한 내용은 차등 쿼리를 참조하십시오.
추가 리소스
getMemberObjects [getObjectsByObjectIds]: ../api/functions-and-actions.md#getObjectsByObjectIds [isMemberOf]: ../api/functions-and-actions.md#isMemberOf [restore]: ../api/functions-and-actions.md#restore