차등 쿼리 | Graph API concepts(Graph API 개념)

적용 대상: Graph API | Azure Active Directory

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

테넌트 디렉터리에 대한 차등 쿼리 요청을 하려면 테넌트가 응용 프로그램에 권한을 부여해야 합니다. 자세한 내용은 Azure Active Directory와 응용 프로그램 통합을 참조하십시오.

차등 쿼리 요청

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

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

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

차등 쿼리 요청 URL

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

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

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

URL: 계층적 세그먼트

URL: 쿼리 문자열 매개 변수

참고: 쿼리 문자열의 키-값 쌍은 대/소문자를 구분하지만 순서는 중요하지 않습니다.

아래에는 가장 간단한 차등 쿼리의 예제가 나와 있습니다. 이 쿼리는 초기 동기화 중에 사용됩니다.

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개. 각 엔터티는 특정 User, Group 또는 Contact 개체의 변경 내용을 포함합니다.

• 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

참고: 이 두 샘플 요청에서 $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"
    }
  ]
}

추가 차등 쿼리 기능

차등 쿼리는 이제 업데이트된 속성 및 링크만 반환할 수 있으므로 차등 쿼리 호출의 처리 속도를 높이고 페이로드를 줄일 수 있습니다. 다음 예와 같이 ocp-aad-dq-include-only-changed-properties 헤더를 true로 설정하여 이 옵션을 사용하도록 설정할 수 있습니다.

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= furK18V1T….
HTTP /1.1
ocp-aad-dq-include-only-changed-properties : true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

예를 들어 사용자의 "displayName" 속성만 변경한 경우. 반환된 개체는 다음과 같습니다.

{     
          "displayName" : "AnUpdatedDisplayName",
         "objectId" :  "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
         "objectType" :  "User",
          "odata.type" :  "Microsoft.WindowsAzure.ActiveDirectory.User"
},

"지금"부터 동기화하는 차등 동기화 지원 - 특수 헤더를 지정하여 최신 deltaToken만 가져오도록 요청할 수 있습니다. 이 토큰은 이후 쿼리에서 사용할 수 있으며 "지금"부터 변경된 내용만 반환합니다. 호출의 예는 다음과 같습니다.

GET https://graph.windows.net/contoso.com/users?api-version=2013-11-08&deltaLink= smLYT8V1T…
HTTP /1.1
ocp-aad-dq-include-only-delta-token: true
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5nl0aEV1T….
Response: 200 OK

응답은 deltaLink를 포함하지만 변경된 개체는 포함하지 않으며 다음과 유사합니다.

{   …  "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43......   }

삭제된 항목 검색 – 응답을 사용하여 삭제된 항목도 검색할 수 있습니다. 삭제된 개체와 삭제된 링크는 값이 true로 설정된 "aad.isDeleted" 속성이 나타냅니다. 이는 이전에 만든 개체 및 링크의 삭제에 대해 응용 프로그램이 인식할 수 있도록 하는 데 필요합니다.

추가 리소스

• 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