Estensioni dello schema della directory | Concetti relativi all'API Graph

Articolo
01/26/2016

In questo argomento vengono illustrate le estensioni di directory nell'API Azure AD Graph, che consentono di aggiungere proprietà agli oggetti della directory senza che sia necessario un archivio dati esterno. Se ad esempio in un'organizzazione è disponibile un'applicazione line-of-business (LOB) che richiede un ID Skype per ciascun utente della directory, con l'API Graph è possibile registrare una nuova proprietà denominata skypeId nell'oggetto User della directory e quindi scrivere un valore nella nuova proprietà per un utente specifico. Questo argomento fornisce esempi di uso delle estensioni di directory nell'API Graph, oltre che informazioni sulle limitazioni di tali estensioni e sulla modalità di registrazione in una 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.

Tipi di dati di estensione

È possibile registrare le estensioni solo usando l'API Graph versione 1.5 o successiva. È possibile registrare i seguenti tipi di proprietà:

Tipo di proprietà	Osservazioni
Binary	256 byte al massimo.
Boolean
DateTime	Deve essere specificato nel formato ISO 8601. Verrà archiviato in formato UTC.
Intero	Valore a 32 bit.
LargeInteger	Valore a 64 bit.
Stringa	256 caratteri al massimo.

I tipi di proprietà sopraindicati possono essere registrati per i seguenti oggetti di una directory:

Informazioni sulla modalità di registrazione di un'estensione

È importante comprendere come viene registrata una proprietà estensione in una directory e come influisce il modello di consenso di Azure AD su tale registrazione. Per altre informazioni sul consenso per l'applicazione in Azure AD, vedere Panoramica del framework di consenso in Integrazione di applicazioni con Azure Active Directory.

Le proprietà di estensione per un oggetto Applicazione vengono registrate all'interno della directory dello sviluppatore. Dopo che un utente o un amministratore avrà dato il proprio consenso all'applicazione nella directory dello sviluppatore, la proprietà viene aggiunta al tipo di directory di destinazione e diventa immediatamente accessibile nella directory dello sviluppatore. Nel caso di un'applicazione multi-tenant, quando a questa viene fornito il consenso da un utente o un amministratore di un'altra organizzazione, le proprietà estensione diventano immediatamente accessibili per il tipo di directory di destinazione nella directory dell'altra organizzazione.

Se un'organizzazione acconsente ad autorizzazioni di sola lettura per un'applicazione con estensioni registrate, tali proprietà diventeranno comunque accessibili nella directory dell'altra organizzazione. Inoltre, le proprietà estensione sono accessibili da qualsiasi applicazione di un'organizzazione a cui è stato fornito il consenso, non solo dall'applicazione in cui sono state registrate. Le altre applicazioni dell'organizzazione a cui è stato fornito il consenso possono leggere o scrivere valori per la nuova proprietà estensione solo se dispongono di autorizzazioni sufficienti.

Se nella directory dell'altra organizzazione l'applicazione viene eliminata o il consenso revocato, la proprietà estensione diventa inaccessibile nell'oggetto della directory di destinazione. Se l'estensione viene eliminata dall'applicazione, anch'essa diventa inaccessibile nell'oggetto della directory di destinazione. Se in un'applicazione multi-tenant vengono aggiunte altre proprietà estensione dopo che è stato fornito il consenso, tali proprietà diventeranno immediatamente accessibili nella directory dell'altra organizzazione.

Nota: se il valore della proprietà di un'estensione è impostato su un oggetto e tale proprietà diventa inaccessibile nella directory di tale oggetto, la proprietà viene comunque conteggiata nel limite dell'oggetto di 100 valori della proprietà estensione. L'unico modo per rimuovere il valore della proprietà una volta impostato consiste nell'impostarlo in modo esplicito su Null. Questa operazione non è possibile se la proprietà estensione è inaccessibile.

Scenario di esempio

Considerare il seguente scenario: Litware è un fornitore di software indipendente (ISV) che ha sviluppato un'applicazione SaaS per l'utilizzo da parte di altre organizzazioni. Tale applicazione richiede una proprietà estensione denominata skypeId per un oggetto User. Prima viene registrata l'applicazione nella directory di Litware, quindi viene chiamata l'API Graph per registrare la proprietà di estensione per l'oggetto Applicazione. In questo modo, la proprietà diventa accessibile per gli oggetti User della directory di Litware. L'applicazione viene infine predisposta per configurazioni multi-tenant in modo da poter essere utilizzata in altre organizzazioni.

Poiché Contoso desidera utilizzare l'applicazione SaaS di Litware, un utente o un amministratore di Contoso fornisce all'applicazione il consenso richiesto. Una volta ottenuto il consenso, l'applicazione viene registrata nella directory di Contoso e le proprietà estensione registrate per l'applicazione di Litware diventano immediatamente disponibili nella directory di Contoso. Poiché la proprietà di estensione skypeId per un oggetto User è stata registrata da Litware nell'applicazione, tale proprietà diventa accessibile per gli oggetti Utente della directory di Contoso. L'applicazione di Litware o altre applicazioni a cui è stato fornito il consenso nella directory di Contoso ora possono accedere alla nuova proprietà a seconda delle autorizzazioni configurate per tale applicazione nella directory di Contoso. Ciò significa che le applicazioni, in base alle relative autorizzazioni, potrebbero scrivere un valore per la proprietà estensione in uno o più utenti nella directory. Solo gli utenti per cui è stato scritto un valore skypeId restituiranno tale proprietà nell'oggetto Utente, almeno finché la proprietà skypeId non sarà stata impostata su Null: a questo punto, l'oggetto User per tale utente non restituirà più la proprietà.

Richieste REST di esempio di estensioni della directory

Nelle richieste di esempio riportate di seguito viene illustrato come registrare, visualizzare, scrivere e leggere le estensioni nella directory, nonché come applicare un filtro in base a tali estensioni e annullare la relativa registrazione. È necessario sostituire il segnaposto <applicationObjectId> con l'ID oggetto dell'applicazione registrata. Per ottenere questo valore, effettuare le seguenti operazioni:

Accedere a https://graphexplorer.cloudapp.net/, fare clic sul collegamento Sign in (Accedi) nell'angolo superiore destro, quindi eseguire l'accesso con le credenziali di un account amministratore disponibile nella directory dell'organizzazione.
Dopo aver effettuato l'accesso, fare clic sull'URL nella casella di testo di risorsa (accanto al pulsante GET), selezionare l'URL che termina con applications/ e quindi fare clic su GET oppure sul tasto Invio.
Trovare nei risultati la voce relativa all'applicazione desiderata, quindi copiare il relativo valore objectId come nel seguente esempio: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

In questa sezione sono disponibili richieste di esempio per le seguenti operazioni:

Registrare un'estensione
Visualizzare estensioni registrate
Scrivere un valore dell'estensione
Rimuovere un valore dell'estensione
Leggere un valore dell'estensione
Filtrare un valore dell'estensione
Annullare la registrazione di un'estensione

Per esempi completi che usano le proprietà estensione, vedere i seguenti esempi di Azure AD su Github:

WebApp-GraphAPI-DirectoryExtensions-PHP: mostra come creare e usare le estensioni con PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: mostra un organigramma del tenant AAD e consente la lettura dei valori dell'estensione predefiniti.

Registrare un'estensione

Nella richiesta di esempio seguente viene creato un oggetto extensionProperty per l'oggetto Applicazione desiderato.

Formato della richiesta

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

{
    "name": "<extensionPropertyName>",
    "dataType": "<String or Binary>",
    "targetObjects": [
        "<DirectoryObject>"
    ]
}

Richiesta di esempio

POST https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 104

{
    "name": "skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 201 Creato insieme al nome completo della proprietà estensione, che è possibile utilizzare per la scrittura di valori nel tipo di destinazione.

Risposta di esempio

HTTP/1.1 201 Created
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty/@Element",
    "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "objectType": "ExtensionProperty",
    "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
    "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}

Visualizzare estensioni registrate

Nella richiesta di esempio seguente vengono visualizzate le estensioni registrate per l'oggetto Applicazione.

Formato della richiesta

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties?api-version=1.5 HTTP/1.1

Richiesta di esempio

GET https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 200 OK insieme a tutte le informazioni su ciascuna proprietà estensione registrata per l'oggetto Application.

Risposta di esempio

HTTP/1.1 200 OK
...

{
    "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
    "value": [
        {
            "odata.type": "Microsoft.WindowsAzure.ActiveDirectory.ExtensionProperty",
            "objectType": "ExtensionProperty",
            "objectId": "dc893d45-a75b-4ccf-9b92-ce7d80922aa7",
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "dataType": "String",
            "targetObjects": [
                "User"
            ]
        }
    ]
}

Scrivere un valore dell'estensione

Nella richiesta di esempio seguente viene scritto un valore per la proprietà di estensione *skypeId^ per un oggetto Utente.

Formato della richiesta

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": <value>
}

Richiesta di esempio

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 204 Nessun contenuto.

Risposta di esempio

HTTP/1.1 204 No Content

Se il tentativo di scrivere supera il limite di valore dell'estensione di 100 per l'oggetto, verrà restituita una risposta HTTP 403 - accesso negato con un codice errore "Directory_ResourceSizeExceeded" e il messaggio seguente: "le dimensioni dell'oggetto ha superato il limite. Ridurre il numero di valori e ripetere la richiesta".

Rimuovere un valore dell'estensione

Nella richiesta di esempio seguente è stato rimosso un valore precedentemente impostato per la proprietà di estensione skypeId per un oggetto Utente ed è stato sostituito con Null.

Formato della richiesta

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

{
    "<extensionPropertyName>": null
}

Richiesta di esempio

PATCH https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Content-Type: application/json
Host: graph.windows.net
Content-Length: 65

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 204 Nessun contenuto.

Risposta di esempio

HTTP/1.1 204 No Content

Leggere un valore dell'estensione

Nella richiesta di esempio seguente viene eseguita un'operazione GET semplice sull'utente, che restituirà i valori standard della proprietà oltre che il nuovo valore della proprietà estensione.

Formato della richiesta

GET https://graph.windows.net/contoso.onmicrosoft.com/users/username@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1

Richiesta di esempio

GET https://graph.windows.net/contoso.onmicrosoft.com/users/jim@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 200 OK insieme al nuovo valore della proprietà estensione. Per brevità, molte proprietà utente sono state rimosse dalla risposta di esempio.

Risposta di esempio

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Filtrare un valore dell'estensione

Nella richiesta di esempio seguente gli utenti vengono filtrati in base al valore specificato della proprietà estensione.

Nota: le ricerche del prefisso nelle estensioni sono limitate a 71 caratteri per le ricerche di stringhe e a 207 byte per le ricerche in estensioni binarie.

Formato della richiesta

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=<extensionName>%20eq%20'<value>' HTTP/1.1

Richiesta di esempio

GET https://graph.windows.net/contoso.onmicrosoft.com/users?api-version=1.5&$filter=extension_ab603c56068041afb2f6832e2a17e237_skypeId%20eq%20'jimbob.skype' HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 200 OK insieme all'oggetto utente risultante.

Risposta di esempio

HTTP/1.1 200 OK

{
    ...
    "usageLocation": null,
    "userPrincipalName": "Jim@contoso.onmicrosoft.com",
    "userType": "Member"
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Annullare la registrazione di un'estensione

Nella richiesta di esempio seguente la registrazione di una proprietà estensione viene annullata mediante l'esecuzione di un'operazione DELETE sull'ID oggetto dell'estensione.

Formato della richiesta

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/<applicationObjectId>/extensionProperties/<extensionObjectId>?api-version=1.5 HTTP/1.1

Richiesta di esempio

DELETE https://graph.windows.net/contoso.onmicrosoft.com/applications/269fc2f7-6420-4ea4-be90-9e1f93a87a64/extensionProperties/dc893d45-a75b-4ccf-9b92-ce7d80922aa7?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Qi...r6Xh5KVA
Host: graph.windows.net

Se l'operazione ha esito positivo, verrà restituito un codice di stato HTTP 204 Nessun contenuto e la registrazione della proprietà estensione per l'applicazione verrà annullata.

Risposta di esempio

HTTP/1.1 204 No Content

Comportamento e limitazioni dell'estensione

Il comportamento e le limitazioni seguenti si applicano alle proprietà estensione in una directory:

Le proprietà estensione registrate per un'applicazione diventano disponibili in una directory quando un utente o l'amministratore della directory dà il proprio consenso all'applicazione.
Quando una proprietà estensione diventa disponibile in una directory, qualsiasi applicazione autorizzata potrebbe leggere o scrivere un valore per tale proprietà estensione per uno qualsiasi degli oggetti per cui tale proprietà viene applicata in base alle autorizzazioni di tale applicazione nella directory. Gli oggetti a cui si applica la proprietà estensione vengono specificati nella proprietà targetObjects.
È possibile scrivere massimo 100 valori della proprietà estensione in un oggetto specifico di una directory. Ad esempio, supponendo che non siano stati scritti altri valori della proprietà estensione in un qualsiasi utente in una directory, se un'applicazione scrive un valore della proprietà estensione in user1, altri 99 valori della proprietà estensione potranno essere scritti in user1 da tale applicazione o da un'altra applicazione con autorizzazioni appropriate nella directory. Tuttavia, sarà ancora possibile scrivere fino a 100 valori della proprietà estensione in altri utenti nella directory.
Se un'applicazione prova a impostare un valore per una proprietà estensione aggiuntiva in un oggetto per cui sono già stati impostati 100 valori della proprietà estensione, l'API Graph restituisce una risposta 403 - accesso negato con un codice errore "Directory_ResourceSizeExceeded" e il messaggio seguente: "le dimensioni dell'oggetto ha superato il limite. Ridurre il numero di valori e ripetere la richiesta".
Se uno sviluppatore annulla la registrazione (elimina) una proprietà estensione da un'applicazione, essa diventa immediatamente inaccessibile nella directory per gli sviluppatori e anche nelle directory per cui è stato concesso il consenso all'applicazione.
Se l'applicazione viene rimossa dalla directory per gli sviluppatori, tutte le proprietà estensione registrate per tale applicazione diventano immediatamente inaccessibili nella directory per gli sviluppatori e nelle directory per cui è stato concesso il consenso a tale applicazione.
Se a un'applicazione multi-tenant è stato concesso il consenso per una directory e in seguito ne viene annullata la registrazione (viene rimossa) da tale directory (ad esempio, da un amministratore che usa il portale di gestione di Azure), qualsiasi proprietà estensione registrata in tale applicazione diventa immediatamente inaccessibile in quella directory.
Un valore della proprietà estensione deve essere impostato in modo esplicito su Null per essere rimosso da un oggetto directory. Se viene impostato un valore della proprietà di estensione in un oggetto directory e tale proprietà estensione diventa inaccessibile nella directory per uno dei motivi citati in precedenza, la proprietà estensione non sarà più visibile nell'oggetto directory. Verrà comunque considerata rispetto al limite di 100 dei valori di proprietà estensione per l'oggetto. Fino a quando la disponibilità della proprietà estensione non sarà stata ripristinata (ad esempio, in alcuni casi, dando di nuovo il consenso all'applicazione) il valore non sarà accessibile per la lettura o la scrittura.

Risorse aggiuntive

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