Table of contents

Administrative Einheiten (Vorschau) | Graph-API-Konzepte

Bryan Lamos|Zuletzt aktualisiert: 07.09.2016
|
1 Mitwirkender

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

Die Funktionen der Azure AD Graph-API sind auch über Microsoft Graph verfügbar. Dies ist eine einheitliche API, die auch APIs von anderen Microsoft-Diensten wie Outlook, OneDrive, OneNote, Planner und Office Graph enthält. Auf alle wird über einen einzigen Endpunkt mit einem einzigen Zugriffstoken zugegriffen. Beachten Sie, dass administrative Einheiten in Microsoft Graph derzeit nicht unterstützt werden. Sie müssen die Azure AD Graph-API für dieses Feature verwenden.

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:

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

  2. Schnellstartanleitung für die Azure AD Graph-API auf Azure.com

  3. Übersicht über die Vorgänge der Graph-API

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

NameTypCreate(POST)Read(GET)Update(PATCH)Beschreibung
descriptionEdm.StringOptionalOptionalGeben Sie eine optionale Beschreibung für die administrative Einheit an.
displayNameEdm.StringErforderlichFilterbarOptionalDer Anzeigename für die administrative Einheit.
NameVon MultiplizitätAnZu MultiplizitätBeschreibung
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.

ArtefaktURL-FragmentBeispiel
Ressourcensatz (alle administrativen Einheiten)/administrativeUnitshttps://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.

AnforderungsheaderBeschreibung
AutorisierungErforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter Authentifizierungsszenarien für Azure AD.
Content-TypeErforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
Content-LengthErforderlich. 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-MethodeAnforderungs-URI
POSThttps://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-MethodeAnforderungs-URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta
GEThttps://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-MethodeAnforderungs-URI
PATCHhttps://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-MethodeAnforderungs-URI
LÖSCHENhttps://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-MethodeAnforderungs-URI
POSThttps://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-MethodeAnforderungs-URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{memberObjectId}?api-version=beta
GEThttps://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-MethodeAnforderungs-URI
LÖSCHENhttps://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:

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

  2. Festlegen einer Navigationseigenschaftszuordnung/-verknüpfung zwischen der AdministrativeUnit und dem neuen ScopedRoleMembership-Element.

HTTP-MethodeAnforderungs-URI
POSThttps://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-MethodeAnforderungs-URI
GEThttps://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-MethodeAnforderungs-URI
LÖSCHENhttps://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:

    AnforderungsheaderBeschreibung
    AutorisierungErforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter „Authentifizierungsszenarien für Azure AD“.
    Content-TypeErforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
    Content-LengthErforderlich. 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-MethodeAnforderungs-URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/$links/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectID}/memberOf?api-version=beta
GEThttps://graph.windows.net/contoso.onmicrosoft.com/groups/{objectID}/$links/memberOf?api-version=beta
GEThttps://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-MethodeAnforderungs-URI
GEThttps://graph.windows.net/contoso.onmicrosoft.com/users/{objectId}/$links/scopedAdministratorOf?api-version=beta
GEThttps://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"
      }
   ]
}
{
   "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.

AnforderungsheaderBeschreibung
AutorisierungErforderlich. Ein Trägertoken, das von Azure Active Directory ausgestellt wird. Weitere Informationen finden Sie unter „Authentifizierungsszenarien für Azure AD“.
Content-TypeErforderlich. Der Medientyp des Inhalts im Anforderungstext, z. B.: application/json.
Content-LengthErforderlich. 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-MethodeAnforderungs-URI
GEThttps://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-StatuscodeOData-FehlercodeBeschreibung
200/OKNicht zutreffendNormale Antwort für eine erfolgreiche Abfrage. Der Antworttext enthält die Daten, die den in den Abfrageparametern angegebenen Filtern entsprechen.
201/CreatedNicht zutreffendNormale Antwort für einen erfolgreichen POST-/Erstellungsvorgang. Der Antworttext enthält die Daten, mit denen die neue Ressource aufgefüllt ist.
204/No ContentNicht zutreffendNormale 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/BadRequestRequest_BadRequestDies 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/UnauthorizedAuthorizationErrorDiese 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 FoundRequest_ResourceNotFoundDiese Meldung wird angezeigt, wenn die Ressource, auf die Sie zugreifen möchten, nicht vorhanden ist.
405/Method not allowedRequest_BadRequestDiese 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

© 2017 Microsoft