Query differenziale | Concetti relativi all'API Graph

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.

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

URL: parametri delle stringhe di query

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)