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

Azure AD Graph API 차등 쿼리

업데이트 날짜: 2014년 10월

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

테넌트 디렉터리에 대한 차등 쿼리 요청을 하려면 테넌트가 응용 프로그램에 권한을 부여해야 합니다. 자세한 내용은 응용 프로그램 추가, 업데이트 및 제거를 참조하세요.

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

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

  • Azure Active Directory에서 발급한 유효한 액세스 토큰이 포함된 인증 헤더. Graph API에 인증하는 방법에 대한 자세한 내용은 Azure AD의 인증 시나리오를 참조하세요.

아래에는 차등 쿼리 요청의 URL 형식이 나와 있습니다. 대괄호 [] 안의 항목은 선택적 요소를 나타냅니다.

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

URL은 계층적 세그먼트 뒤에 키-값 쌍으로 표시되는 일련의 쿼리 문자열 매개 변수가 붙는 형식으로 구성됩니다.

URL: 계층적 세그먼트

세그먼트 설명

<tenantId>

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

<resourceSet>

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

URL: 쿼리 문자열 매개 변수

매개 변수 설명

api-version

요청 실행 대상 Graph API의 버전을 지정하는 필수 매개 변수입니다. 버전 1.5부터는 api-version=1.5와 같이 값이 숫자 버전 번호로 표시됩니다. 이전 버전에서는 값이 api-version=2013-04-05와 같은 YYYY-MM-DD 형식의 문자열이었습니다.

미리 보기 버전 Graph API의 x-ms-dirapi-data-contract-version 헤더 대신 사용됩니다.

deltaLink

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

미리 보기 버전 Graph API의 skipToken 쿼리 문자열 매개 변수 대신 사용됩니다.

$filter

응답에 포함할 엔터티 형식을 나타내는 선택적 매개 변수입니다.

지원되는 엔터티 형식은 User, Group 및 Contact입니다. <resourceSet>가 "directoryObjects"일 때만 유효하며 그 외의 경우에는 <resourceSet>가 필터를 재정의합니다. 예를 들어 <resourceSet>가 "users"인데 $filter 매개 변수도 지정하면 필터 값에 지정된 내용과는 관계없이 사용자에 대한 변경 내용만 반환됩니다. <resourceSet>가 "directoryObjects"인데 $filter를 지정하지 않으면 지원되는 모든 엔터티 형식(User, Group, Contact)에 대한 변경 내용이 반환됩니다.

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

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

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

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

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

미리 보기 버전 Graph API의 objectScope 쿼리 문자열 매개 변수 대신 사용됩니다.

Important중요
버전 1.5부터는 Graph API 네임스페이스가 Microsoft.WindowsAzure.ActiveDirectory에서 Microsoft.DirectoryServices로 변경되었습니다. 이전 버전의 Graph API에서는 $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')와 같이 이전 네임스페이스가 계속 사용됩니다.

$select

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

속성은 정규화하거나 정규화하지 않도록 지정할 수 있습니다. 속성을 여러 개 포함하려면 쉼표로 구분합니다.

  • 정규화된 속성의 경우 User/displayName과 같이 엔터티 형식이 지정됩니다. https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description과 같이 <resourceSet>를 "directoryObjects"로 지정하는 경우에는 정규화된 속성을 사용해야 합니다.

  • 정규화되지 않은 속성의 경우 displayName과 같이 엔터티 형식이 지정되지 않습니다. https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle과 같이 <resourceSet>를 "directoryObjects" 이외의 값으로 지정하는 경우에만 이러한 속성을 사용할 수 있습니다.

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개. 각 엔터티는 특정 사용자, 그룹 또는 연락처 개체의 변경 내용을 포함합니다.

  • DirectoryLinkChange 엔터티 0~3,000개. 각 엔터티는 특정 Member 또는 Manager 링크의 변경 내용을 포함합니다.

  • 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 쿼리 매개 변수는 데모용으로만 표시됩니다. 이 필터는 차등 쿼리에 사용 가능한 모든 대상 유형(User, Group, Contact)을 지정하므로 생략할 수 있으며, 쿼리는 기본적으로 이러한 모든 엔터티 형식에 대한 변경 내용을 반환합니다.

다음 예제 응답은 반환된 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