Compartir a través de


Agregar datos personalizados a los grupos mediante extensiones de esquema

En este tutorial, aprenderá a usar extensiones de esquema.

Imagine que es un desarrollador de una empresa de software de administración de aprendizaje llamada Bellows College que crea cursos de formación y materiales para empresas. Usa la experiencia de colaboración de los grupos de Microsoft 365 para ofrecer contenido del curso y ejercicios de registro entre los participantes para cursos en línea y cursos dirigidos por instructores. Quiere que los grupos de Microsoft 365 se usen para los cursos de aprendizaje fácilmente identificables como cursos de formación, lo que permite a otros desarrolladores descubrir sus grupos y crear experiencias enriquecidas sobre los cursos de aprendizaje.

En este escenario, en este artículo se muestra cómo:

  • Descubra las definiciones de extensión de esquema disponibles que podría usar.
  • Registrar una definición de extensión de esquema que tiene como objetivo grupos de cursos de formación.
  • Cree un nuevo grupo con datos personalizados basados en la definición de extensión de esquema que registró.
  • Agregar, actualizar o eliminar datos personalizados a un grupo existente basado en una definición de extensión de esquema.
  • Lee un grupo y los datos de la extensión.
  • Elimine la definición de la extensión de esquema y los datos de la extensión.

Nota:

Además de los grupos, también se admiten extensiones de esquema y se pueden administrar para otros tipos de recursos.

Requisitos previos

Para reproducir los pasos de este artículo, necesita los siguientes privilegios:

  • Inicie sesión en un cliente de API, como Graph Explorer.
  • Conceda a la aplicación los permisos delegados Group.ReadWrite.All y Application.ReadWrite.All para el usuario que ha iniciado sesión.
  • Sea el propietario de una aplicación a la que asigne la propiedad de la definición de extensión de esquema en este tutorial. En este tutorial, la aplicación se denomina extensiones-application y tiene appIdd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2.

Paso 1. Visualización de las extensiones de esquema disponibles

En primer lugar, como desarrollador, es posible que desee que la aplicación reutilice las definiciones de extensión de esquema existentes si son adecuadas para su propósito. En el ejemplo siguiente, se consultan las extensiones de esquema denominadas (por el identificador). bellowscollege_courses Supongamos que la respuesta muestra que no hay extensiones de esquema con nombre bellowscollege_courses en el inquilino.

Solicitud

GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'bellowscollege_courses'

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET schemaExtensions?$select=description,owner",
    "value": []
}

También puede consultar por el identificador como un parámetro de ruta de acceso como se indica a continuación: GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses. Si no hay extensiones de esquema que coincidan con el identificador, la respuesta es 404 Not Found.

Paso 2. Registro de una definición de extensión de esquema

Quiere crear y registrar una nueva definición de extensión para los cursos de entrenamiento en el recurso de grupo . Especifique las propiedades siguientes:

  • id: proporcione una cadena para esta propiedad de dos maneras:
    • Opción 1: concatene un nombre de dominio de vanidad comprobado para el inquilino con un nombre para la extensión de esquema. Por ejemplo, si el dominio es bellowscollege.comy el nombre de la extensión de esquema es courses, puede usar el identificadorbellowscollege_courses.

    • Opción 2: una manera alternativa es proporcionar solo un nombre de esquema, como courses, y permitir que Microsoft Graph genere automáticamente el identificador anteponiendo al nombre proporcionado una cadena alfanumérica aleatoria.

      Este identificador se convierte en el nombre de la propiedad de extensión de esquema de un grupo.

  • description
  • targetTypes: especifique los tipos de recursos a los que se puede aplicar la extensión de esquema. En este ejemplo, el tipo de recurso es Group. Puede agregar más tipos de recursos actualizando la definición de extensión de esquema más adelante.
  • properties: especifique las propiedades personalizadas que componen el esquema. En este ejemplo, especifique las courseIdpropiedades personalizadas y , courseName y courseType sus tipos. Solo se permiten cambios aditivos después de crear la definición de extensión de esquema.
  • owner: especifique la aplicación propietaria de la definición de extensión de esquema. Si ejecuta este ejemplo desde una aplicación a la que no se le asigna como propietario, especifique el valor appId de la aplicación que se le asigna en la propiedad owner .

Solicitud

POST https://graph.microsoft.com/v1.0/schemaExtensions
Content-type: application/json

{
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

En la respuesta, el estado inicial predeterminado de la extensión de esquema es InDevelopment. Mientras desarrollas la extensión, puedes mantenerla en este estado, durante el cual solo la aplicación que la creó puede actualizarla con cambios aditivos o eliminarla. Cuando esté listo para compartir la extensión para que la usen otras aplicaciones, establezca el estadoen Disponible.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions/$entity",
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

Paso 3. Extensión de un grupo con datos personalizados

Puede ampliar un grupo con datos personalizados durante la creación del grupo o actualizando un grupo existente.

Opción 1: Crear un nuevo grupo con datos extendidos

La solicitud siguiente crea un nuevo grupo y usa la extensión de bellowscollege_courses esquema para ampliar el grupo con datos personalizados. Si tiene un grupo existente, también puede ampliarlo con datos personalizados actualizando el grupo con los datos de extensión.

La respuesta no refleja ninguna extensión de datos. Debe especificar explícitamente $select la extensión por nombre mediante una GET /group/{id} operación.

Solicitud

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "displayName": "New Managers March 2024",
    "description": "New Managers training course for March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mailEnabled": true,
    "mailNickname": "newMan202403",
    "securityEnabled": false,
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

Respuesta

En el ejemplo siguiente se muestra la respuesta. La respuesta no incluye la nueva extensión. Debe especificar explícitamente $select la extensión por nombre mediante una GET /group/{id} operación.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
    "createdDateTime": "2024-01-24T09:09:03Z",
    "description": "New Managers training course for March 2024",
    "displayName": "New Managers March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mail": "newMan202403@bellowscollege.com",
    "mailEnabled": true,
    "mailNickname": "newMan202403"
}

Opción 2: Actualizar un grupo existente con datos extendidos

Si tiene un grupo existente, también puede ampliarlo con datos personalizados como se indica a continuación. La solicitud devuelve una 204 No Content respuesta.

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

Paso 4. Actualización de datos personalizados en un grupo

La siguiente solicitud actualiza la propiedad courseType de la bellowscollege_courses extensión del grupo a Hybrid. Aunque solo desea actualizar la propiedad courseType , también debe incluir las demás propiedades y sus valores existentes en el cuerpo de la solicitud. De lo contrario, Microsoft Graph los establece en null y quita sus datos.

La siguiente solicitud devuelve una 204 No Content respuesta.

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Hybrid"
    }
}

Paso 5. Obtención de un grupo y sus datos de extensión

Para obtener los datos personalizados de un grupo, use $select para incluir la extensión por nombre.

Además de filtrar por el identificador de la extensión de esquema, también puede filtrar por los valores de propiedad de extensión. En el ejemplo siguiente se busca el grupo que tiene la bellowscollege_courses extensión con un courseId valor de propiedad que coincida 123con y se obtienen los datos de extensión y las propiedades displayName, id y description del grupo.

Solicitud

GET https://graph.microsoft.com/v1.0/groups?$filter=bellowscollege_courses/courseId eq '123'&$select=displayName,id,description,bellowscollege_courses

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(displayName,id,description,bellowscollege_courses)",
    "value": [
        {
            "displayName": "New Managers March 2024",
            "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
            "description": "New Managers training course for March 2024",
            "bellowscollege_courses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Hybrid",
                "courseName": "New Managers",
                "courseId": 123
            }
        }
    ]
}

Paso 6: Eliminación de datos de extensión y definición de extensión de esquema

Puede eliminar una definición de extensión de esquema si ya no la necesita. Si las instancias de recursos tienen aplicada la propiedad de extensión, la eliminación de la definición de extensión de esquema no elimina los datos de extensión en las instancias de recurso. En su lugar, los datos de extensión están disponibles, pero ya no son accesibles. Puede volver a crear la definición de extensión de esquema con la misma configuración (si usó el dominio comprobado para el identificador de extensión de esquema) para poder eliminar los datos de la extensión.

La siguiente solicitud elimina la propiedad de extensión de bellowscollege_courses esquema y sus datos asociados del grupo. La solicitud devuelve una 204 No Content respuesta.

PATCH https://graph.microsoft.com/v1.0/groups/8fb45944-4085-449f-b95d-f7dd74a1b081

{
    "bellowscollege_courses": null
}

La siguiente solicitud elimina la definición de extensión de bellowscollege_courses esquema. La solicitud devuelve una 204 No Content respuesta.

DELETE https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses