Table of contents

Query differenziale | Concetti relativi all'API GraphDifferential query | Graph API concepts

Jimaco Brannian|Ultimo aggiornamento: 19/06/2018
|
2 Collaboratori

Si applica a: API Graph | Azure Active DirectoryApplies to: Graph API | Azure Active Directory

Questo argomento illustra la funzionalità di query differenziale dell'API di Azure AD Graph.This topic discusses the differential query feature of Azure AD Graph API.Una richiesta di query differenziale restituisce tutte le modifiche apportate alle entità specificate nel tempo intercorso tra due richieste consecutive.A differential query request returns all changes made to specified entities during the time between two consecutive requests.Se ad esempio si esegue una richiesta di query differenziale un'ora dopo la richiesta precedente, verranno restituite solo le modifiche apportate durante quell'ora.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.Questa funzionalità è particolarmente utile durante la sincronizzazione dei dati della directory di un tenant con l'archivio dati di un'applicazione.This functionality is especially useful when synchronizing tenant directory data with an application’s data store.

Per eseguire una richiesta di query differenziale alla directory di un tenant, l'applicazione deve essere autorizzata dal tenant.To make a differential query request to a tenant’s directory, your application must be authorized by the tenant.Per altre informazioni, vedere Integrazione di applicazioni con Azure Active Directory.For more information, see Integrating Applications with Azure Active Directory.

Importante

Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph.We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources.Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph.Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API.Può essere ancora opportuno usare questa API in un numero molto limitato di scenari. Per altre informazioni, vedere il post di blog Microsoft Graph or the Azure AD Graph (Microsoft Graph o Azure AD Graph) in Office Developer 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.

Richieste di query differenziale Differential query requests

Questa sezione descrive le richieste di query differenziale.This section describes differential query requests.Per tutte le richieste sono necessari i componenti seguenti:All requests require the following components:

  • Un URL della richiesta valido, che includa l'endpoint Graph per il tenant e i parametri applicabili della stringa di query.A valid request URL, including the Graph endpoint for the tenant and applicable query string parameters.

  • Un'intestazione di autorizzazione, tra cui un token di accesso valido rilasciato da Azure Active Directory.An authorization header, including a valid access token issued by Azure Active Directory.Per altre informazioni sull'autenticazione all'API Graph, vedere Scenari di autenticazione per Azure AD.For more information on authenticating to the Graph API, see Authentication Scenarios for Azure AD.

URL della richiesta di query differenzialeDifferential query request URL

Di seguito viene illustrato il formato dell'URL per la richiesta di query differenziale. Le parentesi quadre [] indicano elementi facoltativi.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>]

L'URL è costituito da segmenti gerarchici seguiti da una serie di parametri della stringa di query espressi come coppie chiave-valore.The URL is made up of a hierarchical segments followed by a series of query string parameters expressed as key-value pairs.

URL: segmenti gerarchiciURL: Hierarchical segments

SegmentoSegmentDescrizioneDescription
tenantIdtenantIdIdentificatore univoco del tenant nel quale deve essere eseguita la query.The unique identifier of the tenant that the query should be executed against.In genere è uno dei domini verificati (proprietà verifiedDomains) del tenant, ma può anche essere l'ID oggetto del tenant (proprietà objectId).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).Non fa distinzione tra maiuscole e minuscole.Not case-sensitive.
resourceSetresourceSetSet specifico di risorse del tenant nel quale deve essere eseguita la query.The specific set of tenant resources this query should be executed against.Determina quali risorse vengono restituite nella risposta alla query.Determines what resources are returned in the query response.I valori supportati sono: "directoryObjects", "users", "contacts" o "groups".Supported values are: “directoryObjects”, “users”, “contacts” or “groups”.Per i valori viene fatta distinzione tra maiuscole e minuscole.Values are case-sensitive.

URL: parametri delle stringhe di queryURL: Query string parameters

ParametroParameterDescrizioneDescription
api-versionapi-versionSpecifica la versione dell'API Graph per cui è stata inviata la richiesta.Specifies the version of the Graph API against which the request is issued.Obbligatorio.Required.A partire dalla versione 1.5, il valore è espresso come numero di versione in formato numerico, ad esempio api-version=1.5.Beginning with version 1.5, the value is expressed as a numeric version number; for example, api-version=1.5.Per le versioni precedenti, il valore è una stringa in formato AAAA-MM-GG, ad esempio, 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.

Sostituisce l'uso dell'intestazione x-ms-dirapi-data-contract-version nella versione di anteprima dell'API Graph.(Replaces the use of x-ms-dirapi-data-contract-version header in the preview version of Graph API.)
deltaLinkdeltaLinkToken restituito nella proprietà deltaLink o nella proprietà nextLink nell'ultima risposta.The token returned in either the deltaLink property or the nextLink property in the last response.Obbligatorio, ma sarà vuoto nella prima richiesta.Required, but will be empty on the first request.

Sostituisce il parametro della stringa di query skipToken nella versione di anteprima dell'API Graph.(Replaces the skipToken query string parameter in the preview version of Graph API.)
$filter$filterIndica i tipi di entità da includere nella risposta.Indicates which entity types should be included in the response.Facoltativo.Optional.I tipi di entità supportati sono: User, Group e Contact.The supported entity types are: User, Group and Contact.Valido solo quando il segmento &ltresourceSet&gt è "directoryObjects"; in caso contrario, &ltresourceSet&gt esegue l'override del filtro.Only valid when &ltresourceSet&gt is “directoryObjects”; otherwise, &ltresourceSet&gt overrides the filter.Se ad esempio il segmento &ltresourceSet&gt è "users" ed è specificato anche il parametro $filter, verranno restituite solo le modifiche relative agli utenti, indipendentemente da quanto specificato nel valore di filtro.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.Se il segmento &ltresourceSet&gt è "directoryObjects" e il parametro $filter non è specificato, verranno restituite le modifiche relative a tutti i tipi di entità supportati (User, Group e Contact).If &ltresourceSet&gt is “directoryObjects” and $filter is not specified, changes for all of the supported entity types (User, Group, and Contact) are returned.

Per specificare un singolo tipo di entità, usare uno dei filtri seguenti: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')
Per specificare più tipi di entità, usare l'operatore or, ad esempio $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').

Sostituisce il parametro della stringa di query objectScope nella versione di anteprima dell'API Graph.(Replaces the objectScope query string parameter in the preview version of Graph API.)

Importante A partire dalla versione 1.5, lo spazio dei nomi dell'API Graph è stato modificato da Microsoft.WindowsAzure.ActiveDirectory a Microsoft.DirectoryServices.Important Beginning with version 1.5, the Graph API namespace is changed from Microsoft.WindowsAzure.ActiveDirectory to Microsoft.DirectoryServices.Le versioni precedenti dell'API Graph continuano a usare lo spazio dei nomi precedente, ad esempio $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$selectSpecifica le proprietà da includere nella risposta.Specifies which properties should be included in the response.Se il parametro *$select^ non viene specificato, verranno incluse tutte le proprietà.If *$select^ is not specified, all properties are included.

Le proprietà possono essere specificate come complete o non qualificate.Properties can be specified either fully qualified or non-qualified.Le proprietà multiple sono separate da virgole.Multiple properties are delimited by commas.
  • Per le proprietà complete è specificato il tipo di entità, ad esempio User/displayName.Fully qualified properties have the entity type specified; for example, User/displayName.È OBBLIGATORIO usare le proprietà complete se il segmento &ltresourceSet&gt è specificato come "directoryObjects", ad esempio 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.
  • Per le proprietà non qualificate non è specificato il tipo di entità, ad esempio displayName.Non-qualified properties do not have the entity type specified; for example, displayName.Possono essere usate solo quando il segmento &ltresourceSet&gt è specificato come valore diverso da "directoryObjects", ad esempio 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.

Nota: le coppie chiave-valore nella stringa di query fanno distinzione tra maiuscole e minuscole, ma l'ordine non è significativo.Note: The key-value pairs in the query string are case-sensitive, but their order is not significant.

Di seguito è riportato un esempio della query differenziale più semplice.The following is an example of the simplest differential query.Viene usata durante la sincronizzazione iniziale.This is used during initial sync.

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

Di seguito è riportato un esempio di una richiesta successiva:The following is an example of a subsequent request.

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

Risposte a una query differenziale Differential query responses

Questa sezione descrive i contenuti di una risposta a una query differenziale restituita quando viene eseguita una richiesta di query differenziale.This section describes the contents of a differential query response that is returned when a differential query request is made.L'elenco seguente descrive i contenuti di una risposta:The following list describes the contents of a response:

  • Da zero a 200 entità DirectoryObject, ognuna delle quali contiene modifiche per uno specifico oggetto User, Group o Contact.Zero to 200 DirectoryObject entities, each of which contains changes for a specific User, Group, or Contact object.

  • Da zero a 3000 entità DirectoryLinkChange, ognuna delle quali contiene modifiche per uno specifico collegamento a member o manager.Zero to 3000 DirectoryLinkChange entities, each of which contains changes for a specific member or manager link.

  • Una proprietà deltaLink o nextLink.Either a deltaLink or a nextLink property.In entrambi i casi il valore è una stringa codificata come URL, con distinzione tra maiuscole e minuscole che include informazioni di stato sul set delle modifiche alla directory restituite al client, rispetto alle modifiche rimanenti che si sono verificate nella directory.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.Questa stringa (o token) deve essere inclusa nel parametro della stringa di query deltaLink nella successiva richiesta di query differenziale.This string (or token) should be included in the deltaLink query string parameter in the next differential query request.

    • Se viene restituita la proprietà deltaLink, non sono presenti altre modifiche alla directory da sincronizzare dopo la risposta.If the deltaLink property is returned, there are no more directory changes left for the application to synchronize after this response.L'applicazione può attendere un tempo predeterminato in base ai propri requisiti per emettere la successiva richiesta di query differenziale.The application can wait for some predetermined time according to its own requirements to issue the next differential query request.

    • Se viene restituita la proprietà nextLink, sono presenti modifiche alla directory da sincronizzare dopo la risposta.If the nextLink property is returned, there are directory changes remaining for the application to synchronize after this response.L'applicazione deve emettere la successiva richiesta di query differenziale non appena possibile.The application should issue the next differential query request at its earliest convenience.

Le risposte vengono sempre restituite in formato JSON.Responses are always returned in JSON format.

Considerazioni sull'uso della query differenziale Considerations when using differential query

Di seguito sono riportate alcune importanti considerazioni relative alle applicazioni che usano la query differenziale:The following list highlights important considerations for applications that use differential query:

  • Le modifiche restituite dalla query differenziale rappresentano lo stato degli oggetti directory al momento della risposta.Changes returned by differential query represent the state of the directory objects at the time of the response.L'applicazione non deve considerare tali modifiche come log delle transazioni per la riproduzione.Your application must not treat these changes as transaction logs for replay.

  • Le modifiche vengono visualizzate nell'ordine in cui si sono verificate.Changes appear in the order in which they occurred.Gli oggetti modificati più recentemente vengono visualizzati per ultimi anche se l'oggetto è stato aggiornato più volte.The most-recently changed objects appear last even if the object was updated multiple times.L'ordine non è influenzato dal momento in cui il client ha ricevuto le modifiche.Their order is also not affected by when the client received the changes.Pertanto, è possibile che le modifiche vengano presentate in ordine diverso rispetto a quello in cui si sono inizialmente verificate nella directory.As a result, it is possible for changes to be presented out of order compared to how they initially occurred in the directory.

  • L'applicazione deve essere pronta per le riproduzioni, che si verificano quando la stessa modifica è presente in risposte successive.Your application must be prepared for replays, which occur when the same change appears in subsequent responses.Sebbene la query differenziale applichi tutte le misure necessarie per ridurre le riproduzioni, è comunque possibile che si verifichino.While differential query makes a best effort to reduce replays, they are still possible.

  • L'applicazione deve essere pronta a gestire una eliminazione per un oggetto che non riconosciuto.Your application must be prepared to handle a deletion change for an object it was not aware of.

  • La query differenziale può restituire un collegamento a un oggetto origine o destinazione che non è stato ancora restituito da altre risposte.Differential query can return a link to a source or target object that has not yet been returned by other responses.

  • Per altre informazioni sull'uso di intestazioni delle richieste per vincolare le query per migliorare le prestazioni, vedere più avanti la sezione Funzioni aggiuntive delle query differenziali.See the Additional differential query features section below for more information on using request headers to constrain your queries to improve performance.

Esempi di richiesta e di risposta Request and response examples

Di seguito è riportato un esempio di richiesta di query differenziale iniziale: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

Di seguito è riportato un esempio di richiesta di query differenziale incrementale: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

Nota: in entrambe le richieste di esempio, il parametro di query $filter è riportato unicamente a scopo dimostrativo.Note: In both of these sample requests, the $filter query parameter is shown for demonstration purposes only.Poiché il filtro specifica tutti i possibili tipi di destinazione per la query differenziale (User, Group e Contact), è possibile ometterlo. In questo caso la query restituisce le modifiche per tutti questi tipi di entità per impostazione predefinita.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.

La risposta di esempio seguente mostra il JSON restituito: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"
    }
  ]
}

Funzioni aggiuntive delle query differenziali Additional differential query features

Le query differenziali ora possono restituire solo proprietà e collegamenti aggiornati, garantendo un'elaborazione più rapida e payload ridotti per le chiamate delle query di questo tipo.Differential Queries can now return only updated properties and links – this allows faster processing and reduced payloads for Differential Query calls.Questa opzione viene abilitata impostando l'intestazione ocp-aad-dq-include-only-changed-properties su true, come illustrato in questo esempio.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

In questo esempio è stata modificata solo la proprietà "displayName" dell'utente.For example if only the “displayName” property of user has changed.L'oggetto restituito sarà simile al seguente:The returned object would be similar to this:

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

Supporto per la sincronizzazione differenziale dal momento corrente: è possibile specificare un'intestazione speciale che richiede di ottenere soltanto un deltaToken aggiornato. Questo token può essere usato nelle query successive, che restituiranno solo le modifiche a partire dal momento corrente.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”.Ecco la chiamata di esempio: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

La risposta conterrà il valore della proprietà deltaLink, ma non gli oggetti modificati, come illustrato di seguito: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......   }

Rilevamento di un elemento eliminato: la risposta può essere usata anche per rilevare un elemento eliminato.Detecting a deleted item – the response can also be used to detect a deleted item.Gli oggetti e collegamenti eliminati sono indicati dalla proprietà "aad.isDeleted" con il valore impostato su true. Ciò è necessario per assicurarsi che le applicazioni siano informate dell'eliminazione di oggetti e collegamenti creati in precedenza.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.

Risorse aggiuntive Additional resources

© 2018 Microsoft