Administrative Einheiten (Vorschau) | Graph-API-Konzepte

Artikel
06/09/2016

Gilt für: Graph-API | Azure Active Directory (AD)

Übersicht und Voraussetzungen

Eine administrative Einheit stellt einen konzeptionellen Container für Benutzer- und Gruppenverzeichnisobjekte bereit, der es Administratorrollen, die der administrativen Einheit zugewiesen sind, ermöglicht, Berechtigungen mit höherer Granularität (d.h. für Abteilungen, Regionen usw.) zu delegieren. Dieses Thema enthält Beschreibungen der deklarierten Eigenschaften und Navigationseigenschaften, die von der Entität AdministrativeUnit verfügbar gemacht werden, sowie der Vorgänge und Funktionen, die für die OData-Ressource administrativeUnits aufgerufen werden können.

Wichtig

Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.

Die Verwendung der Vorschau von administrativen Einheiten erfordert außerdem Kenntnisse in der Authentifizierung und Anwendungskonfiguration in Azure AD. Wenn Sie mit den Konzepten der Azure AD-Authentifizierung und/oder den Konfigurationsschritten, die erforderlich sind, um einer Anwendung den Zugriff auf Ihren Mandanten zu gewähren, nicht vertraut sind, sollten Sie den ArtikelAuthentifizierungsszenarien für Azure AD und insbesondere den Abschnitt Grundlagen zur Registrierung einer Anwendung in Azure AD lesen. Hier finden Sie eine Verknüpfung zum detaillierteren Artikel Integrieren von Anwendungen in Azure Active Directory.

Bevor Sie mit den nachfolgenden Abschnitten fortfahren, lesen Sie den Hauptartikel zur Azure Active Directory Graph-API auf Azure.com, und sehen Sie sich die folgende Liste von Artikeln zur Graph-API an, um weitere wichtige und hilfreiche Informationen zu erhalten:

Versionsverwaltung der Azure AD Graph-API

Wichtig: Das Feature der administrativen Einheiten ist derzeit nur in der Vorschau verfügbar. Um Vorschaufunktionen zu verwenden, achten Sie darauf, den Abfragezeichenfolgenparameter für die API-Version auf „beta“ festzulegen, d.h.: https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

Sie können administrative Einheit nur erstellen und verwenden, wenn Sie Azure Active Directory Premium aktivieren. Weitere Informationen finden Sie unter Erste Schritte mit Azure Active Directory Premium.
Schnellstartanleitung für die Azure AD Graph-API auf Azure.com
Übersicht über die Vorgänge der Graph-API
Unterstützte Abfragen, Filter und Paginierungsoptionen

Namespace und Vererbung

Namespace: Microsoft.DirectoryServices

Basistyp: DirectoryObject

Eigenschaften

Die Entität AdministrativeUnit unterstützt die folgenden Eigenschaften:

Deklarierte Eigenschaften

Name	Typ	Create(POST)	Read(GET)	Update(PATCH)	Beschreibung
description	Edm.String	Optional		Optional	Geben Sie eine optionale Beschreibung für die administrative Einheit an.
displayName	Edm.String	Erforderlich	Filterbar	Optional	Der Anzeigename für die administrative Einheit.

Name	Von Multiplizität	An	Zu Multiplizität	Beschreibung
Elemente	*	Benutzer oder Gruppe	*	Der administrativen Einheit zugewiesene Mitglieder. Dies können Benutzer oder Gruppen sein. Wird von DirectoryObject geerbt.
scopedAdministrators	*	ScopedRoleMembership	*	Einer angegebenen Rolle oder angegebenen Rollen zugewiesene Administratoren, die einer administrativen Einheit zugeordnet sind.

Hinweis: Obwohl die Entität DirectoryObject auch andere Navigationseigenschaften unterstützt, z. B. memberOf, owners und ownedObjects, sind diese Eigenschaften für administrative Einheiten nicht gültig. Wenn eine Anforderung für eine dieser Eigenschaften gesendet wird, wird eine Antwort 400 Bad Request mit einer entsprechenden Fehlermeldung zurückgegeben.

Adressierung

Die Adressierung kann eine Sammlung von administrativen Einheiten im Verzeichnis, eine einzelne administrative Einheit oder verwandte Ressourcen umfassen, die über die unterstützten Navigationseigenschaften einer administrativen Einheit verfügbar sind. Bei den Beispielen in der Tabelle wird die Mandantendomäne verwendet, um den Mandanten zu adressieren. Informationen über weitere Methoden zur Adressierung des Mandanten finden Sie unter Adressieren von Entitäten und Vorgängen in der Graph-API.

Artefakt	URL-Fragment	Beispiel
Ressourcensatz (alle administrativen Einheiten)	/administrativeUnits	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`
Einzelne Ressource (d. h. eine administrative Einheit)	/administrativeUnits/{objectId}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta`
Verwandte Ressourcen über eine Navigationseigenschaft	/administrativeUnits/{objectId}/$links/{property-name}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta`

Hinweis: Im obigen Abschnitt über die Navigationseigenschaften finden Sie die Liste der gültigen Navigationseigenschaften, die anstelle von {property-name} verwendet werden können. Entfernen Sie das $links-Segment aus dem Ressourcenpfad des URIs, um die tatsächlichen Objekte zurückzugeben, auf die von einer Navigationseigenschaft verwiesen wird, statt die Links zu ihnen. Sie können eine administrative Einheit auch mithilfe von generischen Verzeichnisobjekten adressieren, indem Sie im Ressourcenpfad des URIs „administrativeUnits“ durch „directoryObjects“ ersetzen.

Umfassendere Informationen zur Abfrage von Verzeichnisobjekten finden Sie unter Allgemeine Abfragen mit der Azure AD Graph-API und Differenzielle Abfragen der Azure AD Graph-API.

Unterstützte Vorgänge – administrativeUnits

In diesem Abschnitt werden die Vorgänge definiert, die für einen administrativeUnits-Ressourcensatz unterstützt werden. Wie bereits erwähnt, ist es wichtig, zunächst die Themen im Abschnitt Übersicht und Voraussetzungen zu lesen, um einige der Graph-API-Grundlagen zu verstehen, die auf alle Entitäten anwendbar sind, z. B. die richtige Formatierung von URLs, die Adressierung von Entitäten und Vorgängen, die Verwendung der Versionsverwaltung usw.

Für jeden der unten aufgeführten Vorgänge gilt:

Der Prinzipal, der den Vorgang ausführt, muss Mitglied in einer Administratorrolle sein, die über Berechtigungen zum Ändern von administrativeUnits-Ressourcen mithilfe von PATCH-, POST- oder DELETE-Anforderungen und über Berechtigungen zum Lesen von Objekten mithilfe von GET-Anforderungen verfügt.
Ersetzen Sie die Platzhalter-Zeichenfolgen „contoso.onmicrosoft.com“ je nach Bedarf durch die Domäne Ihres Azure Active Directory-Mandanten und {objectId} durch die ID des Ressourcentyps, wie in der URL angegeben.
Jede Anforderung muss die folgenden HTTP-Anforderungsheader enthalten, die in der nachfolgenden Tabelle aufgeführt sind.

Anforderungsheader	Beschreibung
Autorisierung	Erforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter Authentifizierungsszenarien für Azure AD.
Content-Type	Erforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
Content-Length	Erforderlich. Die Länge der Anforderung in Bytes.

Die ersten vier unten aufgeführten Vorgänge werden verwendet, um das Erstellen, Abrufen, Aktualisieren und Löschen von AdministrativeUnit-Entitäten zu verwalten. Die danach genannten Vorgänge verwenden die Navigationseigenschaften members und scopedAdministrators, um die Benutzer-/Gruppenmitglieder von AdminstrativeUnit und den Satz zugeordneter Administratoren (über die ScopedRoleMembership-Entität) zu verwalten, die administrative Kontrolle über AdministrativeUnithaben.

Erstellen einer administrativen Einheit

Wird zum Erstellen einer neuen AdministrativeUnitverwendet.

HTTP-Methode	Anforderungs-URI
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`

Der Anforderungstext gibt die erforderliche displayName-Eigenschaft und die optionale description-Eigenschaft an:

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

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Der Antworttext wird dem folgenden ähneln.

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

Abrufen administrativer Einheiten

Wird zum Abrufen einer bestimmten AdministrativeUnit nach {objectId}, einer Teilmenge durch Filtern der displayName-Eigenschaft (siehe Unterstützte Abfragen, Filter und Paginierungsoptionen in der Azure AD Graph-API) oder der Liste aller verfügbaren Einheiten verwendet. Die folgenden Beispiele für Anforderung/Antwort zeigen Abfragen für eine bestimmte administrative Einheit und für alle administrativen Einheiten.

HTTP-Methode	Anforderungs-URI
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`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Der Antworttext wird den folgenden ähneln.

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

Aktualisieren einer administrativen Einheit

Wird zum Aktualisieren einer oder mehrerer Eigenschaften in einer AdministrativeUnit verwendet.

HTTP-Methode	Anforderungs-URI
PATCH	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

Der Anforderungstext gibt eine oder beide der AdministrativeUnit Eigenschaften an:

{ 
  "displayName":"Central Region Administrators"
}

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Es ist keine OData-Antwort im Antworttext vorhanden.

Löschen einer administrativen Einheit

Wird zum Löschen einer AdministrativeUnit verwendet, wie durch {objectId} angegeben.

HTTP-Methode	Anforderungs-URI
LÖSCHEN	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Es ist keine OData-Antwort im Antworttext vorhanden.

Die folgenden Vorgänge werden über die members-Navigationseigenschaft implementiert, die die Verwaltung der Benutzer-/Gruppenmitglieder einer AdminstrativeUnit ermöglicht. Wie bereits erwähnt, ermöglicht es Ihnen das $links-Ressourcensegment, die Zuordnung (d. h. die Verknüpfung) zwischen zwei Ressourcen zu durchlaufen oder zu ändern, z. B. zwischen einer administrativeUnit und einer User- oder Group-Ressource.

Hinzufügen von Mitgliedern zu einer administrativen Einheit

Wird zum Hinzufügen von user- oder group-Ressourcenmitgliedern zu einer AdministrativeUnit verwendet.

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

In diesem Beispiel gibt der Anforderungstext die URL des gewünschten Mitglieds an, das der administrativeUnit hinzugefügt werden soll. In diesem Beispiel handelt es sich um eine users-Ressource. Auch directoryObjects kann anstelle von users als Typressourcensegment verwendet werden, da die User-Entität von der DirectoryObject-Entität geerbt wird. Dies trifft auch bei Verwendung des groups-Ressourcensegments zu.

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

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Es ist keine OData-Antwort im Antworttext vorhanden.

Abrufen von Mitgliedern einer administrativen Einheit

Wird zum Abrufen von user- oder group-Ressourcenmitgliedern einer administrativeUnit verwendet. Beachten Sie, dass Sie zum Abrufen von Mitgliedern eine der unten aufgeführten Formen von GET-Vorgängen verwenden können. Bei der ersten Form wird die URL/der Link des Mitglieds, bei der zweiten werden die Eigenschaften für die Mitglieder zurückgegeben. In beiden Fällen ist das {memberObjectId}-Segment optional, je nachdem, ob der Satz von Mitgliedern oder ein bestimmtes Mitglied zurückgegeben werden soll.

HTTP-Methode	Anforderungs-URI
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`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Das erste Beispiel unten zeigt den Antworttext für einen Vorgang unter Verwendung des $links-Segments für alle Mitglieder (d. h.: {memberObjectId} ist nicht angegeben), wobei zwei Typen von Ressourcen vorhanden sind, User und Group. Das zweite Beispiel zeigt die Antwort für dasselbe Beispiel ohne das $links-Segment.

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

Löschen von Mitgliedern einer administrativen Einheit

Wird zum Löschen von user- oder group-Ressourcenmitgliedern aus einer administrativeGroup-Ressource verwendet. Da die members-Navigationseigenschaft mehrwertig ist, müssen Sie die {objectId} des zu löschenden Mitglieds/Links in der Anforderungs-URL einschließen.

HTTP-Methode	Anforderungs-URI
LÖSCHEN	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Es ist keine OData-Antwort im Antworttext vorhanden.

Administratoren werden einer administrativen Einheit zugewiesen, indem sie in einer Rolle platziert werden, die dieser administrativen Einheit zugeordnet wurde. Die verbleibenden Vorgänge in diesem Abschnitt werden über die scopedAdministrators-Navigationseigenschaft implementiert, die die Verwaltung der Gruppe von Administratoren ermöglicht, die über eine zugeordnete Rolle die administrative Kontrolle über eine AdministrativeUnit haben.

Hinzufügen eines Administrators mit zugeordneter Rolle zu einer administrativen Einheit

Wird verwendet, um einen Administrator zu einer Rolle hinzuzufügen, die einer administrativeUnit zugeordnet wird, über die ScopedRoleMembership-Entität und die scopedAdministrators-Navigationseigenschaft. In diesem Beispiel führt dieser Vorgang zwei Aufgaben aus:

Füllen eines neuen ScopedRoleMembership-Elements (das KEINE adressierbare OData-Ressource ist), das eine Beziehung zwischen einer AdministrativeUnit, einer der administrativen Einheit zugeordneten DirectoryRole und einem Administrator-Benutzer herstellt
Festlegen einer Navigationseigenschaftszuordnung/-verknüpfung zwischen der AdministrativeUnit und dem neuen ScopedRoleMembership-Element.

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

Der Anforderungstext gibt die folgenden Eigenschaften der ScopedRoleMembership-Entität an:

roleObjectId – objectId der gewünschten DirectoryRole. Hinweis: Derzeit sind nur die HelpDeskAdministrators-Rolle und die UserAccountAdministrator-Rolle gültig.
roleMemberInfo – eine Struktur, die die administrative User:objectId – die objectId des administrativen Benutzers – angibt.
objectId – objectId des administrativen Benutzers.

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

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Der Antworttext wird dem folgenden ähneln.

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

Abrufen eines Administrators mit zugeordneter Rolle einer administrativen Einheit

Wird zum Abrufen der Liste der Administratoren in zugeordneten Rollen für eine administrativeUnit-Ressource als ScopedRoleMembership-Entitäten verwendet. Beachten Sie, dass das {scopedRoleMemberId}-Segment optional ist, je nachdem, ob der Satz von Mitgliedern oder ein bestimmtes Mitglied abgerufen werden soll.

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

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Der folgende Antworttext bezieht sich auf eine Abfrage für alle Mitglieder.

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

Löschen eines Administrators mit zugeordneter Rolle einer administrativen Einheit

Wird zum Löschen einer ScopedRoleMembership aus einer administrativeUnit-Ressource verwendet, wie durch das {scopedRoleMemberId}-Segment angegeben.

HTTP-Methode	Anforderungs-URI
LÖSCHEN	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Es ist keine OData-Antwort im Antworttext vorhanden.

Unterstützte Vorgänge – Benutzer und Gruppen

Dieser Abschnitt definiert die neu unterstützten Vorgänge für users- und groups-Ressourcen, die administrativeUnit-Ressourcen unterstützen.

Sehen Sie sich die vollständige Dokumentation für die User-Entität und die Group-Entität und für Vorgänge für Benutzer und Gruppen an.

Für jeden der unten aufgeführten Vorgänge gilt:

Der Prinzipal, der den Vorgang ausführt, muss über Berechtigungen zum Lesen von Objekten mithilfe von GET-Anforderungen verfügen.
Ersetzen Sie die Platzhalter-Zeichenfolgen „contoso.onmicrosoft.com“ je nach Bedarf durch die Domäne Ihres Azure Active Directory-Mandanten und {objectId} durch die ID des Ressourcentyps, wie in der URL angegeben.

Jede Anforderung muss die folgenden HTTP-Anforderungsheader enthalten:

Anforderungsheader	Beschreibung
Autorisierung	Erforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter „Authentifizierungsszenarien für Azure AD“.
Content-Type	Erforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
Content-Length	Erforderlich. Die Länge der Anforderung in Bytes.

Abrufen von administrativen Einheiten, denen ein Benutzer oder eine Gruppe angehört

Die Vorschau ermöglicht das Abrufen der administrativeUnits-Mitgliedschaft für users- und groups-Ressourcen über die memberOf-Navigationseigenschaft für die DirectoryObject-Entität. Geben Sie das users-Ressourcensegment an, um die Mitgliedschaft für users-Ressourcen abzurufen, oder geben Sie „groups“ für groups-Ressourcen an. Geben Sie das $links-Ressourcensegment an, um die Ressourcen-URLs/-Links abzurufen, oder lassen Sie diese Angabe aus, um die Eigenschaften abzurufen.

HTTP-Methode	Anforderungs-URI
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`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Das erste Beispiel unten zeigt den Antworttext für eine users-Ressource mit dem $links-Segment, das über eine Mitgliedschaft bei zwei Typen von Ressourcen verfügt: DirectoryRole und AdministrativeUnit. Das zweite Beispiel zeigt die Antwort für dasselbe Beispiel ohne das $links-Segment.

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

Abrufen von administrativen Einheiten, deren Administrator ein Benutzer ist

Wird zum Abrufen der adminstrativeUnits-Ressource(n) verwendet, deren Administrator ein Benutzer ist, und zwar über die scopedAdministratorOf-Navigationseigenschaft für die User-Entität. Beachten Sie, dass Sie eine der unten aufgeführten Formen von GET-Vorgängen verwenden können. Mit der ersten Form wird die Ressourcen-URL/-Verknüpfung abgerufen, mit der zweiten werden die Eigenschaften zurückgegeben.

HTTP-Methode	Anforderungs-URI
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`

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Das erste Beispiel unten zeigt den Antworttext für einen Vorgang, bei dem das $links-Segment verwendet wird. Das zweite Beispiel zeigt die Antwort für dasselbe Beispiel ohne das $links-Segment.

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

Unterstützte Vorgänge – directoryRoles

Dieser Abschnitt definiert die neu unterstützten Vorgänge für directoryRoles-Ressourcen, die spezifische Unterstützung für administrativeUnits-Ressourcen bieten.

Weitere Informationen zur DirectoryRole-Entität und zu verwandten Vorgängen**** finden Sie in der vollständigen GA-Dokumentation.

Für jeden der unten aufgeführten Vorgänge gilt:

Der Prinzipal, der den Vorgang ausführt, muss über Berechtigungen zum Lesen von Objekten mithilfe von GET-Anforderungen verfügen.
Ersetzen Sie die Platzhalter-Zeichenfolgen „contoso.onmicrosoft.com“ je nach Bedarf durch die Domäne Ihres Azure Active Directory-Mandanten und {objectId} durch die ID des Ressourcentyps, wie in der URL angegeben.
Jede Anforderung muss die folgenden HTTP-Anforderungsheader enthalten: Request HeaderDescriptionAuthorizationRequired. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter „Authentifizierungsszenarien für Azure AD“.Content-TypeRequired. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.Content-LengthRequired. Die Länge der Anforderung in Bytes.

Anforderungsheader	Beschreibung
Autorisierung	Erforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter „Authentifizierungsszenarien für Azure AD“.
Content-Type	Erforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
Content-Length	Erforderlich. Die Länge der Anforderung in Bytes.

Abrufen von Administratoren administrativer Einheiten, die einer bestimmten Rolle zugeordnet sind

Administratoren werden einer administrativen Einheit zugewiesen, indem sie in einer Rolle platziert werden, die dieser administrativen Einheit zugeordnet wurde. Dieser Vorgang ermöglicht es Ihnen, diese „zugeordneten Rollenmitgliedschaften“ für einen Administrator als Satz von scopedRoleMemberships-Ressourcen abzurufen. Beachten Sie, dass nur eine HelpDeskAdministrators-Rolle oder eine UserAccountAdministrator-Rolle {objectId} gültig ist. Beachten Sie auch, dass das {scopedRoleMemberId}-Segment optional ist, je nachdem, ob Sie alle scopedRoleMembership-Ressourcen für eine bestimmte Rolle oder eine spezifische Ressource abrufen möchten.

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

Es gibt keinen Anforderungstext.

Im folgenden Abschnitt HTTP-Antwortreferenz finden Sie Antwortcodedefinitionen. Der folgende Antworttext bezieht sich auf eine Abfrage aller Administratoren einer bestimmten administrativen Einheit, die der Rolle „Helpdesk Administrator“ zugeordnet sind.

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

HTTP-Antwortreferenz

Im Folgenden finden Sie die Liste der möglichen HTTP-Antwortcodes:

HTTP-Statuscode	OData-Fehlercode	Beschreibung
200/OK	Nicht zutreffend	Normale Antwort für eine erfolgreiche Abfrage. Der Antworttext enthält die Daten, die den in den Abfrageparametern angegebenen Filtern entsprechen.
201/Created	Nicht zutreffend	Normale Antwort für einen erfolgreichen POST-/Erstellungsvorgang. Der Antworttext enthält die Daten, mit denen die neue Ressource aufgefüllt ist.
204/No Content	Nicht zutreffend	Normale Antwort für einen erfolgreichen PATCH-/Aktualisierungs- oder DELETE-Vorgang für eine Ressource oder POST für eine verknüpfte Ressource. Der Antworttext enthält keine OData-Antwort.
400/BadRequest	Request_BadRequest	Dies ist eine allgemeine Fehlermeldung für einen ungültigen oder fehlenden Header oder Parameter oder für ungültige oder fehlende Anforderungstextdaten. Dieser Fehler wird auch dann angezeigt, wenn versucht wird, eine bereits vorhandene verknüpfte Ressource hinzuzufügen.
401/Unauthorized	AuthorizationError	Diese Meldung wird angezeigt, wenn der Benutzer nicht autorisiert ist, den Inhalt anzuzeigen. Weitere Informationen zum Sichern von Aufrufen und zum Abrufen und Angeben eines sicheren Zugriffstokens finden Sie im Hauptartikel zu AD Graph-REST.
404/Not Found	Request_ResourceNotFound	Diese Meldung wird angezeigt, wenn die Ressource, auf die Sie zugreifen möchten, nicht vorhanden ist.
405/Method not allowed	Request_BadRequest	Diese Meldung wird angezeigt, wenn Sie versuchen, einen Vorgang durchzuführen, der für eine bestimmte Ressource vorgesehen ist, aber in der Anforderungs-URL die falsche Ressourcen-ID angeben.

Zusätzliche Ressourcen

Informationen zum Verwalten von administrativen Einheiten mithilfe von PowerShell finden Sie im Artikel Verwaltung administrativer Einheiten in Azure AD – öffentliche Vorschau.
Weitere Informationen zu den primitiven OData-Datentypen, die vom EDM verfügbar gemacht werden, finden Sie unter Entity Data Model: Primitive Datentypen.
Referenz zur Azure AD Graph-API

Freigeben über

Administrative Einheiten (Vorschau) | Graph-API-Konzepte

Übersicht und Voraussetzungen

Namespace und Vererbung

Eigenschaften

Deklarierte Eigenschaften

Navigationseigenschaften

Adressierung

Unterstützte Vorgänge – administrativeUnits

Erstellen einer administrativen Einheit

Abrufen administrativer Einheiten

Aktualisieren einer administrativen Einheit

Löschen einer administrativen Einheit

Hinzufügen von Mitgliedern zu einer administrativen Einheit

Abrufen von Mitgliedern einer administrativen Einheit

Löschen von Mitgliedern einer administrativen Einheit

Hinzufügen eines Administrators mit zugeordneter Rolle zu einer administrativen Einheit

Abrufen eines Administrators mit zugeordneter Rolle einer administrativen Einheit

Löschen eines Administrators mit zugeordneter Rolle einer administrativen Einheit

Unterstützte Vorgänge – Benutzer und Gruppen

Abrufen von administrativen Einheiten, denen ein Benutzer oder eine Gruppe angehört

Abrufen von administrativen Einheiten, deren Administrator ein Benutzer ist

Unterstützte Vorgänge – directoryRoles

Abrufen von Administratoren administrativer Einheiten, die einer bestimmten Rolle zugeordnet sind

HTTP-Antwortreferenz

Zusätzliche Ressourcen

Zusätzliche Ressourcen