Partager via


Ajout de données personnalisées à des groupes à l’aide des extensions de schéma

Dans ce tutoriel, vous allez apprendre à utiliser des extensions de schéma.

Imaginez que vous êtes développeur dans une société de logiciels de gestion de l’apprentissage appelée Bellows College qui crée des cours de formation et du matériel pour les entreprises. Vous utilisez l’expérience collaborative des groupes Microsoft 365 pour fournir du contenu de cours et enregistrer des exercices parmi les participants pour les cours en ligne et les cours dirigés par un instructeur. Vous souhaitez rendre les groupes Microsoft 365 utilisés pour les cours de formation facilement identifiables en tant que cours de formation, ce qui permet à d’autres développeurs de découvrir vos groupes et de créer des expériences enrichies en plus de vos cours d’apprentissage.

Pour ce scénario, cet article vous montre comment :

  • Découvrez les définitions d’extension de schéma disponibles que vous pouvez utiliser.
  • Enregistrer une définition d’extension de schéma qui cible des groupes pour les cours de formation.
  • Créez un groupe avec des données personnalisées basées sur la définition d’extension de schéma que vous avez inscrite.
  • Ajouter, mettre à jour ou supprimer des données personnalisées dans un groupe existant en fonction d’une définition d’extension de schéma.
  • Lire un groupe et les données d’extension.
  • Supprimez la définition d’extension de schéma et les données d’extension.

Remarque

Outre les groupes, les extensions de schéma sont également prises en charge et peuvent être gérées pour d’autres types de ressources.

Configuration requise

Pour reproduire les étapes décrites dans cet article, vous avez besoin des privilèges suivants :

  • Connectez-vous à un client API tel que l’Explorateur Graph.
  • Accordez à l’application les autorisations déléguées Group.ReadWrite.All et Application.ReadWrite.All pour l’utilisateur connecté.
  • Être le propriétaire d’une application à laquelle vous attribuez la propriété de la définition d’extension de schéma dans ce tutoriel. Dans ce tutoriel, l’application est nommée extensions-application et a appIdd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2.

Étape 1. Afficher les extensions de schéma disponibles

Tout d’abord, en tant que développeur, vous pouvez souhaiter que l’application réutilise toutes les définitions d’extension de schéma existantes si elles sont adaptées à cet objectif. Dans l’exemple suivant, vous interrogez les extensions de schéma nommées (par l’ID). bellowscollege_courses Supposons que la réponse indique qu’aucune extension de schéma n’est nommée bellowscollege_courses dans votre locataire.

Demande

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

Réponse

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": []
}

Vous pouvez également interroger par l’ID en tant que paramètre de chemin d’accès comme suit : GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses. Si aucune extension de schéma ne correspond à l’ID, la réponse est 404 Not Found.

Étape 2. Inscrire une définition d’extension de schéma

Vous souhaitez créer et inscrire une nouvelle définition d’extension pour les cours de formation sur la ressource de groupe . Spécifiez les propriétés suivantes :

  • id : fournissez une chaîne pour cette propriété en suivant l’une des deux méthodes suivantes :
    • Option 1 : Concaténer un nom de domaine personnel vérifié pour votre locataire avec un nom pour l’extension de schéma. Par exemple, si le domaine est bellowscollege.comet que le nom de l’extension de schéma est courses, vous pouvez utiliser l’IDbellowscollege_courses.

    • Option 2 : une autre méthode consiste à fournir uniquement un nom de schéma, par coursesexemple , et à laisser Microsoft Graph générer automatiquement l’ID pour vous en préfixant le nom fourni d’une chaîne alphanumérique aléatoire.

      Cet ID devient le nom de la propriété d’extension de schéma sur un groupe.

  • description
  • targetTypes : spécifiez les types de ressources auxquels l’extension de schéma peut être appliquée. Dans cet exemple, le type de ressource est Group. Vous pouvez ajouter d’autres types de ressources en mettant à jour la définition d’extension de schéma ultérieurement.
  • properties : spécifiez les propriétés personnalisées qui composent le schéma. Dans cet exemple, spécifiez les courseIdpropriétés personnalisées , courseName et courseType et ainsi que leurs types. Seules les modifications additives sont autorisées après la création de la définition d’extension de schéma.
  • owner : spécifiez l’application qui possède la définition d’extension de schéma. Si vous exécutez cet exemple à partir d’une application qui ne vous est pas attribuée en tant que propriétaire, spécifiez l’appId de l’application qui vous est affectée dans la propriété owner .

Demande

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

Réponse

L’exemple suivant illustre la réponse.

Dans la réponse, l’état initial par défaut de l’extension de schéma est InDevelopment. Pendant que vous développez l’extension, vous pouvez la conserver dans cet état, pendant lequel seule l’application qui l’a créée peut la mettre à jour avec des modifications additives ou la supprimer. Lorsque vous êtes prêt à partager l’extension pour une utilisation par d’autres applications, définissez l’étatsur 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"
        }
    ]
}

Étape 3. Étendre un groupe avec des données personnalisées

Vous pouvez étendre un groupe avec des données personnalisées lors de la création du groupe ou en mettant à jour un groupe existant.

Option 1 : Créer un groupe avec des données étendues

La requête suivante crée un groupe et utilise l’extension de bellowscollege_courses schéma pour étendre le groupe avec des données personnalisées. Si vous avez un groupe existant, vous pouvez également l’étendre avec des données personnalisées en mettant à jour le groupe avec les données d’extension.

La réponse ne reflète aucune extension de données. Vous devez explicitement $select utiliser l’extension par son nom à l’aide d’une GET /group/{id} opération.

Demande

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

Réponse

L’exemple suivant illustre la réponse. La réponse n’inclut pas la nouvelle extension. Vous devez explicitement $select utiliser l’extension par son nom à l’aide d’une GET /group/{id} opération.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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

Option 2 : Mettre à jour un groupe existant avec des données étendues

Si vous avez un groupe existant, vous pouvez également l’étendre avec des données personnalisées comme suit. La requête retourne une 204 No Content réponse.

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

Étape 4. Mettre à jour des données personnalisées dans un groupe

La requête suivante met à jour la propriété courseType dans l’extension bellowscollege_courses du groupe en Hybrid. Bien que vous souhaitiez mettre à jour uniquement la propriété courseType , vous devez également inclure les autres propriétés et leurs valeurs existantes dans le corps de la requête. Sinon, Microsoft Graph les null définit sur et supprime leurs données.

La requête suivante retourne une 204 No Content réponse.

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

Étape 5. Obtenir un groupe et ses données d’extension

Pour obtenir les données personnalisées dans un groupe, utilisez $select pour inclure l’extension par nom.

Outre le filtrage par l’ID de l’extension de schéma, vous pouvez également filtrer en fonction des valeurs de propriété d’extension. L’exemple suivant recherche le groupe qui a l’extension bellowscollege_courses avec une courseId valeur de propriété correspondant 123à , et obtient les données d’extension et les propriétés displayName, id et description du groupe.

Demande

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

Réponse

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

Étape 6 : Supprimer les données d’extension et la définition d’extension de schéma

Vous pouvez supprimer une définition d’extension de schéma si vous n’en avez plus besoin. Si la propriété d’extension est appliquée aux instances de ressources, la suppression de la définition d’extension de schéma ne supprime pas les données d’extension dans les instances de ressource. Au lieu de cela, les données d’extension sont disponibles, mais plus accessibles. Vous pouvez recréer la définition d’extension de schéma avec la même configuration (si vous avez utilisé le domaine vérifié pour l’ID d’extension de schéma) pour pouvoir supprimer les données d’extension.

La requête suivante supprime la propriété d’extension bellowscollege_courses de schéma et ses données associées du groupe. La requête retourne une 204 No Content réponse.

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

{
    "bellowscollege_courses": null
}

La requête suivante supprime la définition d’extension de bellowscollege_courses schéma. La requête retourne une 204 No Content réponse.

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