Condividi tramite

Unità amministrative (anteprima) | Concetti relativi all'API Graph

  • Articolo

Si applica a: API Graph | Azure Active Directory (AD)

Panoramica e prerequisiti

Un'unità amministrativa fornisce un contenitore concettuale per gli oggetti directory Utente e Gruppo, consentendo di delegare le autorizzazioni a un livello di granularità più preciso (ad esempio, reparto, regione, ecc.) ai ruoli amministrativi nell'ambito dell'unità amministrativa. Questo argomento fornisce le descrizioni delle proprietà dichiarate e delle proprietà di navigazione esposte dall'entità AdministrativeUnit, nonché le operazioni e le funzioni che possono essere chiamate nella risorsa administrativeUnits di OData.

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.

È anche necessaria una certa familiarità con l'autenticazione e la configurazione di applicazioni di Azure AD prima di usare l'anteprima dell'unità amministrativa. In caso di scarsa familiarità con i concetti associati all'autenticazione di Azure AD e/o i passaggi di configurazione richiesti per consentire l'accesso di un'applicazione al tenant, leggere l'articolo Scenari di autenticazione per Azure AD e in particolare la sezione Nozioni di base sulla registrazione di un'applicazione in Azure AD, che collega a un articolo più dettagliato, dal titolo Integrazione di applicazioni con Azure Active Directory.

Prima di procedere alle sezioni successive, per altre informazioni utili e importanti vedere il principale articolo su Azure.com, API Graph di Azure Active Directory, e l'elenco seguente di articoli sull'API Graph.

  1. Controllo delle versioni dell'API di Azure AD Graph

    Importante: la funzionalità di unità amministrativa è disponibile in anteprima solo al momento. Per usare le funzionalità di anteprima, assicurarsi di impostare il parametro della stringa di query api-version su "beta", ad esempio: https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

    È possibile creare e usare unità amministrative solo se si abilita Azure Active Directory Premium. Per altre informazioni, vedere Introduzione ad Azure Active Directory Premium

  2. Avvio rapido per l'API Graph di Azure AD su Azure.com

  3. Panoramica delle operazioni dell'API Graph

  4. Query, opzioni di paging e filtri supportati

Spazio dei nomi ed ereditarietà

Spazio dei nomi: Microsoft.DirectoryServices

Tipo di base: DirectoryObject

Proprietà

L'entità AdministrativeUnit supporta le proprietà seguenti:

Proprietà dichiarate

Name Tipo Creazione (POST) Lettura (GET) Aggiornamento (PATCH) Descrizione
description Edm.String Facoltativo Facoltativo Descrizione facoltativa per l'unità amministrativa.
displayName Edm.String Richiesto Filtrabile Facoltativo Nome visualizzato per l'unità amministrativa.
Name Da molteplicità To A molteplicità Descrizione
members * Utente o gruppo * Membri assegnati all'unità amministrativa, che può essere Utenti o Gruppi. Ereditato da DirectoryObject.
scopedAdministrators * ScopedRoleMembership * Amministratori assegnati a un determinato ruolo (o ruoli), nell'ambito di un'unità amministrativa.

Nota: nonostante l'entità DirectoryObject supporti anche altre proprietà di navigazione, tra cui memberOf, owners e ownedObjects, queste proprietà non sono valide per l'unità amministrativa. Se viene inviata una richiesta per una di queste proprietà, viene restituita una risposta 400 Richiesta non valida con un corrispondente messaggio di errore.

Indirizzamento

La definizione del percorso può estendersi a una raccolta di unità amministrative nella directory, a una singola unità amministrativa o alle risorse correlate disponibili attraverso le proprietà di navigazione supportate di un'unità amministrativa. Gli esempi nella tabella usano il dominio del tenant per l'indirizzamento del tenant Per altre modalità di definizione del percorso del tenant vedere Definire il percorso di entità e operazioni nell'API Graph.

Elemento Frammento di URL Esempio
Set di risorse (tutte le unità amministrative) /administrativeUnits https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta
Singola risorsa (ad esempio: una sola unità amministrativa) /administrativeUnits/{objectId} https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta
Risorse correlate con una proprietà di navigazione /administrativeUnits/{objectId}/$links/{nome-proprietà} https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta

Nota: vedere la sezione Proprietà di navigazione sopra riportata per l'elenco delle proprietà di navigazione valide che possono essere usate al posto di {nome-proprietà}. Rimuovere il segmento "$links" dalla parte del percorso della risorsa dell'URI per restituire gli oggetti effettivi a cui fa riferimento una proprietà di navigazione anziché i relativi collegamenti. È anche possibile definire il percorso di un'unità amministrativa usando oggetti directory generici, sostituendo "administrativeUnits" con "directoryObjects" nella parte del percorso della risorsa dell'URI.

Per informazioni più complete sull'esecuzione di query su oggetti directory, vedere Query comuni dell'API di Azure AD Graph e Query differenziale dell'API di Azure AD Graph.

Operazioni supportate: administrativeUnits

Questa sezione definisce le operazioni supportate in un set di risorse administrativeUnits. Come accennato in precedenza, è importante esaminare prima gli argomenti contenuti nella sezione Panoramica e prerequisiti per comprendere alcuni dei concetti alla base di API Graph che si applicano a tutte le entità, ad esempio la corretta formattazione degli URL, la definizione del percorso di entità e operazioni, l'uso del controllo delle versioni e altro ancora.

Per ognuna delle operazioni elencate di seguito:

  • L'entità che esegue l'operazione deve appartenere a un ruolo di amministratore che abbia i privilegi necessari per modificare le risorse administrativeUnits con le richieste PATCH, POST o DELETE e i privilegi necessari per leggere oggetti con le richieste GET.

  • Se richiesto, sostituire le stringhe segnaposto "contoso.onmicrosoft.com" con il dominio del proprio tenant di Azure Active Directory e {objectId} con l'ID del tipo di risorsa determinato nell'URL.

  • Ogni richiesta deve includere le intestazioni della richiesta HTTP riportate nella tabella seguente.

Intestazione della richiesta Descrizione
Autorizzazione Obbligatorio. Token di connessione rilasciato da Azure Active Directory. Per altre informazioni, vedere Scenari di autenticazione per Azure AD.
Content-Type Obbligatorio. Tipo di dati multimediali del contenuto nel corpo della richiesta, ad esempio application/json.
Content-Length Obbligatorio. Lunghezza della richiesta in byte.

Le prime quattro operazioni elencate di seguito vengono usate per gestire la creazione, il recupero, l'aggiornamento e l'eliminazione delle entità AdministrativeUnit. Le operazioni che le seguono usano le proprietà di navigazione members e scopedAdministrators per gestire i membri Utente/Gruppo dell'entità AdministrativeUnit e il set di amministratori nell'ambito (per mezzo dell'entità ScopedRoleMembership) che detengono rispettivamente il controllo amministrativo dell'entità AdministrativeUnit.

Crea un'unità amministrativa

Consente di creare una nuova entità AdministrativeUnit.

Metodo HTTP URI della richiesta
POST https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

Il corpo della richiesta specifica la proprietà obbligatoria displayName e la proprietà facoltativa description:

{
  "displayName":"Central Region",
  "description":"Administrators responsible for the Central region."
}

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il corpo della risposta sarà simile al seguente.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

Ottieni una o più unità amministrative

Consente di recuperare un'entità AdministrativeUnit specifica in base a {objectId}, un subset filtrando in base alla proprietà displayName (vedere Query, opzioni di paging e filtri supportati nell'API di Azure AD Graph) oppure l'elenco di tutte quelle disponibili. Gli esempi di richiesta/risposta seguenti mostrano rispettivamente le query per una determinata unità amministrativa e per tutte le unità amministrative.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il corpo della risposta sarà simile a uno di quelli indicati di seguito.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
   "objectType":"AdministrativeUnit",
   "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
   "deletionTimestamp":null,
   "displayName":"Central Region",
   "description":"Administrators responsible for the Central region."
}

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"ca1a80f3-ac25-429b-a1e9-0f1eb87cc30b",
      "deletionTimestamp":null,
      "displayName":"Central Region",
      "description":"Administrators responsible for the Central region."
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"455b7304-b245-4d58-95c4-1797c32c80db",
      "deletionTimestamp":null,
      "displayName":"East Coast Region",
      "description":"East Coast Two"
      }
   ]
}

Aggiornare un'unità amministrativa

Consente di aggiornare una o più proprietà in un'entità AdministrativeUnit.

Metodo HTTP URI della richiesta
PATCH https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

Il corpo della richiesta specifica una o entrambe le proprietà AdministrativeUnit:

{ 
  "displayName":"Central Region Administrators"
}

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Non esiste alcuna risposta OData nel corpo della risposta.

Elimina un'unità amministrativa

Consente di eliminare un'entità AdministrativeUnit, come specificato da {objectId}.

Metodo HTTP URI della richiesta
DELETE https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Non esiste alcuna risposta OData nel corpo della risposta.

Le operazioni seguenti vengono implementate usando la proprietà di navigazione members, che consente la gestione dei membri utente/gruppo di un'entità AdministrativeUnit. In base alle considerazioni precedenti, il segmento della risorsa $links consente di ignorare o modificare l'associazione (cioè il collegamento) tra due risorse, ad esempio tra una risorsa administrativeUnit e una risorsa User o Group.

Aggiungi uno o più membri a un'unità amministrativa

Consente di aggiungere i membri della risorsa utente o gruppo a un'entità AdministrativeUnit.

Metodo HTTP URI della richiesta
POST https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta

In questo esempio il corpo della richiesta specifica l'URL al membro desiderato che si vuole aggiungere alla risorsa administrativeUnit, che in questo caso è una risorsa utenti. È anche possibile usare directoryObjects come segmento della risorsa del tipo, al posto della risorsa utenti, perché l'entità User viene ereditata dall'entità DirectoryObject. Lo stesso vale quando si usa il segmento della risorsa gruppi.

{
  "url":" https://graph.windows.net/contoso.onmicrosoft.com/users/a1daa894-ff32-4839-bb6a-d7a4210fc96a"
}

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Non esiste alcuna risposta OData nel corpo della risposta.

Ottieni uno o più membri di un'unità amministrativa

Consente di recuperare i membri della risorsa utente o gruppo da una risorsa administrativeUnit. Si noti che è possibile recuperare i membri usando qualsiasi forma di operazione GET elencata di seguito. La prima restituisce l'URL/il collegamento ai membri, la seconda restituisce le proprietà per il membro/i membri. In entrambi i casi, il segmento {memberObjectId} è facoltativo, a seconda che l'obiettivo sia la restituzione di un set di membri o di un membro specifico.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/members/{memberObjectId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il primo esempio riportato di seguito illustra il corpo della risposta per un'operazione che usa il segmento $links per tutti i membri (ad esempio: {memberObjectId} non è specificato), in cui sono disponibili due tipi di risorse: Utente e Gruppo. Il secondo mostra la risposta per l'esempio precedente, senza il segmento $links.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/members",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a1daa894-ff32-4839-bb6a-d7a4210fc96a/Microsoft.DirectoryServices.User"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a0ab9340-2b20-4b3f-8672-bf1a2f141f91/Microsoft.DirectoryServices.Group"
      }
   ]
}

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.User",
      "objectType":"User",
      "objectId":"a1daa894-ff32-4839-bb6a-d7a4210fc96a",
      "deletionTimestamp":null,
      "acceptedAs":null,
      "acceptedOn":null,
      "accountEnabled":true,
      "alternativeSecurityIds":[],
      "alternativeSignInNames":[admin@contoso.com],
      "alternativeSignInNamesInfo":[],
      "appMetadata":null,
      "assignedLicenses":[],
      "assignedPlans":[],
      "city":"Redmond",
      "cloudSecurityIdentifier":"S-1-12-6-2715461780-1211760434-2765580987-1791561505",
      "companyName":null,
      "country":null,
      "creationType":null,
      "department":null,
      "dirSyncEnabled":null,
      "displayName":"Jon Doe",
      "extensionAttribute1":null,
      "extensionAttribute2":null,
      "extensionAttribute3":null,
      "extensionAttribute4":null,
      "extensionAttribute5":null,
      "extensionAttribute6":null,
      "extensionAttribute7":null,
      "extensionAttribute8":null,
      "extensionAttribute9":null,
      "extensionAttribute10":null,
      "extensionAttribute11":null,
      "extensionAttribute12":null,
      "extensionAttribute13":null,
      "extensionAttribute14":null,
      "extensionAttribute15":null,
      "facsimileTelephoneNumber":null,
      "givenName":"Jon",
      "immutableId":null,
      "invitedOn":null,
      "inviteReplyUrl":[],
      "inviteResources":[],
      "inviteTicket":[],
      "isCompromised":null,
      "jobTitle":null,
      "jrnlProxyAddress":null,
      "lastDirSyncTime":null,
      "mail":null,
      "mailNickname":"admin",
      "mobile":null,
      "netId":"100300008001EE6E",
      "onPremisesSecurityIdentifier":null,
      "otherMails":[jon@doe.com],
      "passwordPolicies":null,
      "passwordProfile":null,
      "physicalDeliveryOfficeName":null,
      "postalCode":"98052",
      "preferredLanguage":"en-US",
      "primarySMTPAddress":null,
      "provisionedPlans":[],
      "provisioningErrors":[],
      "proxyAddresses":[],
      "releaseTrack":null,
      "searchableDeviceKey":[],
      "selfServePasswordResetData":null,
      "sipProxyAddress":null,
      "smtpAddresses":[],
      "state":"WA",
      "streetAddress":
      "One Microsoft Way",
      "surname":"Doe",
      "telephoneNumber":"(123) 456-7890",
      "usageLocation":"US",
      "userPrincipalName":admin@constoso.com,
      "userState":null,
      "userStateChangedOn":null,
      "userType":"Member"      
      },
      { 
      "odata.type":"Microsoft.DirectoryServices.Group",
      "objectType":"Group",
      "objectId":"a0ab9340-2b20-4b3f-8672-bf1a2f141f91",
      "deletionTimestamp":null,
      "appMetadata":null,
      "cloudSecurityIdentifier":"S-1-12-6-2695598912-1262431008-448754310-2434733103",
      "description":null,
      "dirSyncEnabled":null,
      "displayName":"Group for users in Central Region Administrative Unit",
      "exchangeResources":[],
      "groupType":null,
      "isPublic":null,
      "lastDirSyncTime":null,
      "licenseAssignment":[],
      "mail":null,
      "mailEnabled":false,
      "mailNickname":"CentralUsers",
      "onPremisesSecurityIdentifier":null,
      "provisioningErrors":[],
      "proxyAddresses":[],
      "securityEnabled":true,
      "sharepointResources":[],
      "targetAddress":null,
      "wellKnownObject":null     
      }
   ]
}

Elimina uno o più membri da un'unità amministrativa

Consente di eliminare i membri della risorsa utente o gruppo da una risorsa administrativeGroup. Poiché members è una proprietà di navigazione con più valori, è necessario includere l'elemento {objectId} del membro/collegamento nell'URL della richiesta che si vuole eliminare.

Metodo HTTP URI della richiesta
DELETE https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Non esiste alcuna risposta OData nel corpo della risposta.

Gli amministratori vengono assegnati a un'unità amministrativa inserendoli in un ruolo nell'ambito di tale unità amministrativa. Le operazioni rimanenti in questa sezione vengono implementate usando la proprietà di navigazione scopedAdministrators, che consente la gestione degli amministratori del set che detengono il controllo amministrativo di un'entità AdministrativeUnit, usando un ruolo con ambito.

Aggiungi un amministratore del ruolo con ambito a un'unità amministrativa

Consente di aggiungere un amministratore a un ruolo con ambito in una risorsa administrativeUnit, usando l'entità ScopedRoleMembership e la proprietà di navigazione scopedAdministrators. In questo esempio, l'operazione esegue due attività:

  1. Inserisce un nuovo elemento ScopedRoleMembership (che NON è una risorsa OData indirizzabile), che stabilisce una relazione tra un'entità AdministrativeUnit, una risorsa DirectoryRole con ambito unità amministrativa e un utente amministratore.

  2. Stabilisce un'associazione/collegamento della proprietà di navigazione tra l'entità AdministrativeUnit e il nuovo elemento ScopedRoleMembership.

Metodo HTTP URI della richiesta
POST https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta

Il corpo della richiesta specifica le proprietà dell'entità ScopedRoleMembership seguenti:

  • roleObjectId: objectId dell'elemento DirectoryRole desiderato. Nota: solo i ruoli HelpDeskAdministrators e UserAccountAdministrator sono validi.

  • roleMemberInfo: una struttura che identifica l'utente amministratore.

  • objectId: objectId dell'utente amministratore.

{
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "roleMemberInfo":{
      "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f"}
}

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il corpo della risposta sarà simile al seguente.

{
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/Microsoft.DirectoryServices.AdministrativeUnit/@Element",
   "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
   "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
   "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
   "roleMemberInfo":{"objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
      "displayName":"Bryan",
      "userPrincipalName":BryanL@contoso.com
      }
}

Ottieni un amministratore del ruolo con ambito a un'unità amministrativa

Consente di ottenere l'elenco degli amministratori nei ruoli con ambito per una risorsa administrativeUnit, come le entità ScopedRoleMembership. Il segmento {scopedRoleMemberId} è facoltativo, a seconda che l'obiettivo sia la restituzione di un set di membri o di un membro specifico.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il corpo della risposta seguente è relativo a una query per tutti i membri.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }            
   ]
}

Elimina un amministratore del ruolo con ambito da un'unità amministrativa.

Consente di eliminare una risorsa ScopedRoleMembership da una risorsa administrativeUnit, specificata dal segmento di {scopedRoleMemberId}.

Metodo HTTP URI della richiesta
DELETE https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Non esiste alcuna risposta OData nel corpo della risposta.

Operazioni supportate: utenti e gruppi

Questa sezione definisce le operazioni ora supportate nelle risorse utenti e gruppi, che forniscono il supporto per le risorse administrativeUnit.

È possibile controllare la documentazione GA completa per le entità User e Group, nonché per le operazioni sulle risorse utenti e gruppi.

Per ognuna delle operazioni elencate di seguito:

  • L'entità che esegue l'operazione deve avere i privilegi necessari per la lettura di oggetti usando richieste GET.

  • Se richiesto, sostituire le stringhe segnaposto "contoso.onmicrosoft.com" con il dominio del proprio tenant di Azure Active Directory e {objectId} con l'ID del tipo di risorsa determinato nell'URL.

  • Ogni richiesta deve includere le intestazioni della richiesta HTTP seguenti:

    Intestazione della richiesta Descrizione
    Autorizzazione Obbligatorio. Token di connessione rilasciato da Azure Active Directory. Per altre informazioni, vedere Scenari di autenticazione per Azure AD.
    Content-Type Obbligatorio. Tipo di dati multimediali del contenuto nel corpo della richiesta, ad esempio application/json.
    Content-Length Obbligatorio. Lunghezza della richiesta in byte.

Ottieni una o più unità amministrative a cui appartiene un utente o gruppo

L'anteprima consente il recupero dell'appartenenza a administrativeUnits per le risorse utenti e gruppi, attraverso la proprietà di navigazione memberOf nell'entità DirectoryObject. Specificare il segmento della risorsa "utenti" per recuperare l'appartenenza per le risorse utenti o "gruppi" per le risorse gruppi. Specificare il segmento della risorsa "$links" per recuperare gli URL/i collegamenti della risorsa oppure ometterlo per recuperare le proprietà.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/memberOf?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il primo esempio riportato di seguito illustra il corpo della risposta per una risorsa utenti con il segmento $links, che appartiene a due tipi di risorse: DirectoryRole e AdministrativeUnit. Il secondo mostra la risposta per l'esempio precedente, senza il segmento $links.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/memberOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/cbf54c29-6184-484d-92d6-d6af32f896a2/Microsoft.DirectoryServices.DirectoryRole"
      },
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/3cc09cfd-5423-4002-85b8-070d60a63fe2/Microsoft.DirectoryServices.AdministrativeUnit"
      }
   ]
}

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects",
   "value":
   [
      {
      "odata.type":"Microsoft.DirectoryServices.DirectoryRole",
      "objectType":"Role",
      "objectId":"cbf54c29-6184-484d-92d6-d6af32f896a2",
      "deletionTimestamp":null,
      "cloudSecurityIdentifier":"S-1-12-6-3421850665-1213030788-2950092434-2727802930",
      "description":"Company Administrator role has full access to perform any operation in the company scope.",
      "displayName":"Company Administrator",
      "isSystem":true,
      "roleDisabled":false,
      "roleTemplateId":"62e90394-69f5-4237-9190-012177145e10"
      },
      {
      "odata.type":"Microsoft.DirectoryServices.AdministrativeUnit",
      "objectType":"AdministrativeUnit",
      "objectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "deletionTimestamp":null,
      "displayName":"Central Region Administrators",
      "description":"Administrators responsible for the Central Region"
      }    
   ]  
}

Ottieni una o più unità amministrative di cui un utente è un amministratore

Consente di recuperare la risorsa adminstrativeUnits (o più risorse) di cui un utente è un amministratore usando la proprietà di navigazione scopedAdministratorOf nell'entità User. Si noti che è possibile usare qualsiasi forma di operazione GET elencata di seguito. La prima recupera gli URL/il collegamento della risorsa, la seconda restituisce le proprietà.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta
GET https://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/scopedAdministratorOf?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il primo esempio riportato di seguito illustra il corpo della risposta per un'operazione usando il segmento $links. Il secondo mostra la risposta per l'esempio precedente, senza il segmento $links.

{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/scopedAdministratorOf",
   "value":
   [
      {
      "url":"https://graph.windows.net/contoso.onmicrosoft.com/scopedRoleMemberships/kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU"
      }
   ]
}```
```json
{
   "odata.metadata": "https://graph.windows.net/contoso.onmicrosoft.com/$metadata#scopedRoleMemberships",
   "value":
   [
      {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
         {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
         }
      }
   ]  
}

Operazioni supportate: directoryRoles

Questa sezione definisce le operazioni ora supportate nelle risorse directoryRoles che forniscono supporto specifico per le risorse administrativeUnits.

È possibile consultare la documentazione GA completa per altre informazioni sull'entità DirectoryRole e sulle operazioni**** correlate.

Per ognuna delle operazioni elencate di seguito:

  • L'entità che esegue l'operazione deve avere i privilegi necessari per la lettura di oggetti usando richieste GET.

  • Se richiesto, sostituire le stringhe segnaposto "contoso.onmicrosoft.com" con il dominio del proprio tenant di Azure Active Directory e {objectId} con l'ID del tipo di risorsa determinato nell'URL.

  • Ogni richiesta deve includere le intestazioni della richiesta HTTP seguenti:Intestazione della richiestaDescrizioneAutorizzazioneObbligatoria. Token di connessione rilasciato da Azure Active Directory. Per altre informazioni, vedere Scenari di autenticazione per Azure AD.Content-TypeObbligatoria. Tipo di dati multimediali del contenuto nel corpo della richiesta, ad esempio application/json.Content-LengthRequired. Lunghezza della richiesta in byte.

Intestazione della richiesta Descrizione
Autorizzazione Obbligatorio. Token di connessione rilasciato da Azure Active Directory. Per altre informazioni, vedere Scenari di autenticazione per Azure AD.
Content-Type Obbligatorio. Tipo di dati multimediali del contenuto nel corpo della richiesta, ad esempio application/json.
Content-Length Obbligatorio. Lunghezza della richiesta in byte.

Ottenere amministratori delle unità amministrative con ambito in un ruolo specifico

Gli amministratori vengono assegnati a un'unità amministrativa inserendoli in un ruolo nell'ambito di tale unità amministrativa. Questa operazione consente di recuperare tali "appartenenze del ruolo con ambito" per un amministratore, ad esempio un set di risorse scopedRoleMemberships. Si noti che solo un {objectId} del ruolo "HelpDeskAdministrators" o "UserAccountAdministrator" è valido. Si noti anche che il segmento {scopedRoleMemberId} è facoltativo, a seconda che l'obiettivo sia la restituzione di tutte le risorse scopedRoleMembership per un ruolo specifico o di una risorsa specifica.

Metodo HTTP URI della richiesta
GET https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta

Non esiste alcun corpo della richiesta.

Per le definizioni dei codici di risposta, vedere la sezione Informazioni di riferimento sulla risposta HTTP riportata di seguito. Il corpo della risposta seguente è relativo a una query per tutti gli amministratori di una determinata unità amministrativa, nell'ambito del ruolo di Amministratore supporto tecnico.

{ 
   "odata.metadata":https://graph.windows.net/contoso.onmicrosoft.com /$metadata#scopedRoleMemberships,
   "value":[
   {
      "id":"kxyuS4zvB0mDyB4cH9Liwf2cwDwjVAJAhbgHDWCmP-Itu0Khgd9mQK-R9j5Kup5fU",
      "roleObjectId":"4bae1c93-ef8c-4907-83c8-1e1c1fd2e2c1",
      "administrativeUnitObjectId":"3cc09cfd-5423-4002-85b8-070d60a63fe2",
      "roleMemberInfo":
      {
         "objectId":"a142bb2d-df81-4066-af91-f63e4aba9e5f",
         "displayName":"Bryan",
         "userPrincipalName":BryanL@contoso.com
      }
   ]
}

Informazioni di riferimento sulla risposta HTTP

Di seguito è riportato l'elenco dei possibili codici di risposta HTTP:

Codice di stato HTTP Codice errore OData Descrizione
200/OK n/d Risposta normale per una query eseguita correttamente. Il corpo della risposta conterrà i dati che soddisfano i filtri specificati nei parametri di query.
201/Created n/d Risposta normale per un'operazione POST/create eseguita correttamente. Il corpo della risposta conterrà i dati così come popolati nella nuova risorsa.
204/No Content n/d Risposta normale per un'operazione PATCH/update o DELETE completata correttamente in una risorsa o POST in una risorsa collegata. Il corpo della risposta non conterrà una risposta OData.
400/BadRequest Request_BadRequest Si tratta di un messaggio di errore generico per un'intestazione, un parametro o dati del corpo della richiesta non validi o mancanti. Questo errore si verifica anche se si prova ad aggiungere una risorsa collegata che esiste già.
401/Unauthorized AuthorizationError Verrà visualizzato quando l'utente non è autorizzato a visualizzare il contenuto. Vedere l'articolo principale sull'API REST Graph di Azure AD per altre informazioni su come proteggere le chiamate e ottenere e specificare un token di accesso protetto.
404/Not Found Request_ResourceNotFound Verrà visualizzato quando la risorsa a cui che si sta provando ad accedere non esiste.
405/Method not allowed Request_BadRequest Questo verrà visualizzato quando si prova a eseguire un'operazione destinata a una risorsa specifica, ma non viene fornito l'ID di risorsa corretto nell'URL della richiesta.

Risorse aggiuntive