Unidades administrativas (versión preliminar) | Conceptos de Graph API

Artículo
06/09/2016

Se aplica a: Graph API | Azure Active Directory (AD)

Información general y requisitos previos

Una unidad administrativa proporciona un contenedor conceptual para objetos de directorio User y Group, habilitando permisos para delegar en una granularidad más fina (es decir, departamental, regional, etc.), a roles administrativos cuyo ámbito es la unidad administrativa. En este tema se ofrecen descripciones de las propiedades declaradas y las propiedades de navegación expuestas por la entidad AdministrativeUnit, así como las operaciones y funciones que se pueden llamar en el recurso de OData administrativeUnits.

Importante

Se recomienda encarecidamente que use Microsoft Graph en lugar de la API de Azure AD Graph para acceder a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.

También es necesario estar familiarizado con la configuración de autenticación y aplicación de Azure AD antes de utilizar la versión preliminar de la unidad administrativa. Si no está familiarizado con los conceptos asociados a la autenticación de Azure AD y/o con los pasos de configuración necesarios para permitir a una aplicación acceder al inquilino, revise el artículo Escenarios de autenticación de Azure AD, concretamente la sección titulada Conceptos básicos sobre el registro de una aplicación en Azure AD que contiene un vínculo a un artículo más detallado: Integración de aplicaciones con Azure Active Directory

Consulte el artículo principal API de Azure Active Directory Graph en Azure.com y en siguiente lista de artículos de Graph API para obtener información adicional importante y útil antes de continuar con las siguientes secciones:

Control de versiones de la API de Azure AD Graph

Importante: La característica Unidad administrativa solo está disponible en la versión preliminar en este momento. Para poder utilizar las características de la versión preliminar, asegúrese de establecer el parámetro de cadena de consulta api-version en “beta”, es decir: https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta

Puede crear y usar unidades administrativas solo si habilita Azure Active Directory Premium. Para más información, consulte Introducción a Azure Active Directory Premium.
Guía de inicio rápido de la API de Azure AD Graph en Azure.com
Información general de las operaciones de Graph API
Consultas, filtros y opciones de paginación admitidos

Espacio de nombres y herencia

Espacio de nombres: Microsoft.DirectoryServices

Tipo base: DirectoryObject

Propiedades

La entidad AdministrativeUnit admite las siguientes propiedades:

Propiedades declaradas

Nombre	Tipo	Create(POST)	Read(GET)	Update(PATCH)	Descripción
description	Edm.String	Opcional		Opcional	Descripción opcional para la unidad administrativa.
displayName	Edm.String	Requerido	Filtrable	Opcional	Nombre para mostrar para la unidad administrativa.

Nombre	Multiplicidad de origen	Para	Para multiplicidad	Descripción
miembros	*	Usuario o grupo	*	Miembros asignados a la unidad administrativa, que pueden ser User o Group. Se hereda de DirectoryObject.
scopedAdministrators	*	ScopedRoleMembership	*	Administradores asignados a roles dados, cuyo ámbito es una unidad administrativa.

Nota: Aunque la entidad DirectoryObject también admite otras propiedades de navegación, incluidas memberOf, owners y ownedObjects, estas propiedades no son válidas para la unidad administrativa. Si se envía una solicitud para cualquiera de estas propiedades, se devuelve una respuesta 400 - Solicitud incorrecta con el mensaje de error correspondiente.

Direccionamiento

El direccionamiento puede abarcar una colección de unidades administrativas en el directorio, una unidad administrativa individual o recursos relacionados disponibles a través de las propiedades de navegación compatibles de una unidad administrativa. En los ejemplos de la tabla se utiliza el dominio del inquilino para dirigirse al inquilino. Para conocer otras maneras de dirigirse al inquilino, consulte Dirigirse a entidades y operaciones en Graph API.

Artefacto	Fragmento de dirección URL	Ejemplo
Conjunto de recursos (todas las unidades administrativas)	/administrativeUnits	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`
Recurso único (es decir, una unidad administrativa)	/administrativeUnits/{objectId}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde?api-version=beta`
Recursos relacionados a través de una propiedad de navegación	/administrativeUnits/{objectId}/$links/{property-name}	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=beta`

Nota: Consulte la sección Propiedades de navegación anterior para ver la lista de propiedades de navegación válidas que se pueden usar en lugar de {property-name}. Quite el segmento "$links" de la parte de la ruta de acceso al recurso del URI para devolver los objetos reales a los que hace referencia una propiedad de navegación en lugar de los vínculos a ellos. También puede dirigirse a una unidad administrativa mediante objetos de directorio genéricos, reemplazando "administrativeUnits" por "directoryObjects" en la parte de la ruta de acceso al recurso del URI.

Para información más completa sobre cómo consultar objetos de directorio, consulte Azure AD Graph API Common Queries (Consultas comunes de la API Graph de Azure AD) y Azure AD Graph API Differential Query (Consulta diferencial de la API Graph de Azure AD).

Operaciones admitidas: administrativeUnits

Esta sección define las operaciones admitidas en un conjunto de recursos administrativeUnits. Como se mencionó anteriormente, es importante revisar primero los temas de la sección Información general y requisitos previos para entender algunos de los conceptos básicos de Graph API que se aplican a todas las entidades, como el formato correcto de direcciones URL, entidades y operaciones de direccionamiento, uso de control de versiones, etc.

Para cada una de las operaciones enumeradas siguientes:

La entidad de seguridad que realiza la operación debe estar en un rol de administrador que tenga privilegios para modificar recursos administrativeUnits mediante solicitudes PATCH, POST o DELETE, y privilegios para leer objetos mediante solicitudes GET.
Según corresponda, reemplace las cadenas de marcador de posición “contoso.onmicrosoft.com” por el dominio de su inquilino de Azure Active Directory y {objectId} por el identificador del tipo de recurso determinado en la dirección URL.
Cada solicitud debe incluir los siguientes encabezados de solicitud HTTP en la tabla siguiente.

Encabezado de solicitud	Descripción
Autorización	Obligatorio. Un token de portador emitido por Azure Active Directory. Consulte Escenarios de autenticación para Azure AD para obtener más información.
Content-Type	Obligatorio. El tipo de medio del contenido en el cuerpo de la solicitud, por ejemplo, application/json.
Content-Length	Obligatorio. La longitud de la solicitud en bytes.

Las primeras cuatro operaciones enumeradas a continuación se usan para administrar la creación, recuperación, actualización y eliminación de entidades AdministrativeUnit. Las operaciones posteriores utilizan las propiedades de navegación members y scopedAdministrators para administrar los miembros User y Group de AdminstrativeUnit, y el conjunto de administradores de ámbito (a través de la entidad ScopedRoleMembership) que tienen control administrativo de AdministrativeUnit, respectivamente.

Creación de una unidad administrativa

Se usa para crear una nueva entidad AdministrativeUnit.

Método HTTP	URI de solicitud
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits?api-version=beta`

El cuerpo de la solicitud especifica las propiedades displayName (requerida) y description (opcional):

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

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El cuerpo de la respuesta será similar al siguiente.

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

Obtención de unidades administrativas

Se usa para recuperar una AdministrativeUnit determinada por {objectId}, un subconjunto filtrando por la propiedad displayName (consulte Supported Queries, Filters, and Paging Options in Azure AD Graph API (Consultas, filtros y opciones de paginación compatibles en la API Graph de Azure AD)), o la lista de todas las disponibles. Los ejemplos de solicitud y respuesta siguientes muestran las consultas para una unidad administrativa determinada y para todas las unidades administrativas, respectivamente.

Método HTTP	URI de solicitud
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`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El cuerpo de la respuesta será similar a uno de los siguientes.

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

Actualización de una unidad administrativa

Se usa para actualizar una o varias de las propiedades de una AdministrativeUnit.

Método HTTP	URI de solicitud
PATCH	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

El cuerpo de la solicitud especifica una o las dos propiedades de AdministrativeUnit:

{ 
  "displayName":"Central Region Administrators"
}

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. No hay ninguna respuesta de OData en el cuerpo de la respuesta.

Eliminación de una unidad administrativa

Se usa para eliminar una AdministrativeUnit, tal y como especifica {objectId}.

Método HTTP	URI de solicitud
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}?api-version=beta`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. No hay ninguna respuesta de OData en el cuerpo de la respuesta.

Las siguientes operaciones se implementan a través de la propiedad de navegación members, que proporciona administración de los miembros User y Group de una AdminstrativeUnit. Recuperado de antes, el segmento de recurso $links permite recorrer o modificar la asociación (también conocida como vínculo) entre los dos recursos, como entre un elemento administrativeUnit y un recurso User o Group.

Incorporación de miembros a una unidad administrativa

Se usa para agregar miembros de recurso user o group a una AdministrativeUnit.

Método HTTP	URI de solicitud
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/?api-version=beta`

En este ejemplo, el cuerpo de solicitud especifica la dirección URL para el miembro deseado que queremos a agregar a la administrativeUnit, que es un recurso users en este ejemplo. También es válido usar directoryObjects como el segmento de recurso de tipo, en lugar de users, ya que la entidad User se hereda de la entidad DirectoryObject. Lo mismo se aplica cuando se usa el segmento de recurso groups.

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

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. No hay ninguna respuesta de OData en el cuerpo de la respuesta.

Obtención de miembros de una unidad administrativa

Se usa para recuperar miembros de recurso user o group de una administrativeUnit. Tenga en cuenta que puede recuperar miembros mediante cualquiera de las formas de las operaciones GET enumeradas a continuación. La primera devuelve la dirección URL o el vínculo a los miembros, mientras que la segunda devuelve las propiedades de los miembros. En ambos casos, el segmento {memberObjectId} es opcional, dependiendo de si desea el conjunto de miembros devuelto o uno específico.

Método HTTP	URI de solicitud
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`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El primer ejemplo siguiente muestra el cuerpo de la respuesta para una operación que usa el segmento $links para todos los miembros (es decir: {memberObjectId} no se especifica), donde existen dos tipos de recursos: User y Group. El segundo muestra la respuesta para el mismo ejemplo, sin el 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     
      }
   ]
}

Eliminación de miembros de una unidad administrativa

Se usa para eliminar miembros de recurso user o group de un recurso administrativeGroup. Dado que members es una propiedad de navegación de varios valores, debe incluir el segmento {objectId} del miembro o vínculo que desea eliminar en la dirección URL de solicitud.

Método HTTP	URI de solicitud
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/$links/members/{objectId}?api-version=beta`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. No hay ninguna respuesta de OData en el cuerpo de la respuesta.

Los administradores se asignan a una unidad administrativa colocándolos en un rol al que se le ha dado un ámbito en esa unidad administrativa. Las operaciones restantes de esta sección se implementan a través de la propiedad de navegación scopedAdministrators, que proporciona administración de los administradores establecidos que tienen control administrativo de una AdministrativeUnit, a través de un rol con ámbito.

Incorporación de un administrador de rol con ámbito a una unidad administrativa

Se usa para agregar un administrador a un rol que tendrá un ámbito en una administrativeUnit, a través de la entidad ScopedRoleMembership y la propiedad de navegación scopedAdministrators. En este ejemplo, la operación hace dos cosas:

Rellena un nuevo elemento ScopedRoleMembership (que NO es un recurso de OData direccionable), que establece una relación entre una AdministrativeUnit, un DirectoryRole con ámbito en la unidad administrativa y un User de administrador.
Establece un vínculo o una asociación de propiedad de navegación entre la AdministrativeUnit y el nuevo elemento ScopedRoleMembership.

Método HTTP	URI de solicitud
POST	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators?api-version=beta`

El cuerpo de la solicitud especifica las siguientes propiedades de la entidad ScopedRoleMembership:

roleObjectId: Identificador de objeto de DirectoryRole que se desea. Nota: Actualmente solo los roles HelpDeskAdministrators y UserAccountAdministrator son válidos.
roleMemberInfo: Una estructura que identifica el User:objectId administrativo (Identificación de usuario del usuario administrativo).
objectId: Identificación de usuario del usuario administrativo.

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

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El cuerpo de la respuesta será similar al siguiente.

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

Obtención de un administrador de rol con ámbito de una unidad administrativa

Se usa para obtener la lista de administradores en roles con ámbito para un recurso administrativeUnit, como entidades ScopedRoleMembership. Tenga en cuenta que el segmento {scopedRoleMemberId} es opcional, dependiendo de si desea el conjunto de miembros o uno específico.

Método HTTP	URI de solicitud
GET	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El cuerpo de respuesta siguiente es para una consulta para todos los miembros.

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

Eliminación de un rol de administrador con ámbito de una unidad administrativa

Se usa para eliminar un ScopedRoleMembership de un recurso administrativeUnit, especificado por el segmento {scopedRoleMemberId}.

Método HTTP	URI de solicitud
DELETE	`https://graph.windows.net/contoso.onmicrosoft.com/administrativeUnits/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. No hay ninguna respuesta de OData en el cuerpo de la respuesta.

Operaciones admitidas: usuarios y grupos

Esta sección define las operaciones recién admitidas en recursos users y groups, que proporcionan compatibilidad para recursos administrativeUnit.

Puede consultar la documentación completa de disponibilidad general para las entidades User y Group, y para operaciones en users y groups.

Para cada una de las operaciones enumeradas siguientes:

La entidad de seguridad que realiza la operación debe tener privilegios para leer objetos mediante solicitudes GET.
Según corresponda, reemplace las cadenas de marcador de posición “contoso.onmicrosoft.com” por el dominio de su inquilino de Azure Active Directory y {objectId} por el identificador del tipo de recurso determinado en la dirección URL.

Cada solicitud debe incluir los siguientes encabezados de solicitud HTTP:

Encabezado de solicitud	Descripción
Autorización	Obligatorio. Un token de portador emitido por Azure Active Directory. Consulte Escenarios de autenticación para Azure AD para obtener más información.
Content-Type	Obligatorio. El tipo de medio del contenido en el cuerpo de la solicitud, por ejemplo, application/json.
Content-Length	Obligatorio. La longitud de la solicitud en bytes.

Obtención de unidades administrativa a las que pertenece un usuario o grupo

La versión preliminar permite la recuperación de la pertenencia de administrativeUnits para recursos users y groups a través de la propiedad de navegación memberOf en la entidad DirectoryObject entidad. Especifique el segmento de recurso “users” para recuperar la pertenencia de para recursos users o “groups” para recursos groups. Especifique el segmento de recurso "$links" para recuperar las direcciones URL o los vínculos del recurso, u omítalo para recuperar las propiedades.

Método HTTP	URI de solicitud
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`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El primer ejemplo siguiente muestra el cuerpo de la respuesta para un recurso users con el segmento $links, que tiene pertenencia en dos tipos de recursos: DirectoryRole y AdministrativeUnit. El segundo muestra la respuesta para el mismo ejemplo, sin el 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"
      }    
   ]  
}

Obtención de unidades administrativas de las que un usuario es administrador

Se usa para recuperar los recursos adminstrativeUnits de los que un usuario es administrador mediante la propiedad de navegación scopedAdministratorOf en la entidad User. Tenga en cuenta que puede usar cualquiera de las formas de las operaciones GET enumeradas a continuación. La primera recupera las direcciones URL o el vínculo del recurso y la segunda devuelve las propiedades.

Método HTTP	URI de solicitud
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`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El primer ejemplo muestra el cuerpo de la respuesta para una operación mediante el segmento $links. El segundo muestra la respuesta para el mismo ejemplo, sin el 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
         }
      }
   ]  
}

Operaciones admitidas: directoryRoles

Esta sección define las operaciones recién admitidas en recursos directoryRoles, que proporcionan compatibilidad específica para recursos administrativeUnits.

Puede consultar la documentación completa de disponibilidad general para obtener más información sobre la entidad DirectoryRole y las operaciones**** relacionadas.

Para cada una de las operaciones enumeradas siguientes:

La entidad de seguridad que realiza la operación debe tener privilegios para leer objetos mediante solicitudes GET.
Según corresponda, reemplace las cadenas de marcador de posición “contoso.onmicrosoft.com” por el dominio de su inquilino de Azure Active Directory y {objectId} por el identificador del tipo de recurso determinado en la dirección URL.
Cada solicitud debe incluir los siguientes encabezados de solicitud HTTP: Encabezado de solicitud Descripción Authorization Requerido. Un token de portador emitido por Azure Active Directory. Consulte Escenarios de autenticación para Azure AD para obtener más información. Content-Type Requerido. El tipo de medio del contenido en el cuerpo de la solicitud, por ejemplo, application/json. Content-Length Requerido. La longitud de la solicitud en bytes.

Encabezado de solicitud	Descripción
Autorización	Obligatorio. Un token de portador emitido por Azure Active Directory. Consulte Escenarios de autenticación para Azure AD para obtener más información.
Content-Type	Obligatorio. El tipo de medio del contenido en el cuerpo de la solicitud, por ejemplo, application/json.
Content-Length	Obligatorio. La longitud de la solicitud en bytes.

Obtención de administradores de unidades administrativas con ámbito en un rol específico

Los administradores se asignan a una unidad administrativa colocándolos en un rol al que se le ha dado un ámbito en esa unidad administrativa. Esta operación permite recuperar esos "ámbito de función de la cuenta" para que un administrador, como un conjunto de scopedRoleMemberships recursos. Tenga en cuenta que solo es válido un segmento {objectId} de rol “HelpDeskAdministrators” o “UserAccountAdministrator”. Tenga en cuenta también que el segmento {scopedRoleMemberId} es opcional, dependiendo de si desea todos los recursos scopedRoleMembership para un rol específico o un recurso concreto.

Método HTTP	URI de solicitud
GET	`https://graph.windows.net/contoso.onmicrosoft.com/directoryRoles/{objectId}/scopedAdministrators/{scopedRoleMemberId}?api-version=beta`

No hay ningún cuerpo de solicitud.

Consulte la sección Referencia de la respuesta HTTP a continuación para obtener definiciones de código de respuesta. El cuerpo de la respuesta siguiente es para una consulta para todos los administradores de una unidad administrativa determinada, con ámbito en el rol HelpdeskAdministrators.

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

Referencia de la respuesta HTTP

A continuación se muestra la lista de posibles códigos de respuesta HTTP:

Código de estado HTTP	Código de error de OData	Descripción
200/Correcto	n/a	Respuesta normal para una consulta correcta. El cuerpo de respuesta contendrá los datos que coincidan con los filtros especificados en los parámetros de la consulta.
201/Creado	n/a	Respuesta normal para una operación POST/create correcta. El cuerpo de la respuesta contendrá los datos tal y como se rellenan en el nuevo recurso.
204/Sin contenido	n/a	Respuesta normal para una operación PATCH/update o DELETE correcta en un recurso, o POST en un recurso vinculado. El cuerpo de la respuesta no contendrá una respuesta de OData.
400/Solicitud incorrecta	Request_BadRequest	Se trata de un mensaje de error genérico para un encabezado, parámetro o datos del cuerpo de la solicitud ausentes o no válidos. También verá este error si intenta agregar un recurso vinculado que ya existe.
401/No autorizado	AuthorizationError	Se mostrará cuando el usuario no está autorizado para ver el contenido. Consulte el artículo principal de REST Graph de AD para obtener detalles adicionales sobre protección de las llamadas y la obtención y especificación de un token de acceso seguro.
404/No encontrado	Request_ResourceNotFound	Se mostrará cuando el recurso al que está intentando acceder no existe.
405/Método no permitido	Request_BadRequest	Se mostrará cuando intenta una operación pensada para un recurso específico, pero no proporciona el identificador de recurso correcto en la dirección URL de la solicitud.

Recursos adicionales

Para obtener más información sobre cómo administrar unidades administrativas mediante PowerShell, visite el artículo Administración de unidades administrativas en Azure AD: versión preliminar pública.
Para más información sobre los tipos de datos primitivos de OData expuestos por el EDM, consulte Entity Data Model: Tipos de datos primitivos.
Referencia de la API de Azure AD Graph