Agregar datos personalizados a los recursos mediante extensionesAdd custom data to resources using extensions

Microsoft Graph proporciona un único punto de conexión de API que le da acceso a información y datos centrados en personas enriquecidos a través de varios recursos como user y message. También puede extender Microsoft Graph con sus propios datos de aplicación. Puede agregar propiedades personalizadas a los recursos de Microsoft Graph sin necesidad de un almacén de datos externo.Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights through a number of resources such as user and message. You can also extend Microsoft Graph with your own application data. You can add custom properties to Microsoft Graph resources without requiring an external data store.

Por ejemplo, puede que no desee que su aplicación ocupe mucho espacio y almacenar datos específicos del usuario específico de la aplicación en Microsoft Graph extendiendo el recurso user.For example, you might decide to keep your app lightweight and store app-specific user profile data in Microsoft Graph by extending the user resource. O puede que desee conservar el perfil de usuario existente en su aplicación y simplemente agregar un identificador de almacenamiento específico de aplicación al recurso user.Alternatively, you might want to retain your app’s existing user profile store, and simply add an app-specific store identifier to the user resource.

Microsoft Graph ofrece dos tipos de extensiones. Elija el tipo de extensión que mejor se adapte a sus necesidades de aplicación:Microsoft Graph offers two types of extensions. Choose the extension type that best suits your application needs:

  • Extensiones abiertas: Una buena manera para que los desarrolladores empiecen a trabajar.Open extensions: A good way for developers to get started.
  • Extensiones de esquema: Un mecanismo más versátil para los desarrolladores que se preocupan por el almacenamiento de datos escritos, que hace su esquema reconocible y compartible, y les permitirá en el futuro realizar la autorización y validación de datos de entrada.Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future, being able to perform input data validation and authorization.

Importante: No debe utilizar extensiones para almacenar información de identificación personal confidencial, como credenciales de cuenta, números de identificación gubernamentales, información de propietarios de tarjetas de crédito, datos de cuentas bancarias, información médica o antecedentes delicados.Important: You should not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.

Recursos admitidosSupported resources

En la tabla siguiente, se enumeran los recursos que admiten extensiones abiertas y de esquema, y se indica si tienen un estado de disponibilidad general (GA) (disponibles en los puntos de conexión beta y v1.0) o si están en versión preliminar (disponibles solo en el punto de conexión beta).The following table lists the resources that support open and schema extensions, and indicates whether they have reached general availability (GA - available in both the v1.0 and beta endpoints) or are in preview (available only in the beta endpoint).

RecursoResource Extensiones abiertasOpen extensions Extensiones de esquemaSchema extensions
Unidad administrativaAdministrative unit Solo versión preliminarPreview only Solo versión preliminarPreview only
Evento de calendarioCalendar event GAGA GAGA
DispositivoDevice GAGA GAGA
GrupoGroup GAGA GAGA
Evento de calendario de grupoGroup calendar event GAGA GAGA
Publicación de conversación de grupoGroup conversation post GAGA GAGA
MensajeMessage GAGA GAGA
OrganizaciónOrganization GAGA GAGA
Contacto personalPersonal contact GAGA GAGA
UsuarioUser GAGA GAGA

Puede usar las extensiones de todos estos recursos al iniciar sesión con una cuenta profesional o educativa.You can use extensions on all these resources when signed in with a work or school account. Además, puede usar las extensiones en los recursos event, post, group, message, contact y user al iniciar sesión con una cuenta personal.In addition, you can use extensions on the event, post, group, message, contact, and user resources when signed in with a personal account.

Extensiones abiertasOpen extensions

Las extensiones abiertas (anteriormente conocidas como extensiones de datos de Office 365) son tipos abiertos que ofrecen una forma flexible de agregar datos de la aplicación sin tipo directamente a una instancia de recurso.Open extensions (formerly known as Office 365 data extensions) are open types that offer a flexible way to add untyped app data directly to a resource instance.

Las extensiones abiertas, junto con sus datos personalizados, son accesibles a través de la propiedad de navegación extensions de la instancia del recurso.Open extensions, together with their custom data, are accessible through the extensions navigation property of the resource instance. La propiedad extensionName es la única propiedad predefinida y modificable una extensión abierta.The extensionName property is the only pre-defined, writable property in an open extension. Al crear una extensión abierta, debe asignar a la propiedad NombreExtensión un nombre que sea único dentro del inquilino.When creating an open extension, you must assign the extensionName property a name that is unique within the tenant.

Una forma de hacerlo es usar un método inverso del formato de nombres de dominio (DNS) que dependa de su propio dominio, por ejemplo, Com.Contoso.ContactInfo.One way to do this is to use a reverse domain name system (DNS) format that is dependent on your own domain, for example, Com.Contoso.ContactInfo.

No use el dominio de Microsoft (Com.Microsoft o Com.OnMicrosoft) en un nombre de extensión.Do not use the Microsoft domain (Com.Microsoft or Com.OnMicrosoft) in an extension name.

Puede crear una extensión abierta en una instancia de recurso y almacenar datos personalizados en ella en la misma operación (tenga en cuenta la limitación conocida para algunos de los recursos admitidos).You can create an open extension in a resource instance and store custom data to it all in the same operation (note known limitation for some of the supported resources).

Posteriormente, puede leer, actualizar o eliminar la extensión y sus datos.You can subsequently read, update, or delete the extension and its data.

Ejemplo de extensión abierta: Agregar datos personalizados a los usuarios mediante extensiones abiertasOpen extension example: Add custom data to users using open extensions

Extensiones de esquemaSchema extensions

Las extensiones de esquema permiten definir un esquema que puede usar para extender un tipo de recurso. En primer lugar, se crea una definición de extensión de esquema. Después, se utiliza para ampliar las instancias de recurso con datos personalizados inflexibles. Además, es posible controlar el estado de la extensión de esquema y permitir que sea reconocible por otras aplicaciones. Estas aplicaciones, a su vez, pueden utilizar la extensión para sus datos y crear experiencias adicionales a partir de ella.Schema extensions allow you to define a schema that you can use to extend a resource type. First, you create your schema extension definition. Then, use it to extend resource instances with strongly-typed custom data. In addition, you can control the status of your schema extension and let it be discoverable by other apps. These apps can in turn use the extension for their data and build further experiences on top of it.

Al crear una definición de extensión de esquema, debe proporcionar un nombre único para su id. Existen dos opciones de nomenclaturas:When creating a schema extension definition, you must provide a unique name for its id. There are two naming options:

  • Si ya tiene un dominio de cortesía .com, .net, .gov, .edu o .org que haya comprobado con su arrendatario, puede usar el nombre de dominio junto con el nombre de esquema para definir un nombre exclusivo, con este formato {nombreDominio}_{nombreEsquema}. Por ejemplo, si su dominio de cortesía es contoso.com, puede definir un id. de contoso_mySchema. Esta es la opción preferida.If you already have a vanity .com,.net, .gov, .edu or a .org domain that you have verified with your tenant, you can use the domain name along with the schema name to define a unique name, in this format {domainName}_{schemaName}. For example, if your vanity domain is contoso.com, you can define an id of, contoso_mySchema. This is the preferred option.
  • Si no tiene un dominio de cortesía comprobado, solo puede establecer el id a un esquema de nombres (sin un prefijo de nombre de dominio), por ejemplo, mySchema. Microsoft Graph le asignará un identificador de cadena basado en el nombre proporcionado en este formato: ext{8-random-alphanumeric-chars}_{schema-name}. Por ejemplo, extkvbmkofy_mySchema.If you don’t have a verified vanity domain, you can just set the id to a schema name (without a domain name prefix), for example, mySchema. Microsoft Graph will assign a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, extkvbmkofy_mySchema.

Verá que este nombre único en el id. se usa como el nombre del tipo complejo que almacenará sus datos personalizados en la instancia de recurso extendido.You will see this unique name in id used as the name of the complex type that will store your custom data on the extended resource instance.

A diferencia de las extensiones abiertas, la administración de las definiciones de extensión de esquema (list, create, get, update y delete) y de sus datos (agregar, obtener, actualizar y eliminar datos) son conjuntos independientes de operaciones de API.Unlike open extensions, managing schema extension definitions (list, create, get, update, and delete) and managing their data (add, get, update, and delete data) are separate sets of API operations.

Como las extensiones de esquema son accesibles como tipos complejos en las instancias de los recursos de destino, puede realizar operaciones CRUD en los datos personalizados en una extensión de esquema de las siguientes maneras:Because schema extensions are accessible as complex types in instances of the targeted resources, you can do CRUD operations on the custom data in a schema extension in the following ways:

  • Utilice el método de recurso POST para especificar datos personalizados al crear una nueva instancia del recurso.Use the resource POST method to specify custom data when creating a new resource instance. Tenga en cuenta que hay un problema conocido con los recursos de contacto, evento, mensaje y publicación que requiere la creación de una extensión de esquema con una operación PATCH.Note that there is a known issue on the contact, event, message, and post resources that requires creating a schema extension using a PATCH operation.
  • Utilice el método de recurso GET para leer los datos personalizados.Use the resource GET method to read the custom data.
  • Utilice el método de recurso PATCH para agregar o actualizar datos personalizados en una instancia de recurso existente.Use the resource PATCH method to add or update custom data in an existing resource instance.
  • Utilice el método de recurso PATCH para establecer el tipo complejo en null, para eliminar los datos en la instancia de recurso personalizados.Use the resource PATCH method to set the complex type to null, to delete the custom data in the resource instance.

Ejemplo de extensión de esquema: Agregar datos personalizados a los grupos mediante extensiones de esquemaSchema extension example: Add custom data to groups using schema extensions

Ciclo de vida de extensiones de esquemaSchema extensions lifecycle

Cuando la aplicación crea una definición de extensión de esquema, se marca como propietaria de esa extensión de esquema.When your app creates a schema extension definition, the app is marked as the owner of that schema extension.

La aplicación propietaria puede mover la extensión a través de diferentes estados de un ciclo de vida, mediante una operación PATCH en su propiedad status. Dependiendo del estado actual, el propietario de la aplicación puede actualizar o eliminar la extensión. Las actualizaciones de una extensión de esquema solo deberían ser aditivas y de no separación.The owner app can move the extension through different states of a lifecycle, using a PATCH operation on its status property. Depending on the current state, the owner app may be able to update or delete the extension. Any updates to a schema extension should always only be additive and non-breaking.

EstadoState Comportamiento de estado de ciclo de vidaLifecycle state behavior
InDevelopmentInDevelopment
  • Estado inicial después de su creación. El propietario de la aplicación aún está desarrollando la extensión de esquema. Initial state after creation. The owner app is still developing the schema extension.
  • En este estado, cualquier aplicación que esté en el mismo directorio donde se ha registrado la aplicación propietaria puede ampliar las instancias de recursos con esta definición de esquema (siempre y cuando la aplicación tenga los permisos de ese recurso).In this state, any app in the same directory where the owner app is registered can extend resource instances with this schema definition (as long as the app has permissions to that resource).
  • Solamente la aplicación propietaria puede actualizar la definición de extensión con cambios que se incorporen o eliminarla.Only the owner app can update the extension definition with additive changes or delete it.
  • La aplicación del propietario puede mover la extensión de InDevelopment al estado Disponible.The owner app can move the extension from InDevelopment to the Available state.
DisponibleAvailable
  • La extensión de esquema está disponible para su uso por todas las aplicaciones de los inquilinos.The schema extension is available for use by all apps in any tenant.
  • Después de que la aplicación propietaria establezca la extensión en Disponible, cualquier aplicación puede simplemente agregar datos personalizados a instancias de esos tipos de recursos especificadas en la extensión (siempre que la aplicación tenga permisos para ese recurso).After the owner app sets the extension to Available, any app can simply add custom data to instances of those resource types specified in the extension (as long as the app has permissions to that resource). La aplicación puede asignar datos personalizados al crear una nueva instancia o al actualizar una instancia existente.The app can assign custom data when creating a new instance or updating an existing instance.
  • Solamente la aplicación propietaria puede actualizar la definición de extensión con cambios que se incorporen.Only the owner app can update the extension definition with additive changes. Ninguna aplicación puede eliminar la definición de la extensión en este estado.No app can delete the extension definition in this state.
  • La aplicación del propietario puede mover la extensión de esquema de Disponible al estado En desuso.The owner app can move the schema extension from Available to the Deprecated state.
En desusoDeprecated
  • La definición de la extensión de esquema ya no se puede leer o modificar.The schema extension definition can no longer be read or modified.
  • Ninguna aplicación puede ver, actualizar, agregar nuevas propiedades o eliminar la extensión.No app can view, update, add new properties, or delete the extension.
  • Sin embargo, las aplicaciones todavía pueden leer, actualizar o eliminar los valores de la propiedad de la extensión existente.Apps can, however, still read, update, or delete existing extension property values.

Tipos de datos de propiedad admitidosSupported property data types

Se admiten los siguientes tipos de datos al definir una propiedad en una extensión de esquema:The following data types are supported when defining a property in a schema extension:

Tipo de propiedadProperty Type ObservacionesRemarks
BinarioBinary Máximo de 256 bytes.256 bytes maximum.
BooleanoBoolean No se admite para los mensajes, eventos y publicaciones.Not supported for messages, events and posts.
DateTimeDateTime Debe especificarse en el formato ISO 8601. Se almacenarán en UTC.Must be specified in ISO 8601 format. Will be stored in UTC.
EnteroInteger Valor de 32 bits. No se admite para los mensajes, eventos y publicaciones.32-bit value. Not supported for messages, events and posts.
StringString Máximo de 256 caracteres.256 characters maximum.

Nota: No se admiten propiedades de varios valores.Note: Multi-value properties are not supported.

Extensiones de esquema de directorio de Azure ADAzure AD directory schema extensions

Azure AD es compatible con un tipo similar de extensiones, conocido como las extensiones de esquema de directorio, en unos pocos recursos directoryObject. Aunque debe utilizar la API Graph de Azure AD para crear y administrar las definiciones de las extensiones de esquema de directorio, puede utilizar la API de Microsoft Graph para agregar, obtener, actualizar y eliminar datos en las propiedades de estas extensiones.Azure AD supports a similar type of extension, known as directory schema extensions, on a few directoryObject resources. Although you have to use the Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use the Microsoft Graph API to add, get, update and delete data in the properties of these extensions.

PermisosPermissions

Los mismos permisos necesarios para leer de o escribir en un recurso específico, también son necesarios para hacerlo en cualquier extensión de datos de dicho recurso.The same permissions that are required to read from or write to a specific resource are also required to read from or write to any extensions data on that resource. Por ejemplo, para que una aplicación pueda actualizar el perfil del usuario que ha iniciado sesión con datos personalizados de la misma, esta debe tener el permiso User.ReadWrite.all.For example, for an app to be able to update the signed-in user's profile with custom app data, the app must have been granted the User.ReadWrite.All permission.

Además, para crear y administrar definiciones de extensión de esquema, una aplicación debe contar con el permiso Directory.AccessAsUser.All.Additionally, to create and manage schema extension definitions, an application must be granted the Directory.AccessAsUser.All permission.

Límites de datosData limits

Límites de extensión abiertosOpen extension limits

Los límites siguientes se aplican a los recursos de directorio (como user, group, device):The following limits apply to directory resources (such as user, group, device):

  • Cada extensión abierta puede tener hasta 2 KB de datos (incluida la propia definición de extensión).Each open extension can have up to 2 KB of data (including the extension definition itself).
  • Una aplicación puede agregar hasta dos extensiones abiertas por cada instancia del recurso.An application can add up to two open extensions per resource instance.

Los siguientes límites se aplican a los recursos de Outlook (como message, event y contact):The following limits apply to Outlook resources (such as message, event, and contact):

Límites de extensión del esquemaSchema extension limits

Una aplicación no puede crear más de cinco definiciones de extensión del esquema.An application may create no more than five schema extension definitions.

Limitaciones conocidasKnown limitations

Para ver las limitaciones conocidas al usar las extensiones, consulte la sección de extensiones del artículo de problemas conocidos.For known limitations using extensions, see the extensions section in the known issues article.

Ejemplos de extensiónExtension examples

Consulte tambiénSee also