Tipo de recurso schemaExtension (extensiones de esquema)

  • Artículo

Espacio de nombres: microsoft.graph

Las extensiones de esquema permiten definir un esquema para extender y agregar datos personalizados fuertemente tipados a un tipo de recurso. Los datos personalizados aparecen como un tipo complejo en el recurso extendido. Las extensiones de esquema son compatibles con los siguientes tipos de recursos:

Use este recurso y los métodos asociados para administrar las definiciones de extensión de esquema. Para administrar los datos de extensión de esquema en la instancia de recursos extendidos, use la misma solicitud REST que emplea para administrar la instancia de recurso. Consulte el ejemplo de extensión de esquema para obtener información sobre cómo agregar datos personalizados a los grupos.

Para obtener más información sobre la extensibilidad de Microsoft Graph, incluidos los límites de las extensiones de esquema, consulte Agregar propiedades personalizadas a los recursos mediante extensiones.

Métodos

Método Tipo de valor devuelto Descripción
Crear schemaExtension Cree una definición de extensión de esquema y su propiedad de extensión de esquema asociada.
List schemaExtension Enumera las definiciones schemaExtension disponibles y sus propiedades.
Get schemaExtension Lee las propiedades de una definición schemaExtension específica.
Update schemaExtension Actualiza una definición schemaExtension. Use esta operación para actualizar la descripción, el estado, los tipos de destino o agregar más propiedades a la definición de la extensión de esquema.
Delete Ninguno Elimina una definición schemaExtension.

Propiedades

Propiedad Tipo Descripción
description String Descripción de la extensión de esquema. Admite $filter (eq).
id Cadena Identificador único para la definición de la extensión de esquema.
Puede asignar un valor de dos maneras:
  • Concatene el nombre de uno de los dominios comprobados con un nombre para la extensión de esquema para formar una cadena única en este formato, {domainName}_{schemaName}. Por ejemplo: contoso_mySchema.
  • Proporcione un nombre de esquema y deje que Microsoft Graph use ese nombre de esquema para completar la asignación de identificador en este formato: ext{8-random-alphanumeric-chars}_{schema-name}. Un ejemplo sería extkvbmkofy_mySchema.
Una vez creada, esta propiedad no se puede modificar. Admite $filter (eq). Nota: Se recomienda que el identificador comience por una letra alfabética entre A-Z porque las capacidades de consulta pueden estar limitadas para los identificadores que comienzan por enteros.

Admite $filter (eq).
owner String El appId de la aplicación que es el propietario de la extensión del esquema. El propietario de la definición de esquema debe especificarse explícitamente durante las operaciones De creación y actualización, o se asignará automáticamente por Microsoft Entra ID como se indica a continuación:
  • En el acceso delegado:
    • El usuario que ha iniciado sesión debe ser el propietario de la aplicación que llama a Microsoft Graph para crear la definición de la extensión de esquema.
    • Si el usuario que inició sesión no es el propietario de la aplicación que realiza la llamada, debe especificar explícitamente la propiedad owner y asignarle el appId de una aplicación de su propiedad.
  • En el acceso solo a la aplicación:
    • La propiedad owner no es necesaria en el cuerpo de la solicitud. En su lugar, a la aplicación que realiza la llamada se le asigna la propiedad de la extensión de esquema.

Por ejemplo, si crea una nueva definición de extensión de esquema mediante el Explorador de Graph, debe proporcionar la propiedad owner. Una vez establecida, esta propiedad es de solo lectura y no se puede cambiar. Admite $filter (eq).
properties Colección extensionSchemaProperty La colección de nombres de propiedad y tipos que conforman la definición de la extensión de esquema.
status Cadena El estado del ciclo de vida de la extensión de esquema. Los estados posibles son InDevelopment (En desarrollo), Available (Disponible) y Deprecated (En desuso). En el momento de la creación se establece automáticamente en InDevelopment. Para obtener más información sobre las posibles transiciones de estado y comportamientos, vea El ciclo de vida de las extensiones de esquema. Admite $filter (eq).
targetTypes String collection Conjunto de tipos de Microsoft Graph (compatibles con extensiones) a los que se puede aplicar la extensión de esquema. Seleccione entre administrativeUnit, contact, device, event, group, message, organization, post, todoTask, todoTaskList o user.

Ciclo de vida de extensiones de esquema

Cuando la aplicación crea una definición de extensión de esquema, se marca como propietaria de esa extensión de esquema.

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 de estado . En función del estado actual, es posible que la aplicación propietaria pueda actualizar o eliminar la extensión. Las actualizaciones de una extensión de esquema siempre deben ser aditivas y no interrumpirse.

Estado Comportamiento de estado de ciclo de vida
InDevelopment
  • Estado inicial después de su creación. La aplicación propietaria sigue desarrollando la extensión de esquema.
  • 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).
  • En el caso de una aplicación de propietario multiinquilino, solo la instancia de la aplicación propietaria que se encuentra en un directorio diferente del directorio principal puede ampliar las instancias de recursos con esta definición de esquema (si la aplicación tiene permisos para ese recurso) o leer los datos de la extensión.
  • Solamente la aplicación propietaria puede actualizar la definición de extensión con cambios que se incorporen.
  • Solo la aplicación propietaria puede eliminar la definición de extensión.
  • La aplicación propietaria puede mover la extensión desde InDevelopment al Available estado .
Disponible
  • La extensión de esquema está disponible para su uso por todas las aplicaciones de los inquilinos.
  • Una vez que la aplicación propietaria establece la extensión Availableen , cualquier aplicación puede agregar datos personalizados a instancias de esos tipos de recursos especificados en la extensión (si la aplicación tiene permisos para ese recurso). La aplicación puede asignar datos personalizados al crear una nueva instancia o al actualizar una instancia existente.
  • Solamente la aplicación propietaria puede actualizar la definición de extensión con cambios que se incorporen. Ninguna aplicación puede eliminar la definición de la extensión en este estado.
  • La aplicación propietaria puede mover la extensión de esquema del Available estado.Deprecated
En desuso
  • La definición de la extensión de esquema ya no se puede leer o modificar.
  • Ninguna aplicación puede ver, actualizar, agregar nuevas propiedades o eliminar la extensión.
  • Sin embargo, las aplicaciones pueden leer, actualizar o eliminar los valores de propiedad de extensión existentes.

Nota:

Las definiciones de extensión de esquema (marcadas como Available) creadas por otros desarrolladores de otros inquilinos son visibles para todos los desarrolladores (enumerando todas las extensiones de esquema). Esto es diferente a otras API que solo devuelvan datos específicos de los espacios empresariales. Por otra parte, los datos de extensión creados basándose en definiciones de extensión de esquema son específicos del espacio empresarial y solo las aplicaciones que tienen permiso concedido explícitamente pueden acceder a ellos.

Representación JSON

La siguiente representación JSON muestra el tipo de recurso.

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

Contenido relacionado