Query differenziale | Concetti relativi all'API Graph

Articolo
01/26/2016

Si applica a: API Graph | Azure Active Directory

Questo argomento illustra la funzionalità di query differenziale dell'API di Azure AD Graph. Una richiesta di query differenziale restituisce tutte le modifiche apportate alle entità specificate nel tempo intercorso tra due richieste consecutive. 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. Questa funzionalità è particolarmente utile durante la sincronizzazione dei dati della directory di un tenant con l'archivio dati di un'applicazione.

Per eseguire una richiesta di query differenziale alla directory di un tenant, l'applicazione deve essere autorizzata dal tenant. Per altre informazioni, vedere Integrazione di applicazioni con Azure Active Directory.

Importante

Per accedere alle risorse di Azure Active Directory è fortemente consigliabile usare Microsoft Graph anziché l'API di Azure AD Graph. Le attività di sviluppo Microsoft sono ora concentrate su Microsoft Graph e non sono previsti altri miglioramenti per l'API di Azure AD Graph. 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.

Richieste di query differenziale

Questa sezione descrive le richieste di query differenziale. Per tutte le richieste sono necessari i componenti seguenti:

Un URL della richiesta valido, che includa l'endpoint Graph per il tenant e i parametri applicabili della stringa di query.
Un'intestazione di autorizzazione, tra cui un token di accesso valido rilasciato da Azure Active Directory. Per altre informazioni sull'autenticazione all'API Graph, vedere Scenari di autenticazione per Azure AD.

URL della richiesta di query differenziale

Di seguito viene illustrato il formato dell'URL per la richiesta di query differenziale. Le parentesi quadre [] indicano elementi facoltativi.

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.

URL: segmenti gerarchici

Segmento	Descrizione
tenantId	Identificatore univoco del tenant nel quale deve essere eseguita la query. In genere è uno dei domini verificati (proprietà verifiedDomains) del tenant, ma può anche essere l'ID oggetto del tenant (proprietà objectId). Non fa distinzione tra maiuscole e minuscole.
resourceSet	Set specifico di risorse del tenant nel quale deve essere eseguita la query. Determina quali risorse vengono restituite nella risposta alla query. I valori supportati sono: "directoryObjects", "users", "contacts" o "groups". Per i valori viene fatta distinzione tra maiuscole e minuscole.

URL: parametri delle stringhe di query

Parametro	Descrizione
api-version	Specifica la versione dell'API Graph per cui è stata inviata la richiesta. Obbligatorio. A partire dalla versione 1.5, il valore è espresso come numero di versione in formato numerico, ad esempio api-version=1.5. Per le versioni precedenti, il valore è una stringa in formato AAAA-MM-GG, ad esempio, api-version=2013-04-05. Sostituisce l'uso dell'intestazione x-ms-dirapi-data-contract-version nella versione di anteprima dell'API Graph.
deltaLink	Token restituito nella proprietà deltaLink o nella proprietà nextLink nell'ultima risposta. Obbligatorio, ma sarà vuoto nella prima richiesta. Sostituisce il parametro della stringa di query skipToken nella versione di anteprima dell'API Graph.
$filter	Indica i tipi di entità da includere nella risposta. Facoltativo. I tipi di entità supportati sono: User, Group e Contact. Valido solo quando il segmento &ltresourceSet&gt è "directoryObjects"; in caso contrario, &ltresourceSet&gt esegue l'override del filtro. 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. 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). Per specificare un singolo tipo di entità, usare uno dei filtri seguenti: `$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')`. Sostituisce il parametro della stringa di query objectScope nella versione di anteprima dell'API Graph. Importante A partire dalla versione 1.5, lo spazio dei nomi dell'API Graph è stato modificato da Microsoft.WindowsAzure.ActiveDirectory a Microsoft.DirectoryServices. Le versioni precedenti dell'API Graph continuano a usare lo spazio dei nomi precedente, ad esempio `$filter=isof('Microsoft.WindowsAzure.ActiveDirectory.Contact')`.
$select	Specifica le proprietà da includere nella risposta. Se il parametro *$select^ non viene specificato, verranno incluse tutte le proprietà. Le proprietà possono essere specificate come complete o non qualificate. Le proprietà multiple sono separate da virgole. Per le proprietà complete è specificato il tipo di entità, ad esempio `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`. Per le proprietà non qualificate non è specificato il tipo di entità, ad esempio `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`.

Nota: le coppie chiave-valore nella stringa di query fanno distinzione tra maiuscole e minuscole, ma l'ordine non è significativo.

Di seguito è riportato un esempio della query differenziale più semplice. Viene usata durante la sincronizzazione iniziale.

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

Di seguito è riportato un esempio di una richiesta successiva:

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

Risposte a una query differenziale

Questa sezione descrive i contenuti di una risposta a una query differenziale restituita quando viene eseguita una richiesta di query differenziale. L'elenco seguente descrive i contenuti di una risposta:

Da zero a 200 entità DirectoryObject, ognuna delle quali contiene modifiche per uno specifico oggetto User, Group o Contact.
Da zero a 3000 entità DirectoryLinkChange, ognuna delle quali contiene modifiche per uno specifico collegamento a member o manager.
Una proprietà deltaLink o nextLink. 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. Questa stringa (o token) deve essere inclusa nel parametro della stringa di query deltaLink nella successiva richiesta di query differenziale.
- Se viene restituita la proprietà deltaLink, non sono presenti altre modifiche alla directory da sincronizzare dopo la risposta. L'applicazione può attendere un tempo predeterminato in base ai propri requisiti per emettere la successiva richiesta di query differenziale.
- Se viene restituita la proprietà nextLink, sono presenti modifiche alla directory da sincronizzare dopo la risposta. L'applicazione deve emettere la successiva richiesta di query differenziale non appena possibile.

Le risposte vengono sempre restituite in formato JSON.

Considerazioni sull'uso della query differenziale

Di seguito sono riportate alcune importanti considerazioni relative alle applicazioni che usano la query differenziale:

Le modifiche restituite dalla query differenziale rappresentano lo stato degli oggetti directory al momento della risposta. L'applicazione non deve considerare tali modifiche come log delle transazioni per la riproduzione.
Le modifiche vengono visualizzate nell'ordine in cui si sono verificate. Gli oggetti modificati più recentemente vengono visualizzati per ultimi anche se l'oggetto è stato aggiornato più volte. L'ordine non è influenzato dal momento in cui il client ha ricevuto le modifiche. Pertanto, è possibile che le modifiche vengano presentate in ordine diverso rispetto a quello in cui si sono inizialmente verificate nella directory.
L'applicazione deve essere pronta per le riproduzioni, che si verificano quando la stessa modifica è presente in risposte successive. Sebbene la query differenziale applichi tutte le misure necessarie per ridurre le riproduzioni, è comunque possibile che si verifichino.
L'applicazione deve essere pronta a gestire una eliminazione per un oggetto che non riconosciuto.
La query differenziale può restituire un collegamento a un oggetto origine o destinazione che non è stato ancora restituito da altre risposte.
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.

Esempi di richiesta e di risposta

Di seguito è riportato un esempio di richiesta di query differenziale iniziale:

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:

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. 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.

La risposta di esempio seguente mostra il JSON restituito:

{
  "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

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. Questa opzione viene abilitata impostando l'intestazione ocp-aad-dq-include-only-changed-properties su true, come illustrato in questo esempio.

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. L'oggetto restituito sarà simile al seguente:

{     
          "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. Ecco la chiamata di esempio:

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:

{   …  "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. 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.

Risorse aggiuntive

Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph)