Zapytanie różnicowej | Pojęcia dotyczące interfejsu API programu Graph
Dotyczy: interfejsu API programu Graph | Usługa Azure Active Directory
W tym temacie omówiono funkcję różnicowej zapytania interfejsu API Azure AD Graph. Żądanie kwerendy różnicowej zwraca wszystkie zmiany wprowadzone do określonej jednostki w czasie od dwóch kolejnych żądań. Na przykład jeśli wprowadzisz różnicowej zapytania żądania godziny po poprzednie żądanie różnicowej zapytania zostanie zwrócony tylko zmiany wprowadzone w ciągu tej godziny. Ta funkcja jest szczególnie przydatna podczas przechowywania synchronizacji danych katalog dzierżawy z danymi aplikacji.
Aby różnicowa żądania do katalogu dzierżawcy, aplikacja musi być autoryzowany przez dzierżawcę. Aby uzyskać więcej informacji, zobacz integracji aplikacji z usługą Azure Active Directory.
Ważne
Zdecydowanie zaleca się używanie Microsoft Graph zamiast interfejsu API Azure AD Graph dostęp do zasobów usługi Azure Active Directory. Nasze programistycznych teraz jest skoncentrowana na program Microsoft Graph i interfejsu API usługi Azure AD Graph planowane żadne rozszerzenia funkcjonalności. Istnieje bardzo ograniczoną liczbę scenariuszy, w których interfejsu API usługi Azure AD Graph nadal może być odpowiednie; Aby uzyskać więcej informacji, zobacz Microsoft Graph lub Azure AD Graph wpis w blogu w Centrum deweloperów pakietu Office.
Żądania zapytań różnicowej
W tej sekcji opisano różnicowej zapytania żądania. Wszystkie żądania wymagają następujących składników:
Prawidłowy adres URL żądania, tym wykres punktu końcowego dzierżawcy i parametrów ciągu zapytania zastosowania.
Nagłówek autoryzacji, w tym dostęp token wystawiony przez usługę Azure Active Directory. Aby uzyskać więcej informacji na temat uwierzytelniania do interfejsu API programu Graph, zobacz scenariusze uwierzytelniania dla usługi Azure AD.
Adres URL żądania różnicowej zapytania
Poniżej przedstawiono format adresu URL dla żądania zapytania różnicowej; nawiasy kwadratowe [] wskazują opcjonalne elementy.
https://graph.windows.net/<tenantId>/<resourceSet>?api-version=<SupportedApiVersion>&deltaLink=<token>&[$filter=isof(<entityType>)]&[$select=<PropertyList>]
Adres URL składa się z segmentów hierarchiczne, następuje szereg wyrażonej w postaci pary klucz wartość parametrów ciągu zapytania.
Adresu URL: Hierarchiczna segmenty
| Segment | Opis |
|---|---|
| Dla identyfikatora dzierżawcy | Unikatowy identyfikator dzierżawy, który należy wykonać zapytanie względem. Zwykle to zweryfikowanych domen (verifiedDomains właściwości) dzierżawy, ale można też obiektu dzierżawcy o identyfikatorze (objectId właściwości). Bez uwzględniania wielkości liter. |
| resourceSet | Określony zbiór tego zapytania mają zostać wykonane przed zasoby dzierżawcy. Określa, jakie zasoby są zwracane w odpowiedzi na kwerendę. Obsługiwane są następujące wartości: "directoryObjects", "Użytkownicy", "Kontakty" lub "grupy". Wartości jest rozróżniana wielkość liter. |
Adres URL: Parametry ciągu zapytania
| Parametr | Opis |
|---|---|
| api-version | Określa wersję interfejsu API programu Graph, względem którego wygenerowania żądania. Wymagane. Począwszy od wersji 1.5, wartość jest wyrażona jako numer wersji liczbowych; na przykład interfejsu api-version = 1.5. W poprzednich wersjach wartość jest ciągiem w postaci RRRR-MM-DD; na przykład interfejsu api-version = 2013-04-05. (Zastępuje użycia x-ms-dirapi-data-contract-version nagłówka w wersji zapoznawczej interfejsu API programu Graph.) |
| deltaLink | Token zwracany albo deltaLink właściwości lub nextLink właściwości w ostatniej odpowiedzi. Wymagane, ale będzie pusty na pierwsze żądanie. (Zastępuje skipToken parametr ciągu w wersji zapoznawczej interfejsu API programu Graph zapytania.) |
| $filter | Wskazuje, typy jednostek, które powinny być uwzględnione w odpowiedzi. Opcjonalny. Jednostki obsługiwane typy: użytkownika, grupy i danych kontaktowych. Tylko prawidłowe w przypadku & ltresourceSet & gt jest "directoryObjects"; w przeciwnym razie & ltresourceSet & gt zastąpienia filtra. Na przykład jeśli & ltresourceSet & gt jest "Użytkownicy", a $filter podano także parametr, tylko zmiany dla użytkowników, zostaną zwrócone niezależnie od tego, co jest określony w wartości filtru. Jeśli & ltresourceSet & gt jest "directoryObjects" i $filter jest nie jest określony, zmiany dla wszystkich typów obsługiwanych jednostek (użytkowników, grupy i danych kontaktowych) są zwracane. Aby określić typ pojedynczej jednostki, użyj jednej z następujących czynności:
$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group'). (Zastępuje objectScope parametr ciągu w wersji zapoznawczej interfejsu API programu Graph zapytania.) Ważne począwszy od wersji 1.5, interfejsu API programu Graph przestrzeń nazw została zmieniona z Microsoft.WindowsAzure.ActiveDirectory na Microsoft.DirectoryServices. Wcześniejszych wersji interfejsu API programu Graph w dalszym ciągu używać poprzedniej przestrzeni nazw; na przykład $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact'). |
| $select | Określa właściwości, które powinny być uwzględnione w odpowiedzi. Jeśli * $select ^ nie zostanie określona, wszystkie właściwości są uwzględniane. Właściwości mogą być określone w pełni kwalifikowaną albo nie jest kwalifikowana. Wiele właściwości są rozdzielone przecinkami.
|
Uwaga: pary klucz wartość w ciągu zapytania jest rozróżniana wielkość liter, ale ich kolejność nie jest znacząca.
Oto przykład najprostszym różnicowej kwerendy. Jest on używany podczas synchronizacji początkowej.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=
Oto przykład kolejnego żądania.
https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=AAABAGCL8z4m%2bc9IJGIzYjFmYzU5LTg0YjgtNDQwMC1hNzE1LWVhOGE3ZTQwZjRmZQBuvX43ACZQT4LRVPug8An6AAABAANIABAfGgAQwAMAJDCHA5AAABAATCkAA44TADQnhAQAIAAAgAHAAwAQAAAA8rLSTyfq5U`
Odpowiedzi na kwerendy różnicowej
W tej sekcji opisano zawartości odpowiedzi różnicowej zapytania, która jest zwracany, gdy zapytania różnicową żądań. Poniższa lista zawiera opis zawartości odpowiedzi:
Zero 200 DirectoryObject jednostek, z których każdy zawiera zmiany dla określonego użytkownika, grupy, lub skontaktuj się z obiektu.
Zero, aby 3000 DirectoryLinkChange jednostek, z których każdy zawiera zmiany dla określonego elementu członkowskiego lub Menedżera łącza.
Albo deltaLink lub nextLink właściwości. W obu przypadkach jego wartość jest ciągiem z uwzględnieniem wielkości liter, zakodowane w adresie URL, który osadza informacje o zestawie zmiany katalogu, które zostały zwrócone do klienta, w odniesieniu do pozostałych zmian, które wystąpiły w katalogu. Ten ciąg (lub tokenu) powinny być uwzględnione w deltaLink parametr ciągu w następnym żądaniu zapytania różnicowej zapytania.
Jeśli deltaLink zwracana jest właściwość, nie ma żadnych więcej zmian katalog dla aplikacji, które synchronizuje się po tej odpowiedzi. Aplikacja może Poczekaj chwilę ustalonej zgodnie z wymaganiami własną wydania przy następnym żądaniu różnicowej zapytania.
Jeśli nextLink zwracana jest właściwość, istnieją zmiany katalogu pozostałych aplikacji synchronizuje się po tej odpowiedzi. Aplikacja powinien wystawiać następnym żądaniu zapytania różnicowej jego najwcześniejszą wygodne.
Odpowiedzi są zawsze zwracane w formacie JSON.
Uwagi dotyczące korzystania z różnicowej zapytania
Poniższa lista wyróżnione istotnych kwestii dotyczących aplikacji, które używają różnicowej zapytania:
Zmiany zwróconych przez zapytanie różnicowej reprezentuje stan obiektów katalogu w czasie odpowiedzi. Aplikacji nie należy traktować te zmiany jako dzienniki transakcji powtarzania.
Zmiany są wyświetlane w kolejności, w której miały miejsce. Ostatnio zmienionych obiektów ostatnio wyświetlane nawet, jeśli obiekt został zaktualizowany wiele razy. Ich kolejność również nie ma wpływu na klienta odbiorze zmiany. W związku z tym istnieje możliwość zmiany będą widoczne poza kolejnością w porównaniu do ich początkowo przyczyny w katalogu.
Odtworzenie, które występują, gdy te same zmiany pojawia się w kolejnych odpowiedzi, należy przygotować aplikacji. Gdy zapytanie różnicowej sprawia, że starań, aby zmniejszyć odtworzenie, są one nadal możliwe.
Aplikacji muszą być przygotowane do obsługi zmiany usunięcia dla obiektu, który nie był znane.
Różnicowa zapytanie może zwrócić łącze do obiektu źródłowa lub docelowa nie została jeszcze zwrócona przez inne odpowiedzi.
Zobacz funkcje dodatkowe zapytania różnicowej sekcji poniżej, aby uzyskać więcej informacji przy użyciu nagłówków żądań, aby ograniczyć zapytań do zwiększenia wydajności.
Przykładowe żądanie i odpowiedź
Poniżej przedstawiono przykład żądania początkowego różnicowej zapytania:
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
Poniżej przedstawiono przykład żądanie przyrostowe różnicowej zapytania:
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
Uwaga: W obu tych żądań próbki $filter parametru zapytania jest wyświetlany tylko w celach demonstracyjnych. Ponieważ filtr Określa wszystkie typy możliwy element docelowy dla zapytania różnicowa (użytkowników, grup i skontaktuj się z), można pominąć i kwerendy zwróci domyślnie zmian dla typu jednostki.
Następujący przykład odpowiedzi zademonstrowano zwrócony 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"
}
]
}
Funkcje dodatkowe różnicowej zapytania
Różnicowa zapytania teraz mogą zwracać tylko właściwości aktualizowane i linki — dzięki temu szybsze przetwarzanie i zmniejszenie ładunków dla wywołań różnicowej zapytania. Ta opcja jest włączona, ustawiając nagłówka ocp-aad-dq-include-only-changed-properties na true, jak pokazano w poniższym przykładzie.
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
Na przykład jeśli tylko właściwość "displayName" użytkownika został zmieniony. Zwrócony obiekt będzie podobny do poniższego:
{
"displayName" : "AnUpdatedDisplayName",
"objectId" : "c1bf5c59-7974-4aff-a59a-f8dfe9809b18",
"objectType" : "User",
"odata.type" : "Microsoft.WindowsAzure.ActiveDirectory.User"
},
Różnicowa Obsługa synchronizacji do synchronizowania z "teraz" — można określić specjalne nagłówka, żądanie GET tylko aktualne deltaToken ten token mogą być używane w kolejnych zapytania, który będzie zwracać tylko zmiany z "teraz". Oto przykład wywołania:
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
Odpowiedź zawiera deltaLink, ale nie będą miały zmienione obiekty podobny do poniższego:
{ … "aad.deltaLink":https://graph.windows.net/contoso.com/users?deltaLink=MRa43...... }
Wykrywanie usuniętego elementu — odpowiedzi mogą również służyć do wykrywania usuniętego elementu. Usunięte obiekty i linki usuniętego są oznaczone za pomocą właściwości "aad.isDeleted" z ustawioną wartość true; jest to niezbędne do upewnij się, że aplikacje dowiedzieć się o usunięcie utworzonej wcześniej obiektów i łączy.