Table of contents

Rozdílovou dotazu | Rozhraní Graph API konceptyDifferential query | Graph API concepts

Jimaco Brannian|Poslední aktualizace: 19. 6. 2018
|
1 Přispěvatel

Platí pro: Graph API | Azure Active DirectoryApplies to: Graph API | Azure Active Directory

Toto téma popisuje funkci rozdílové dotazu Azure AD Graph API.This topic discusses the differential query feature of Azure AD Graph API.Žádost o rozdílové dotaz vrátí všechny změny provedené na zadané entity v době mezi dva po sobě jdoucí požadavky.A differential query request returns all changes made to specified entities during the time between two consecutive requests.Například pokud provedete rozdílové dotazu žádosti o jednu hodinu po předchozí požadavek rozdílové dotazu, bude vrácen pouze změny provedené danou dobu.For example, if you make a differential query request an hour after the previous differential query request, only the changes made during that hour will be returned.Tato funkce je obzvláště užitečná při ukládání synchronizace dat adresáře klienta s dat aplikace.This functionality is especially useful when synchronizing tenant directory data with an application’s data store.

Vytvořte žádost na rozdílové dotazu do adresáře klienta, aplikace musí být autorizován klientem.To make a differential query request to a tenant’s directory, your application must be authorized by the tenant.Další informace najdete v tématu integrace aplikací s Azure Active Directory.For more information, see Integrating Applications with Azure Active Directory.

Důležité

Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.

Požadavky na rozdílové dotaz Differential query requests

Tato část popisuje požadavky na rozdílové dotaz.This section describes differential query requests.Všechny požadavky vyžadují následující součásti:All requests require the following components:

  • Platný adrese URL požadavku, včetně grafu koncový bod pro klienta a parametrů řetězce dotazu použít.A valid request URL, including the Graph endpoint for the tenant and applicable query string parameters.

  • Hlavičku autorizace včetně platný přístup tokenem vydaným službou Azure Active Directory.An authorization header, including a valid access token issued by Azure Active Directory.Další informace týkající se ověřování pro rozhraní Graph API najdete v tématu scénáře ověřování pro Azure AD.For more information on authenticating to the Graph API, see Authentication Scenarios for Azure AD.

Adresa URL požadavku rozdílové dotazuDifferential query request URL

Následující obrázek znázorňuje formát adresy URL pro rozdílové dotazu požadavek; hranaté závorky [] znamenat volitelné elementy.The following shows the format of the URL for differential query request; square brackets [] indicate optional elements.

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

Adresa URL je tvořena hierarchické segmenty, za nímž následuje řadu parametrů řetězce dotazu, vyjádřené jako páry klíč hodnota.The URL is made up of a hierarchical segments followed by a series of query string parameters expressed as key-value pairs.

Adres URL: Hierarchická segmentyURL: Hierarchical segments

SegmentSegmentPopisDescription
TenantIdtenantIdJedinečný identifikátor klienta, který je třeba spustit dotaz na.The unique identifier of the tenant that the query should be executed against.To se obvykle označuje ověřených domén (verifiedDomains vlastnost) klienta, ale také může být ID objektu klienta (objectId vlastnost).This is typically one of the verified domains (verifiedDomains property) of the tenant, but it can also be the tenant’s object ID (objectId property).Není malá a velká písmena.Not case-sensitive.
resourceSetresourceSetKonkrétní sadu prostředků klienta, které tento dotaz, je třeba spustit na.The specific set of tenant resources this query should be executed against.Určuje, jaké prostředky jsou vráceny v odpovědi na dotaz.Determines what resources are returned in the query response.Podporovány jsou tyto hodnoty: "directoryObjects", "uživatelé", "kontakty" nebo "skupiny".Supported values are: “directoryObjects”, “users”, “contacts” or “groups”.Hodnoty jsou malá a velká písmena.Values are case-sensitive.

Adresa URL: Parametrů řetězce dotazuURL: Query string parameters

ParametrParameterPopisDescription
verze-apiapi-versionUrčuje verzi rozhraní Graph API, vůči které se objeví požadavek.Specifies the version of the Graph API against which the request is issued.Vyžaduje se.Required.Od verze 1.5, hodnota je vyjádřena jako číslo verze číselné; například rozhraní api-version = 1.5.Beginning with version 1.5, the value is expressed as a numeric version number; for example, api-version=1.5.U předchozích verzí hodnota je řetězec ve formátu RRRR-MM-DD; například rozhraní api-version = 2013-04-05.For previous versions, the value is a string of the form YYYY-MM-DD; for example, api-version=2013-04-05.

(Nahrazuje použití x-ms-dirapi-data-contract-version záhlaví v verzi preview rozhraní Graph API.)(Replaces the use of x-ms-dirapi-data-contract-version header in the preview version of Graph API.)
deltaLinkdeltaLinkToken vrátil buď deltaLink vlastnost nebo nextLink vlastnost v poslední odpovědi.The token returned in either the deltaLink property or the nextLink property in the last response.Vyžaduje, ale bude prázdný na první požadavek.Required, but will be empty on the first request.

(Nahrazuje skipToken parametr řetězce ve verzi preview rozhraní Graph API dotazu.)(Replaces the skipToken query string parameter in the preview version of Graph API.)
$filter$filterUrčuje, jaké typy entit by měl být zahrnuty v odpovědi.Indicates which entity types should be included in the response.Volitelný parametr.Optional.Typy podporované entity: uživatelů, skupiny a kontakt.The supported entity types are: User, Group and Contact.Pouze v případě platný & ltresourceSet & gt je "directoryObjects"; v opačném & ltresourceSet & gt přepsání filtru.Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.Například pokud & ltresourceSet & gt je "uživatelé" a $filter rovněž je zadán parametr, pouze změny pro uživatele, bude vrácen bez ohledu na to, co je zadaný v poli Hodnota filtru.For example, if &ltresourceSet&gt is “users”, and the $filter parameter is also specified, only changes for users will be returned regardless of what is specified in the filter value.Pokud & ltresourceSet & gt je "directoryObjects" a $filter není zadaný, jsou vráceny změny pro všechny typy podporovaných entit (uživatelů, skupiny a obraťte se na).If &ltresourceSet&gt is “directoryObjects” and $filter is not specified, changes for all of the supported entity types (User, Group, and Contact) are returned.

Zadejte typ jedné entity, použijte jednu z následujících akcí:To specify a single entity type, use one of the following:
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')
  • $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Group')
Chcete-li zadat více typy entit, použijte nebo operátor, například $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').To specify multiple entity types, use the or operator; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.User')%20or%20isof('Microsoft.WindowsAzure.ActiveDirectory.Group').

(Nahrazuje objectScope parametr řetězce ve verzi preview rozhraní Graph API dotazu.)(Replaces the objectScope query string parameter in the preview version of Graph API.)

Důležité od verze 1.5, rozhraní Graph API obor názvů se změní z Microsoft.WindowsAzure.ActiveDirectory na Microsoft.DirectoryServices.Important Beginning with version 1.5, the Graph API namespace is changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices.Dřívějších verzích rozhraní Graph API nadále používat předchozí obor názvů; například $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').Earlier versions of the Graph API continue to use the previous namespace; for example, $filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact').
$select$selectUrčuje vlastnosti, které by měly být zahrnuty v odpovědi.Specifies which properties should be included in the response.Pokud * $select ^ není zadán, jsou zahrnuty všechny vlastnosti.If *$select^ is not specified, all properties are included.

Vlastnosti mohou být zadané buď plně kvalifikovaný nebo nekvalifikovaným.Properties can be specified either fully qualified or non-qualified.Více vlastností jsou odděleny čárkami.Multiple properties are delimited by commas.
  • Plně kvalifikovaný vlastnosti mají zadaný; typ entity například User/displayName.Fully qualified properties have the entity type specified; for example, User/displayName.Plně kvalifikovaný vlastnosti musíte použít, pokud & ltresourceSet & gt je zadán jako "directoryObjects"; například https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.Fully qualified properties MUST be used if &ltresourceSet&gt is specified as “directoryObjects”; for example, https://graph.windows.net/contoso.com/directoryObjects?api-version=2013-04-05&deltaLink=&$select=User/displayName,Group/description.
  • Kvalifikovaný bez vlastnosti nemají zadaný; typ entity například displayName.Non-qualified properties do not have the entity type specified; for example, displayName.Je pouze lze použít při & ltresourceSet & gt je zadán jako jiná hodnota než "directoryObjects"; například https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.They can only be used when &ltresourceSet&gt is specified as a value other than “directoryObjects”; for example, https://graph.windows.net/contoso.com/users?api-version=2013-04-05&deltaLink=&$select=displayName,jobTitle.

Poznámka:: rozlišují malá a páry klíč hodnota v řetězci dotazu, ale jejich pořadí není důležité.Note: The key-value pairs in the query string are case-sensitive, but their order is not significant.

Následuje příklad nejjednodušší rozdílové dotazu.The following is an example of the simplest differential query.To se používá při počáteční synchronizaci.This is used during initial sync.

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

Následuje příklad následného požadavku.The following is an example of a subsequent request.

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

Odpovědi na dotazy rozdílové Differential query responses

Tato část popisuje obsah rozdílové dotazu odpovědi, která je vrácena, pokud rozdílová dotazu požadavku.This section describes the contents of a differential query response that is returned when a differential query request is made.Následující seznam popisuje obsah odpovědi:The following list describes the contents of a response:

  • Nula na 200 DirectoryObject entity, z nichž každý obsahuje změny pro konkrétní uživatele, skupiny, nebo kontaktujte objektu.Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • Nula na 3000 DirectoryLinkChange entity, z nichž každý obsahuje změny pro konkrétní člen nebo manager odkaz.Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • Buď deltaLink nebo nextLink vlastnost.Either a deltaLink or a nextLink property.V obou případech je jeho hodnota malá a velká písmena, kódovaná adresou URL řetězec, který se vloží informace o sadu změn adresáře, které byl vrácen do klienta, s ohledem na ostatní změny, ke kterým došlo v adresáři stavu.In either case, its value is a case-sensitive, URL-encoded string that embeds state information about the set of directory changes that have been returned to the client, with respect to remaining changes that have occurred in the directory.Tento řetězec (nebo token) by měl být součástí deltaLink parametr řetězce v další rozdílové dotazu požadavku dotazu.This string (or token) should be included in the deltaLink query string parameter in the next differential query request.

    • Pokud deltaLink je vrácena vlastnost, neexistují žádné další změny adresáře zbývajících pro aplikaci pro synchronizaci po této odpovědi.If the deltaLink property is returned, there are no more directory changes left for the application to synchronize after this response.Aplikace můžete Počkejte chvíli předem určený podle vlastní požadavky na vydání další rozdílové dotazu požadavku.The application can wait for some predetermined time according to its own requirements to issue the next differential query request.

    • Pokud nextLink je vrácena vlastnost, jsou změny adresáře zbývající pro aplikaci pro synchronizaci po této odpovědi.If the nextLink property is returned, there are directory changes remaining for the application to synchronize after this response.Aplikace by měla vydání další rozdílové dotazu požadavku na jeho nejdřívější pohodlí.The application should issue the next differential query request at its earliest convenience.

Vždy jsou odpovědi vrácené ve formátu JSON.Responses are always returned in JSON format.

Informace týkající se použití rozdílové dotazu Considerations when using differential query

V následujícím seznamu jsou uvedeny důležité informace pro aplikace, které používají rozdílové dotazu:The following list highlights important considerations for applications that use differential query:

  • Vrácené dotazem rozdílové změny reprezentovat stav objektů adresáře v době odezvy.Changes returned by differential query represent the state of the directory objects at the time of the response.Vaše aplikace nesmí tyto změny považovat protokoly transakcí pro opakování.Your application must not treat these changes as transaction logs for replay.

  • Změny se v pořadí, ve kterém k nim došlo.Changes appear in the order in which they occurred.Naposledy změněné objekty se zobrazí poslední i v případě, že objekt byl aktualizován vícekrát.The most-recently changed objects appear last even if the object was updated multiple times.Jejich pořadí nemá vliv také při klienta přijetí změn.Their order is also not affected by when the client received the changes.V důsledku toho je možné pro změny předkládané mimo pořadí, ve srovnání s jak k nim původně došlo v adresáři.As a result, it is possible for changes to be presented out of order compared to how they initially occurred in the directory.

  • Aplikace musí být připravené opětovná přehrání, ke kterým dochází, když se zobrazí stejné změny v odpovědi na následné.Your application must be prepared for replays, which occur when the same change appears in subsequent responses.Při rozdílové dotaz provede usilovně ke snížení opětovná přehrání, jsou stále možné.While differential query makes a best effort to reduce replays, they are still possible.

  • Aplikace musí být připraveny se zpracovat změnu odstranění pro objekt, který nebyl vědět.Your application must be prepared to handle a deletion change for an object it was not aware of.

  • Rozdílovou dotaz může vrátit odkaz na objekt zdroje nebo cíle, které ještě nebyly vráceny pomocí jiné reakce.Differential query can return a link to a source or target object that has not yet been returned by other responses.

  • Najdete v článku funkce další rozdílové dotazů části níže Další informace o používání hlaviček požadavku omezit své dotazy ke zlepšení výkonu.See the Additional differential query features section below for more information on using request headers to constrain your queries to improve performance.

Příklady žádosti a odpovědi Request and response examples

Následuje příklad požadavku počáteční rozdílové dotazu:The following is an example of an initial differential query request:

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

Následuje příklad požadavku přírůstkové rozdílové dotazu:The following is an example of an incremental differential query request:

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

Poznámka:: V obou tyto ukázkové požadavky $filter parametr dotazu se zobrazí pouze pro demonstrační účely.Note: In both of these sample requests, the $filter query parameter is shown for demonstration purposes only.Vzhledem k tomu, že filtr určuje všechny typy možný cíl pro rozdílové dotaz (uživatele, skupiny a obraťte se na), může být vynechán a dotaz by vrátit změny všech těchto typů entit ve výchozím nastavení.Because the filter specifies all of the possible target types for the differential query (User, Group, and Contact), it could be omitted and the query would return changes for all of these entity types by default.

Odpověď na následující příklad ukazuje vrácený JSON:The following example response demonstrates the returned 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"
    }
  ]
}

Funkce další rozdílové dotazů Additional differential query features

Rozdílovou dotazy mohou vracet nyní pouze aktualizované vlastnosti a odkazy – to umožňuje rychlejší zpracování a menší datové části pro volání rozdílové dotazu.Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls.Tato možnost je povolená nastavením záhlaví ocp-aad-dq-include-only-changed-properties na hodnotu true, jak je znázorněno v tomto příkladu.This option is enabled by setting the header ocp-aad-dq-include-only-changed-properties to true as shown in this example.

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

Například pokud pouze vlastnost "displayName" uživatele byla změněna.For example if only the “displayName” property of user has changed.Vráceného objektu by měl podobat tomuto:The returned object would be similar to this:

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

Rozdílová synchronizace podpory na synchronizaci z "teď" -lze zadat speciální záhlaví, vyžaduje pouze get aktuální deltaToken, tento token lze použít v následujících dotazech, které vrátí pouze změny provedené z "teď".Differential Sync support to sync from “now” - a special header can be specified, requesting to only get an up-to-date deltaToken, this token can be used in subsequent queries, which will return only changes from “now”.Tady je příklad volání:Here’s the example call:

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

Odpověď bude obsahovat deltaLink, ale nebude mít změněné objekty, podobně jako tento:The response will contain the deltaLink, but will not have the changed object(s), similar to this:

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

Zjišťování odstraněné položky – odpovědi lze také použít ke zjištění odstraněné položky.Detecting a deleted item – the response can also be used to detect a deleted item.Odstraněné objekty a odstraněných odkazy jsou označeny "aad.isDeleted" vlastnost s hodnotu nastavenou na hodnotu true; To je nezbytné, abyste měli jistotu, že aplikace můžete další informace o odstranění dříve vytvořené objekty a odkazy.Deleted objects and deleted links are indicated by the "aad.isDeleted" property with a value set to true; this is necessary to make sure applications can learn about the deletion of previously created objects and links.

Další zdroje informací Additional resources

© 2018 Microsoft