Extensiones de esquema de directorio |Conceptos de Graph API

Artículo
01/26/2016

En este tema se describen las extensiones de directorios en la API de Azure AD Graph, que se puede usar para agregar propiedades a los objetos de directorio sin la necesidad de un almacén de datos externos. Por ejemplo, si una organización tiene una aplicación de línea de negocio (LOB) que requiere un usuario de Skype para cada usuario en el directorio, Graph API se puede usar para registrar una nueva propiedad llamada skypeId en el objeto User del directorio y, luego, escribir un valor en la nueva propiedad para un usuario específico. Este tema le ayudará a comprender las limitaciones de las extensiones de los directorios, cómo se registran en un directorio y ejemplos de cómo se usan en Graph API.

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.

Tipos de datos de extensiones

Las extensiones solo se pueden registrar usando Graph API versión 1.5 o posterior. Se pueden registrar los tipos de propiedad siguientes:

Tipo de propiedad	Comentarios
Binary	256 bytes como máximo.
Boolean
DateTime	Debe especificarse en formato ISO 8601. Se almacenará en formato UTC.
Entero	Valor de 32 bits.
LargeInteger	Valor de 64 bits.
String	256 caracteres como máximo.

Los tipos de propiedad anteriores se pueden registrar en los objetos siguientes en un directorio:

Descripción de cómo registrar una extensión

Es importante comprender cómo se registra la propiedad de una extensión en un directorio y cómo afecta a su registro el modelo de consentimiento de Azure AD. Para más información sobre el consentimiento de aplicación en Azure AD, consulte Información general sobre el marco de consentimiento en Integración de aplicaciones con Azure Active Directory.

Las propiedades de extensión se registran en un objeto Application en el directorio del desarrollador. Después de que la aplicación ha sido aceptada por un usuario o un administrador en el directorio del desarrollador, la propiedad se agrega al tipo de directorio de destino y pasa a estar accesible inmediatamente en el directorio del desarrollador. En el caso de una aplicación de varios inquilinos, cuando un usuario o un administrador de otra organización otorga el consentimiento a la aplicación, se obtiene acceso inmediato a las propiedades de la extensión en el tipo de directorio de destino en el directorio de la otra organización.

Si una organización da su consentimiento para permisos de “solo lectura” para una aplicación con extensiones registradas, aún se podrá acceder a las propiedades en el directorio de la otra organización. Además, cualquier aplicación con consentimiento de una organización puede tener acceso a las propiedades de extensión, no solo la aplicación en la que se registran. Otras aplicaciones con consentimiento en esa organización pueden leer o escribir valores para la nueva propiedad de extensión si tienen permisos suficientes.

Si se elimina la aplicación o se quita el consentimiento en el directorio de la otra organización, la propiedad de extensión deja de estar accesible en el objeto de directorio de destino. Si la aplicación elimina la extensión, también deja de estar accesible en el objeto de directorio de destino. Si una aplicación de varios inquilinos agrega propiedades de extensión adicionales después de haberse otorgado el consentimiento, estas propiedades pasan a estar accesibles de inmediato en el directorio de la otra organización.

Nota: Si el valor de una propiedad de extensión se establece en un objeto y esa propiedad deja de estar accesible en el directorio de ese objeto, la propiedad sigue contando para el límite de 100 valores de propiedad de extensión de ese objeto. La única forma de quitar el valor de propiedad de la consideración una vez que se ha establecido es establecerlo explícitamente en null. No puede hacer esto si la propiedad de extensión no está accesible.

Escenario de ejemplo

Considere el siguiente escenario: Litware es un proveedor de software independiente (ISV) que ha desarrollado una aplicación SaaS para que la utilicen otras organizaciones y esta aplicación requiere una propiedad de extensión llamada skypeId en un objeto User. En primer lugar, Litware registra la aplicación en su propio directorio y, después, llama a Graph API para registrar la propiedad de extensión en el objeto Application, que hace que se pueda acceder a la propiedad en los objetos User en el directorio de Litware. Finalmente, Litware hace que la aplicación sea compatible con varios inquilinos para que otras organizaciones puedan utilizarla.

Contoso quiere utilizar la aplicación SaaS de Litware, por lo que un usuario o administrador de Contoso da su consentimiento para la aplicación. Tras el consentimiento, la aplicación se registra en el directorio de Contoso y las propiedades de extensión registradas para la aplicación por Litware están inmediatamente disponibles en el directorio de Contoso. Dado que la propiedad de extensión skypeId para un objeto User se registra en la aplicación por Litware, se puede tener acceso a la propiedad en los objetos User, en el directorio de Contoso. La aplicación de Litware u otras aplicaciones con consentimiento en el directorio de Contoso ahora pueden tener acceso a la nueva propiedad de acuerdo con los permisos configurados para esa aplicación en el directorio de Contoso. Esto significa que las aplicaciones, según sus permisos, pueden escribir un valor para esa propiedad de extensión en uno o varios usuarios en el directorio. Solo los usuarios para los que se ha escrito un valor skypeId devolverán esa propiedad en su objeto User. Esto será así hasta que la propiedad skypeId se establezca en null, tras lo cual el objeto User para ese usuario ya no devolverá la propiedad.

Solicitudes REST de ejemplo para extensiones de directorio

Las solicitudes de ejemplo siguientes le muestran cómo registrar, ver, escribir, leer, filtrar y cancelar el registro de extensiones en su directorio. Reemplace el marcador de posición <applicationObjectId> por el id. de objeto de la aplicación registrada. Puede obtener este valor de la siguiente manera:

Vaya a https://graphexplorer.cloudapp.net/, haga clic en el vínculo Sign In (Iniciar sesión) que encontrará en la esquina superior derecha e inicie sesión con las credenciales de una cuenta de administrador del directorio de su organización.
Una vez que haya iniciado sesión, haga clic en la dirección URL en el cuadro de texto del recurso (junto al botón GET (OBTENER)), seleccione la dirección URL que termina en applications/ y, luego, haga clic en GET (OBTENER) o en la tecla Intro.
Busque la entrada de la aplicación que desee en los resultados y, luego, copie su valor objectId, como el siguiente: "objectId": "269fc2f7-6420-4ea4-be90-9e1f93a87a64"

En esta sección, hay solicitudes de ejemplo para las siguientes operaciones:

Registrar una extensión
Ver extensiones registradas
Escribir un valor de extensión
Quitar un valor de extensión
Leer un valor de extensión
Filtrar un valor de extensión
Cancelar el registro de una extensión

Para obtener ejemplos completos que usan propiedades de extensión, consulte los siguientes ejemplos en los ejemplos de Azure AD en Github:

WebApp-GraphAPI-DirectoryExtensions-PHP: Muestra cómo crear y utilizar extensiones con PHP.
WebApp-GraphAPI-DirectoryExtensions-DotNet: Muestra un gráfico de organización de inquilinos AAD y permite leer valores de extensión desde el comienzo.

Registrar una extensión

La solicitud de ejemplo siguiente crea extensionProperty en el objeto Application deseado.

Formato de solicitud

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

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

Solicitud de ejemplo

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

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

Si la operación fue correcta, devolverá un código de estado HTTP 201 Creado junto con el nombre completo de la propiedad de extensión, que se puede utilizar para escribir valores en el tipo de destino.

Respuesta de ejemplo

HTTP/1.1 201 Created
...

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

Ver extensiones registradas

La solicitud de ejemplo siguiente obtiene las extensiones que se registran en su objeto Application.

Formato de solicitud

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

Solicitud de ejemplo

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

Si la operación fue correcta, devolverá un código de estado HTTP 200 CORRECTO junto con toda la información sobre cada propiedad de extensión registrada en el objeto Application.

Respuesta de ejemplo

HTTP/1.1 200 OK
...

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

Escribir un valor de extensión

La solicitud de ejemplo siguiente escribe un valor de extensión para la propiedad de extensión *skypeId^ en un objeto User.

Formato de solicitud

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

{
    "<extensionPropertyName>": <value>
}

Solicitud de ejemplo

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

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": "jimbob.skype"
}

Si la operación fue correcta, devolverá un código de estado HTTP 204 Sin contenido.

Respuesta de ejemplo

HTTP/1.1 204 No Content

Si el intento de escritura supera el límite del valor de extensión de 100 para el objeto, devolverá una respuesta HTTP 403 Prohibido con un código de error de "Directory_ResourceSizeExceeded" y el mensaje siguiente: “El tamaño del objeto superó su límite. Reduzca el número de valores y vuelva a intentar la solicitud.".

Quitar un valor de extensión

La solicitud de ejemplo siguiente quita un valor de extensión que se ha configurado anteriormente para la propiedad de extensión skypeId en un objeto User al establecer el valor en null.

Formato de solicitud

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

{
    "<extensionPropertyName>": null
}

Solicitud de ejemplo

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

{
    "extension_ab603c56068041afb2f6832e2a17e237_skypeId": null
}

Si la operación fue correcta, devolverá un código de estado HTTP 204 Sin contenido.

Respuesta de ejemplo

HTTP/1.1 204 No Content

Leer un valor de extensión

La solicitud de ejemplo siguiente realiza una operación GET sencilla en el usuario, lo que devolverá los valores de propiedad estándar, así como el nuevo valor de propiedad de extensión.

Formato de solicitud

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

Solicitud de ejemplo

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

Si la operación fue correcta, devolverá un código de estado HTTP 200 OK junto con el nuevo valor de la propiedad de extensión (muchas propiedades de usuario se han quitado de la respuesta de ejemplo para ser concisos).

Respuesta de ejemplo

HTTP/1.1 200 OK

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

Filtrar un valor de extensión

La solicitud de ejemplo siguiente filtra los usuarios según el valor de propiedad de extensión especificado.

Nota: Las búsquedas de prefijos en extensiones están limitadas a 71 caracteres para búsquedas de cadenas y a 207 bytes para búsquedas en extensiones binarias.

Formato de solicitud

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

Solicitud de ejemplo

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

Si la operación fue correcta, devolverá un código de estado HTTP 200 OK, junto con el objeto de usuario resultante.

Respuesta de ejemplo

HTTP/1.1 200 OK

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

Cancelar el registro de una extensión

La solicitud de ejemplo siguiente cancela el registro de una propiedad de extensión al realizar una operación DELETE en el identificador de objeto de la extensión.

Formato de solicitud

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

Solicitud de ejemplo

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

Si la operación fue correcta, devolverá un código de estado HTTP 204 Sin contenido, y se cancelará el registro de la propiedad de extensión en la aplicación.

Respuesta de ejemplo

HTTP/1.1 204 No Content

Limitaciones y comportamiento de la extensión

El comportamiento y las limitaciones siguientes se aplican a las propiedades de extensión en un directorio:

Las propiedades de extensión registradas para una aplicación pasan a estar disponibles en un directorio cuando un usuario o administrador del directorio da su consentimiento para la aplicación.
Después de que una propiedad de extensión pase a estar disponible en un directorio, cualquier aplicación con consentimiento puede leer o escribir un valor para esa propiedad de extensión para cualquiera de los objetos para los que esa propiedad se aplica según los permisos de esa aplicación en el directorio. Los objetos para los que se aplica la propiedad de extensión se especifican en la propiedad targetObjects.
Se puede escribir un máximo de 100 valores de propiedad de extensión en un objeto específico en un directorio. Por ejemplo, suponiendo que no se han escrito otros valores de propiedad de extensión en ningún usuario en un directorio, si una aplicación escribe un valor de propiedad de extensión en user1, esa aplicación u otra con los permisos adecuados puede escribir valores para otras 99 propiedades de extensión en user1; sin embargo, otros usuarios del directorio todavía podrán tener hasta 100 valores de propiedad de extensión escritos en ellos.
Si una aplicación intenta establecer un valor para una propiedad de extensión adicional en un objeto para el que ya se han establecido 100 valores de propiedad de extensión, Graph API devuelve una respuesta 403 Prohibido con un código de error de "Directory_ResourceSizeExceeded" y el siguiente mensaje: “El tamaño del objeto superó su límite. Reduzca el número de valores y vuelva a intentar la solicitud.".
Si un desarrollador anula el registro (elimina) de una propiedad de extensión desde una aplicación, esa propiedad de extensión deja de estar accesible inmediatamente en el directorio del desarrollador y también en directorios para los que se ha concedido consentimiento a la aplicación.
Si la aplicación se quita del directorio del desarrollador, todas las propiedades de extensión registradas en esa aplicación dejan de estar accesibles inmediatamente en el directorio del desarrollador y en los directorios en los que ha concedido consentimiento a esa aplicación.
Si se ha concedido consentimiento a una aplicación multiempresa en un directorio y posteriormente se anula el registro (quita) de esa aplicación de ese directorio (por ejemplo, por un administrador mediante el Portal de administración de Azure), entonces cualquier propiedad de extensión registrada en esa aplicación deja de estar accesible inmediatamente en ese directorio.
Un valor de propiedad de extensión se debe establecer explícitamente en null para quitarse de un objeto de directorio. Si se establece un valor de propiedad de extensión en un objeto de directorio y esa propiedad de extensión deja de estar accesible en el directorio por cualquiera de los motivos citados anteriormente, entonces la propiedad de extensión ya no será visible en ese objeto de directorio. Sin embargo, seguirá teniéndose en cuenta para el límite del valor de propiedad de extensión de 100 para ese objeto. Hasta que la disponibilidad de la propiedad de extensión se restaure (por ejemplo, en algunos casos, dando consentimiento a la aplicación de nuevo), el valor no será accesible para lectura ni escritura.

Recursos adicionales

Referencia de la API de Azure AD Graph

Compartir a través de

Extensiones de esquema de directorio |Conceptos de Graph API

Tipos de datos de extensiones

Descripción de cómo registrar una extensión

Escenario de ejemplo

Solicitudes REST de ejemplo para extensiones de directorio

Registrar una extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Ver extensiones registradas

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Escribir un valor de extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Quitar un valor de extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Leer un valor de extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Filtrar un valor de extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Cancelar el registro de una extensión

Formato de solicitud

Solicitud de ejemplo

Respuesta de ejemplo

Limitaciones y comportamiento de la extensión

Recursos adicionales

Recursos adicionales