디렉터리 스키마 확장 | Graph API concepts(Graph API 개념)

아티클
10/21/2021

이 항목에서는 외부 데이터 저장소 없이 디렉터리 개체에 속성을 추가하는 데 사용할 수 있는 Azure AD Graph API의 디렉터리 확장에 대해 알아봅니다. 예를 들어 조직에 디렉터리의 각 사용자에 대한 Skype ID를 필요로 하는 LOB(기간 업무) 응용 프로그램이 있는 경우 Graph API를 사용하여 디렉터리의 사용자 개체에 새 skypeId 속성을 등록한 다음 특정 사용자에 대한 값을 새 속성에 기록할 수 있습니다. 이 항목에서는 디렉터리 확장의 제한 사항, 디렉터리에 디렉터리 확장을 등록하는 방법 및 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 버전 1.5 이상을 사용해서만 확장을 등록할 수 있습니다. 등록할 수 있는 속성 유형은 다음과 같습니다.

속성 유형	설명
Binary	최대 256바이트
부울
DateTime	ISO 8601 형식으로 지정해야 합니다. UTC에 저장됩니다.
Integer	32비트 값입니다.
LargeInteger	64비트 값입니다.
문자열	최대 256자

위 속성 유형을 등록할 수 있는 디렉터리의 개체는 다음과 같습니다.

[사용자]
그룹
TenantDetail
[장치]
[응용 프로그램]
ServicePrincipal

확장 등록 방법 이해

확장 속성을 디렉터리에 등록하는 방법 및 Azure AD의 승인 모델이 해당 등록에 영향을 주는 방법을 이해해야 합니다. Azure AD의 응용 프로그램 동의에 대한 자세한 내용은 Azure Active Directory와 응용 프로그램 통합에 있는 동의 프레임워크 개요를 참조하십시오.

확장 속성은 개발자 디렉터리 내의 Application 개체에 등록됩니다. 개발자 디렉터리에서 사용자나 관리자가 응용 프로그램을 승인하고 나면 속성이 대상 디렉터리 유형에 추가되어 개발자 디렉터리에서 즉시 액세스할 수 있는 상태가 됩니다. 다중 테넌트 응용 프로그램의 경우 다른 조직의 사용자나 관리자가 응용 프로그램을 승인하면 해당 조직의 디렉터리 내 대상 디렉터리 유형에서 확장 속성에 즉시 액세스할 수 있게 됩니다.

조직에서 등록된 확장이 있는 응용 프로그램에 대해 "읽기 전용" 권한을 승인한 경우에도 다른 조직의 디렉터리에서 속성에 계속 액세스할 수 있습니다. 또한 등록된 응용 프로그램뿐 아니라 조직의 승인된 모든 응용 프로그램에서 확장 속성에 액세스할 수 있습니다. 해당 조직의 승인된 다른 응용 프로그램에서는 충분한 권한이 있는 경우 새 확장 속성에 대한 값을 읽거나 쓸 수 있습니다.

응용 프로그램이 삭제되거나 다른 조직의 디렉터리에서 승인이 제거된 경우에는 대상 디렉터리 개체에서 확장 속성에 액세스할 수 없게 됩니다. 응용 프로그램에 의해 확장이 삭제되면 대상 디렉터리 개체에서도 해당 확장에 액세스할 수 없게 됩니다. 다중 테넌트 응용 프로그램에서 승인을 받은 후 추가 확장 속성을 추가한 경우 다른 조직의 디렉터리에서 이러한 속성에 즉시 액세스할 수 있게 됩니다.

참고: 개체에 대해 확장 속성 값을 설정했는데 해당 개체 디렉터리에서 이 속성에 액세스할 수 없게 되어도 해당 개체의 확장 속성 값 제한인 100개에는 이 속성이 계속 포함됩니다. 속성 값을 설정한 후에 고려 대상에서 제거하려면 명시적으로 해당 값을 null로 설정해야 합니다. 확장 속성에 액세스할 수 없는 경우에는 이와 같이 설정할 수 없습니다.

시나리오 예

시나리오: Litware는 다른 조직에서 사용할 SaaS 응용 프로그램을 개발한 ISV(Independent Software Vendor)입니다. 이 응용 프로그램을 사용하려면 사용자 개체에 skypeId라는 확장 속성이 있어야 합니다. Litware는 먼저 자체 디렉터리에 응용 프로그램을 등록한 다음 Graph API를 호출하여 Application 개체에 확장 속성을 등록합니다. 그러면 Litware의 디렉터리 내 사용자 개체에서 이 속성에 액세스할 수 있게 됩니다. 마지막으로 Litware는 다른 조직에서 사용할 수 있도록 이 응용 프로그램을 다중 테넌트 가능하게 설정합니다.

Contoso에서 Litware의 SaaS 응용 프로그램을 사용하려고 합니다. 따라서 Contoso의 사용자 또는 관리자는 응용 프로그램을 승인해야 합니다. 승인 시 응용 프로그램이 Contoso 디렉터리에 등록되고 Litware에서 해당 응용 프로그램에 대해 등록한 확장 속성을 Contoso 디렉터리에서 즉시 사용할 수 있게 됩니다. Litware에서 사용자 개체에 대한 skypeId 확장 속성을 응용 프로그램에 대해 등록했으므로 Contoso 디렉터리의 User 개체에서 속성에 액세스할 수 있게 됩니다. 그러면 Litware의 응용 프로그램이나 Contoso 디렉터리에 포함된 기타 승인된 응용 프로그램이 Contoso 디렉터리에서 해당 응용 프로그램에 대해 구성된 권한에 따라 새 속성에 액세스할 수 있습니다. 즉, 해당 응용 프로그램은 권한에 따라 디렉터리의 사용자 한 명 이상에 대해 해당 확장 속성의 값을 쓸 수 있습니다. skypeId 값이 작성된 사용자의 경우에만 자신의 User 개체에 대해 해당 속성이 반환됩니다. skypeId 속성이 null로 설정될 때까지는 이 방식이 사용되며, 그 후에는 해당 사용자의 사용자 개체가 더 이상 속성을 반환하지 않습니다.

디렉터리 확장에 대한 샘플 REST 요청

다음 예제 요청에서는 디렉터리에서 확장을 보고, 쓰고, 읽고, 필터링하고, 등록 취소하는 방법을 보여 줍니다. &ltapplicationObjectId&gt 자리 표시자를 등록된 응용 프로그램의 개체 ID로 바꿉니다. 다음과 같은 방식으로 이 값을 가져올 수 있습니다.

https://graphexplorer.cloudapp.net/으로 이동하여 오른쪽 상단에 있는 Sign In 링크를 클릭한 다음 조직의 디렉터리 내 관리자 계정의 자격 증명을 사용하여 로그인합니다.
로그인한 후에 GET 단추 옆의 리소스 텍스트 상자에서 URL을 클릭하고 applications/로 끝나는 URL을 선택한 후에 GET 또는 Enter 키를 클릭합니다.
결과에서 원하는 응용 프로그램 항목을 찾아 다음과 같이 해당 objectId 값을 복사합니다. "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

이 섹션에서는 다음 작업을 위한 샘플 요청을 제공합니다.

확장 등록
등록된 확장 보기
확장 값 쓰기
확장 값 제거
확장 값 읽기
확장 값 필터링
확장 등록 취소

확장 속성을 사용하는 전체 샘플은 Github의 Azure AD 샘플을 참조하십시오.

WebApp-GraphAPI-DirectoryExtensions-PHP: PHP를 통해 확장을 만들고 사용하는 방법을 보여 줍니다.
WebApp-GraphAPI-DirectoryExtensions-DotNet: AAD 테넌트 조직도를 표시하고 확장 값을 즉시 읽을 수 있도록 합니다.

확장 등록

다음 샘플 요청은 원하는 Application 개체에 extensionProperty를 만듭니다.

요청 형식

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

샘플 요청

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

{
    "name": "skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

작업에 성공하면 대상 유형의 값을 쓰는 데 사용할 수 있는 정규화된 확장 속성 이름과 함께 HTTP 201 Created 상태 코드가 반환됩니다.

샘플 응답

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

등록된 확장 보기

다음 샘플 요청은 Application 개체에 등록된 확장을 가져옵니다.

요청 형식

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

샘플 요청

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

작업에 성공하면 응용 프로그램 개체에 등록된 각 확장 속성에 대한 모든 정보와 함께 HTTP 200 확인 상태 코드가 반환됩니다.

샘플 응답

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

확장 값 쓰기

다음 샘플 요청은 User 개체의 *skypeId^ 확장 속성에 확장 값을 기록합니다.

요청 형식

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

샘플 요청

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

작업에 성공하면 HTTP 204 No Content 상태 코드가 반환됩니다.

샘플 응답

HTTP/1.1 204 No Content

개체에 대한 쓰기 시도가 확장 값 제한인 100회를 초과하면 오류 코드가 "Directory_ResourceSizeExceeded"인 HTTP 403 사용할 수 없음 응답과 “개체의 크기 제한이 초과되었습니다. 값 수를 줄인 후에 요청을 다시 시도하세요."라는 메시지를 반환합니다.

확장 값 제거

다음 샘플 요청은 값을 null로 설정하여 User 개체에서 이전에 skypeId 확장 속성에 대해 설정된 확장 값을 제거합니다.

요청 형식

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

샘플 요청

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

작업에 성공하면 HTTP 204 No Content 상태 코드가 반환됩니다.

샘플 응답

HTTP/1.1 204 No Content

확장 값 읽기

다음 예제 요청은 사용자에 대한 간단한 GET 작업을 수행하며, 표준 속성 값 및 새 확장 속성 값을 반환합니다.

요청 형식

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

샘플 요청

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

작업에 성공하면 새 확장 속성 값과 함께 HTTP 200 OK 상태 코드가 반환됩니다(간단하게 나타내기 위해 많은 사용자 속성이 예제 응답에서 제거됨).

샘플 응답

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

확장 값 필터링

다음 예제 요청은 지정된 확장 속성 값으로 사용자를 필터링합니다.

참고: 확장에 대한 접두사 검색은 문자열 검색의 경우 71자, 이진 확장 검색의 경우 207자로 제한됩니다.

요청 형식

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

샘플 요청

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

작업에 성공하면 결과 사용자 개체와 함께 HTTP 200 OK 상태 코드가 반환됩니다.

샘플 응답

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

확장 등록 취소

다음 예제 요청은 확장 개체 ID에 대해 DELETE 작업을 수행하여 확장 속성의 등록을 취소합니다.

요청 형식

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

샘플 요청

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

작업에 성공하면 HTTP 204 No Content 상태 코드가 반환되고 응용 프로그램에서 확장 속성의 등록이 취소됩니다.

샘플 응답

HTTP/1.1 204 No Content

확장 동작 및 제한

디렉터리의 확장 속성에는 다음과 같은 동작 및 제한이 적용됩니다.

응용 프로그램에 대해 등록된 확장 속성은 디렉터리 사용자 또는 관리자가 해당 응용 프로그램을 승인하면 디렉터리에서 사용할 수 있게 됩니다.
디렉터리에서 확장 속성을 사용할 수 있게 되면 승인된 응용 프로그램이 디렉터리 내의 해당 응용 프로그램 권한에 따라 이 속성이 적용되는 개체에 대해 해당 확장 속성의 값을 읽거나 쓸 수 있습니다. 확장 속성이 적용되는 개체는 targetObjects 속성에서 지정됩니다.
디렉터리의 특정 개체에 대해 확장 속성 값을 100개까지 기록할 수 있습니다. 예를 들어 디렉터리의 사용자에 대해 다른 확장 속성 값이 기록되지 않았다고 가정할 때 응용 프로그램이 user1에 대해 확장 속성 값을 기록하면 나머지 99개 확장 속성의 값은 해당 응용 프로그램이나 디렉터리 내의 적합한 권한이 있는 다른 응용 프로그램이 기록할 수 있습니다. 그러나 디렉터리의 다른 사용자에 대해서도 확장 속성 값을 100개까지 기록할 수 있습니다.
응용 프로그램이 확장 속성 값 100개가 이미 설정된 개체에 대해 추가 확장 속성 값을 설정하려고 하면 Graph API에서는 오류 코드가 "Directory_ResourceSizeExceeded"인 403 사용할 수 없음 응답과 “개체의 크기 제한이 초과되었습니다. 값 수를 줄인 후에 요청을 다시 시도하세요."라는 메시지를 반환합니다.
개발자가 응용 프로그램에서 확장 속성을 등록 취소(삭제)하면 개발자 디렉터리와 응용 프로그램이 승인된 디렉터리에서 해당 확장 속성이 즉시 액세스할 수 없는 상태가 됩니다.
개발자 디렉터리에서 응용 프로그램을 제거하면 개발자 디렉터리와 응용 프로그램이 승인된 디렉터리에서 해당 응용 프로그램에 등록된 모든 확장 속성이 즉시 액세스할 수 없는 상태가 됩니다.
디렉터리에서 승인된 다중 테넌트 응용 프로그램이 나중에 해당 디렉터리에서 등록 취소(제거)되면(예: 관리자가 Azure 관리 포털을 통해 등록 취소/제거함) 해당 디렉터리에서 이 응용 프로그램에 등록된 모든 확장 속성이 즉시 액세스할 수 없는 상태가 됩니다.
확장 속성 값은 명시적으로 null로 설정해야 디렉터리 개체에서 제거할 수 있습니다. 디렉터리 개체에 대해 확장 속성 값을 설정했는데 위에서 설명한 이유로 인해 디렉터리에서 해당 확장 속성에 액세스할 수 없게 되면 해당 디렉터리 개체에 대해 확장 속성이 더 이상 표시되지 않습니다. 그러나 해당 개체의 확장 속성 값 제한인 100개에는 이 속성이 계속 포함됩니다. 경우에 따라 응용 프로그램을 다시 승인하는 등의 방법을 통해 확장 속성을 다시 사용할 수 있게 될 때까지는 읽기 또는 쓰기를 위해 값에 액세스할 수 없습니다.

추가 리소스

Azure AD Graph API 참조

getMemberObjects [getObjectsByObjectIds]: ../api/functions-and-actions.md#getObjectsByObjectIds [isMemberOf]: ../api/functions-and-actions.md#isMemberOf [restore]: ../api/functions-and-actions.md#restore

다음을 통해 공유

디렉터리 스키마 확장 | Graph API concepts(Graph API 개념)

확장 데이터 형식

확장 등록 방법 이해

시나리오 예

디렉터리 확장에 대한 샘플 REST 요청

확장 등록

요청 형식

샘플 요청

샘플 응답

등록된 확장 보기

요청 형식

샘플 요청

샘플 응답

확장 값 쓰기

요청 형식

샘플 요청

샘플 응답

확장 값 제거

요청 형식

샘플 요청

샘플 응답

확장 값 읽기

요청 형식

샘플 요청

샘플 응답

확장 값 필터링

요청 형식

샘플 요청

샘플 응답

확장 등록 취소

요청 형식

샘플 요청

샘플 응답

확장 동작 및 제한

추가 리소스

추가 리소스