내보내기(0) 인쇄
모두 확장

Azure AD Graph 차등 쿼리

업데이트 날짜: 2014년 4월

이 항목에서는 Azure Active Directory Graph에 대해 수행할 수 있는 차등 쿼리를 설명합니다. 차등 쿼리 요청에서는 연속된 두 요청 사이의 시간 동안 지정된 엔터티에 대해 적용된 모든 변경 내용이 반환됩니다. 예를 들어 이전 차등 쿼리 요청을 수행하고 1시간 후 차등 쿼리 요청을 수행한 경우 이 시간 동안 변경된 내용만 반환됩니다. 이 기능은 테넌트 디렉터리 데이터를 응용 프로그램의 데이터 저장소와 동기화할 때 특히 유용합니다.

테넌트의 디렉터리에 대해 차등 쿼리 요청을 수행하려면 테넌트에서 응용 프로그램에 권한을 부여해야 합니다. 자세한 내용은 Getting Started With Azure Active Directory Graph를 참조하십시오.

이 섹션에서는 차등 쿼리 요청에 대해 설명합니다. 모든 요청에는 다음 구성 요소가 필요합니다.

  • 유효한 요청 URI(테넌트의 Graph 끝점 및 적용 가능한 쿼리 문자열 매개 변수 포함)

  • 권한 부여 헤더(Azure AD 액세스 제어 서비스의 유효한 토큰). Graph를 인증하는 방법에 대한 자세한 내용은 Authenticating to Azure AD Graph을 참조하십시오.

차등 쿼리 요청의 URI 형식은 다음과 같습니다(대괄호([ ])는 선택적 요소를 나타냄).

https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]

URI는 키-값 쌍으로 표현된 일련의 쿼리 문자열 매개 변수가 뒤에 오는 계층적 세그먼트로 구성됩니다.

URI: 계층적 세그먼트

세그먼트 설명

<tenantId>

쿼리를 실행할 대상 테넌트의 고유 식별자입니다. 일반적으로 테넌트의 확인된 도메인(verifiedDomains 속성) 중 하나이지만 테넌트의 개체 ID(objectId 속성)일 수도 있습니다. 대/소문자를 구분하지 않습니다.

<resourceSet>

이 쿼리를 실행할 대상 테넌트의 특정 리소스 집합입니다. 쿼리 응답에 반환되는 리소스를 결정합니다. 지원되는 값은 “directoryObjects”, “users”, “contacts” 또는 “groups”입니다. 값은 대/소문자를 구분합니다.

URI: 쿼리 문자열 매개 변수

매개 변수 설명

api-version

요청을 실행할 Graph API의 버전을 지정합니다. 필수 사항입니다. 값은 YYYY-MM-DD 형식의 문자열입니다(예: api-version=2013-04-05).

(미리 보기 버전의 Graph API에서 사용된 x-ms-dirapi-data-contract-version 헤더를 대체합니다.)

deltaLink

마지막 응답의 deltaLink 속성 또는 nextLink 속성에서 반환되는 토큰입니다. 필수 사항이지만 첫 번째 요청에서는 비어 있습니다.

(미리 보기 버전의 Graph API에서 사용된 skipToken 쿼리 문자열 매개 변수를 대체합니다.)

$filter

응답에 포함할 엔터티 유형을 나타냅니다. 선택 사항입니다. 지원되는 엔터티 유형은 사용자, 그룹 및 연락처입니다. <resourceSet>가 “directoryObjects”인 경우에만 유효합니다. 그렇지 않으면 <resourceSet>가 필터를 재정의합니다. 예를 들어 <resourceSet>가 “users”이고 $filter 매개 변수도 지정된 경우 필터 값에 지정된 항목에 상관없이 사용자에 대한 변경 내용만 반환됩니다. <resourceSet>가 “directoryObjects”이고 $filter가 지정되지 않은 경우에는 지원되는 모든 엔터티 유형(사용자, 그룹 및 연락처)에 대한 변경 내용이 반환됩니다.

단일 엔터티 유형을 지정하려면 다음 중 하나를 사용합니다.

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.Contact’)

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.User’)

  • $filter=isof(‘Microsoft.WindowsAzure.ActiveDirectory.Group’)

여러 엔터티 유형을 지정하려면 or 연산자를 사용합니다(예: $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')).

(미리 보기 버전의 Graph API에서 사용된 objectScope 쿼리 문자열 매개 변수를 대체합니다.)

$select

응답에 포함할 속성을 지정합니다. $select를 지정하지 않으면 모든 속성이 포함됩니다.

정규화된 속성 또는 정규화되지 않은 속성을 지정할 수 있습니다. 여러 속성을 쉼표로 구분합니다.

  • 정규화된 속성에는 지정된 엔터티 유형이 있습니다(예: User/displayName). <resourceSet>를 “directoryObjects”로 지정한 경우 정규화된 속성을 사용해야 합니다(예: https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description).

  • 정규화되지 않은 속성에는 지정된 엔터티 유형이 없습니다(예: displayName). <resourceSet>를 “directoryObjects”가 아닌 다른 값으로 지정한 경우에만 사용할 수 있습니다(예: https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle).

note참고
쿼리 문자열의 키-값 쌍은 대/소문자를 구분하지만 순서는 상관없습니다.

가장 간단한 차등 쿼리의 예는 다음과 같습니다. 이는 초기 동기화 중에 사용됩니다.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=

다음은 후속 요청의 예입니다.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U

이 섹션에서는 차등 쿼리 요청이 수행된 경우에 반환되는 차등 쿼리 응답 내용에 대해 설명합니다. 다음 목록에 응답 내용이 나와 있습니다.

  • 각각 특정 사용자, 그룹 또는 연락처 개체에 대한 변경 내용을 포함하는 DirectoryObject 엔터티 0~200개

  • 각각 특정 Member 또는 Manager 링크에 대한 변경 내용을 포함하는 DirectoryLinkChange 엔터티 0~3000개

  • deltaLink 또는 nextLink 속성. 두 속성 모두 해당 값은 대/소문자를 구분하는 URL로 인코딩된 문자열이며, 여기에는 디렉터리에서 발생한 나머지 변경 내용에 대해 클라이언트에 반환된 디렉터리 변경 내용 집합에 대한 상태 정보를 포함합니다. 이 문자열은 다음 차등 쿼리 요청의 deltaLink 쿼리 문자열 매개 변수에 포함해야 합니다.

    • deltaLink 속성이 반환된 경우에는 이 응답 이후에 응용 프로그램에서 동기화할 디렉터리 변경 내용이 더 이상 없습니다. 이 경우 응용 프로그램은 자체 요구 사항에 따라 미리 정해진 시간 동안 대기한 후 다음 차등 쿼리 요청을 실행할 수 있습니다.

    • nextLink 속성이 반환된 경우에는 이 응답 이후에 응용 프로그램에서 동기화할 디렉터리 변경 내용이 남아 있습니다. 이 경우 응용 프로그램은 편리한 가장 빠른 시간에 다음 차등 쿼리 요청을 실행해야 합니다.

응답은 항상 JSON 형식으로 반환됩니다.

다음 목록에는 차등 쿼리를 사용하는 응용 프로그램에 대한 중요한 고려 사항이 나와 있습니다.

  • 차등 쿼리에서 반환되는 변경 내용은 응답 당시의 디렉터리 개체 상태를 나타냅니다. 응용 프로그램은 이러한 변경 내용을 재생을 위한 트랜잭션 로그로 처리해서는 안 됩니다.

  • 변경 내용은 발생한 순서대로 표시됩니다. 가장 최근에 변경된 개체가 마지막에 표시되며, 이는 해당 개체가 여러 번 업데이트된 경우에도 마찬가지입니다. 이 순서는 클라이언트에서 변경 내용을 받은 시점의 영향을 받지 않습니다. 따라서 디렉터리에서 초기에 발생한 방식과 비교하여 순서 없이 변경 내용이 표시될 수 있습니다.

  • 응용 프로그램에서 재생에 대한 준비를 갖춰야 합니다. 재생은 후속 응답에서 동일한 변경 내용이 나타난 경우에 발생합니다. 차등 쿼리는 재생을 줄이기 위해 최선을 다하지만 여전히 재생이 발생할 수 있습니다.

  • 응용 프로그램에서 인식하지 못한 개체의 삭제 변경 내용을 처리할 준비를 갖춰야 합니다.

  • 차등 쿼리는 다른 응답에서 아직 반환되지 않은 원본 또는 대상 개체의 링크를 반환할 수 있습니다.

다음은 초기 차등 쿼리 요청의 예입니다.

GET https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink= HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net

다음은 증분 차등 쿼리 요청의 예입니다.

https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U
 HTTP /1.1
Authorization: Bearer eyJ0eXAiOiJKV . . . KUAe1EQ
Host: graph.windows.net
note참고
두 예제 요청 모두에서 $filter 쿼리 매개 변수는 데모용으로만 표시된 것입니다. 필터에 차등 쿼리의 가능한 모든 대상 유형(사용자, 그룹 및 연락처)이 지정되어 있기 때문에 이 매개 변수를 생략할 수 있으며 쿼리는 기본적으로 이 모든 엔터티 유형에 대한 변경 내용을 반환합니다.

다음 예제 응답은 반환된 JSON을 보여 줍니다.

{
  "odata.metadata": "https://graph.windows.net/contoso.com/$metadata#directoryObjects",


  # This is the deltaLink to be used for the next query
  "aad.deltaLink": "https://graph.windows.net/contoso.com/directoryObjects?deltaLink=XARBN7ivjcS6QIhSZDQR3OkT15SO1eeY-01BZSS0sOct6sh5oEyqOLLKRVhRmBMLHhePUF... [Truncated]",
  "value": [

    # User object for John Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.User",
      "objectType": "User",
      "objectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "accountEnabled": true,
      "displayName": "John Smith",
      "givenName": "John",
      "mailNickname": "johnsmith",
      "passwordPolicies": "None",
      "surname": "Smith",
      "usageLocation": "US",
      "userPrincipalName": "johnsmith@contoso.com"
    },

    # Group object for IT Administrators
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Group",
      "objectType": "Group",
      "objectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "description": "IT Administrators",
      "displayName": "Administrators",
      "mailNickname": "Administrators",
      "mailEnabled": false,
      "securityEnabled": true
    },

    # Contact object for Jane Smith
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.Contact",
      "objectType": "Contact",
      "objectId": "d711a1f8-21cf-4dc0-834a-5583e5324c44",
      "displayName": "Jane Smith",
      "givenName": "Jane",
      "mail": "johnsmith@contoso.com",
      "mailNickname": "johnsmith",
      "proxyAddresses": [
        "SMTP:janesmith@fabrikam.com"
      ],
      "surname": "Smith"
    },

    # Member link indicating John Smith is a member of IT Admin Group
    {
      "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.DirectoryLinkChange",
      "objectType": "DirectoryLinkChange",
      "objectId": "00000000-0000-0000-0000-000000000000",
      "associationType": "Member",
      "sourceObjectId": "7373b0af-d462-406e-ad26-f2bc96d823d8",
      "sourceObjectType": "Group",
      "sourceObjectUri": "https://graph.windows.net/contoso.com/groups/7373b0af-d462-406e-ad26-f2bc96d823d8",
      "targetObjectId": "dca803ab-bf26-4753-bf20-e1c56a9c34e2",
      "targetObjectType": "User",
      "targetObjectUri": "https://graph.windows.net/contoso.com/users/dca803ab-bf26-4753-bf20-e1c56a9c34e2"
    }
  ]
}

참고 항목

표시:
© 2014 Microsoft