Ajout de données personnalisées à des groupes à l’aide des extensions de schémaAdd custom data to groups using schema extensions

Nous allons vous présenter un exemple montrant comment utiliser les extensions de schéma.We're going to walk you through an example to demonstrate how to use schema extensions.

Imaginez que vous êtes développeur dans une société de logiciels de gestion de l’apprentissage appelée « Graph Learn » qui crée des cours de formation et de la documentation pour les entreprises. Les groupes Office 365, avec leurs fonctionnalités de collaboration étendues, sont un excellent moyen de fournir du contenu de cours et d’enregistrer les exercices des participants pour les formations en ligne et les formations animées par un instructeur. Ces groupes Office 365 utilisés pour les cours de formation doivent être facilement identifiables comme cours de formation, ce qui permettra aux autres développeurs de découvrir vos groupes et créer des expériences étendues en plus de vos cours d’apprentissage.Imagine you're a developer in a Learning Management Software company called “Graph Learn” that builds training courses and materials for businesses. Office 365 groups, with their rich collaborative experiences, is a fantastic way to deliver course content and record exercises among participants for both online courses and instructor-led courses. You may want to make those Office 365 groups used for training courses easily identifiable as training courses, which will allow other developers to discover your groups and build rich experiences on top of your learning courses.

Pour ce scénario, nous allons vous montrer comment :For this scenario, we're going to show you how to:

  1. Afficher les définitions d’extension de schéma que vous pouvez utiliser.View available schema extension definitions that you could use.
  2. Enregistrer une définition d’extension de schéma qui cible des groupes pour les cours de formation.Register a schema extension definition that targets groups for training courses.
  3. Créer un groupe avec des données étendues en fonction de la définition d’extension de schéma que vous venez d’enregistrer.Create a new group with extended data based on the schema extension definition that you just registered.
  4. 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.Add, update, or remove custom data in an existing group based on a schema extension definition.
  5. Lire un groupe et les données d’extension.Read back a group and the extension data.

Remarque : Cette rubrique explique comment créer et lire des valeurs d’extension de schéma sur une ressource group (étapes 3 à 5). Les mêmes méthodes sont prises en charge pour les types de ressources administrativeUnit, device, event, message, organization, post et user. Ainsi, vous pouvez effectuer des opérations semblables aux exemples de demandes ci-dessous sur n’importe laquelle de ces ressources. Notez que administrativeUnit est disponible uniquement dans le point de terminaison bêta.Note: This topic shows you how to create and read schema extension values on a group resource (steps 3-5). The same methods are supported for the administrativeUnit, device, event, message, organization, post, and user resource types as well. So you can carry out similar operations as the example requests below on any of those resources. Note that administrativeUnit is available only in the beta endpoint.

1. Affichage des extensions de schéma disponibles1. View available schema extensions

Tout d’abord, en tant que développeur, vous pourriez vouloir rechercher d’autres définitions de schéma d’extension que notre application pourrait réutiliser. Cette opération peut être effectuée en interrogeant la ressource schemaExtension.First, as a developer, you might want to find any other schema extension definitions that our app could reuse. This can be done by querying the schemaExtension resource.
Dans l’exemple ci-dessous, vous allez utiliser une requête pour rechercher une extension de schéma spécifique par ID.In the example below, you're going to query for a specific schema extension by id.

Notez que l’extension renvoyée dans la réponse indique Disponible en tant que valeur d’état, ce qui indique qu’une application qui dispose des autorisations pour les ressources dans la propriété targetTypes peut utiliser et mettre à jour l’extension avec des modifications supplémentaires. En règle générale, cette opération renvoie toutes les extensions de schéma qui correspondent au filtre spécifié indépendamment de l’état, vérifiez donc l’état de l’extension avant de l’utiliser.Notice that the extension returned in the response has Available as the status value, which indicates that any app which has permission to the resources in the targetTypes property can use and update the extension with additive changes. In general, this operation returns any schema extensions that satisfy the specified filter regardless of status, so do check the extension status before using it.

DemandeRequest
GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'graphlearn_test'
RéponseResponse
HTTP/1.1 200 OK
Content-Type: application/json
Content-length: 420
{
    "value": [
        {
            "id":"graphlearn_test",
            "description": "Yet another test schema",
            "targetTypes": [
                "User", "Group"
            ],
            "status": "Available",
            "owner": "24d3b144-21ae-4080-943f-7067b395b913",
            "properties": [
                {
                    "name": "testName",
                    "type": "String"
                }
            ]
        }
    ]
}

2. Enregistrement d’une définition d’extension de schéma qui décrit un cours de formation2. Register a schema extension definition that describes a training course

Si vous ne pouvez pas trouver d’extension de schéma qui soit adaptée à vos besoins, vous pouvez créer et enregistrer une nouvelle définition d’extension pour les cours de formation sur la ressource group.If you can't find a schema extension that is appropriate for your needs, you can create and register a new extension definition for training courses on the group resource.

Lorsque vous créez une définition d’extension de schéma, vous devez fournir une chaîne pour la propriété ID. Il existe deux méthodes pour y parvenir. L’exemple suivant illustre la méthode recommandée, qui utilise un nom de domaine personnel (graphlearn.com) qui a été vérifié par votre client. Concaténez le nom de domaine vérifié (graphlearn) avec un nom pour l’extension de schéma (courses) et affectez un ID avec la chaîne résultante, graphlearn_courses.When creating a schema extension definition, you should provide a string for the id property. There are two ways to do this. The following example shows the preferred way, which uses a vanity domain name (graphlearn.com) that has been verified with your tenant. Concatenate the verified domain name (graphlearn) with a name for the schema extension (courses), and assign id with the resultant string, graphlearn_courses.

Indiquez ensuite une description (pour activer la découverte), des types de cible (qui définissent les ressources auxquelles s’appliquent cette extension) et les propriétés personnalisées qui composeront le schéma. Dans cet exemple, spécifiez les propriétés personnalisées courseId, courseName et courseType et leurs types.Then, specify a description (to enable discoverability), target types (defining which resources this extension applies to), and the custom properties that make up the schema. In this example, specify the courseId, courseName and courseType custom properties and their types.

Consultez un exemple de l’autre façon d’affecter ID dans la demande, qui nécessite que vous fournissiez uniquement un nom de schéma.See an example of the other way to assign id in the request, that requires you to provide only a schema name.

Notez que lorsque vous créez initialement une extension de schéma, son état est InDevelopment. Lorsque vous développez l’extension, vous pouvez la conserver dans cet état, pendant lequel seule l’application avec laquelle vous l’avez créée peut la mettre à jour avec d’autres modifications additifs ou la supprimer. Lorsque vous êtes prêt à partager l’extension pour une utilisation par d’autres applications, définissez l’état sur Disponible.Notice that when you initially create a schema extension, its status is InDevelopment. While you're developing the extension, you can keep it in this status, during which only your app that created it can update it with additive changes or delete it. When you are ready to share the extension for use by other apps, set status to Available.

DemandeRequest
POST https://graph.microsoft.com/v1.0/schemaExtensions
Content-type: application/json
{
    "id":"graphlearn_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}
RéponseResponse
HTTP/1.1 201 Created
Content-Type: application/json
Content-length: 420
{
    "id": "graphlearn_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "24d3b144-21ae-4080-943f-7067b395b913",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

3. Création d’un groupe avec des données étendues3. Create a new group with extended data

Créez un nouveau groupe et étendez-le avec des données supplémentaires à l’aide de la définition d’extension de schéma graphlearn_courses que vous venez d’enregistrer. Il s’agit d’une demande POST standard pour la ressource group, avec l’extension de type complexe graphlearn_courses définie dans le corps de la demande. La réponse ne reflète pas les extensions de données. Nous devons $select explicitement l’extension par nom à l’aide d’une opération GET.Create a new group and extend it with extra data using the graphlearn_courses schema extension definition that we just registered. This is a standard POST to the group resource, with the additional graphlearn_courses complex type extension defined in the request body. The response will not mirror back any data extensions. We need to explicitly $select the extension by name using a GET operation.

DemandeRequest
POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json
{
    "displayName": "New Managers March 2017",
    "description": "New Managers training course for March 2017",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "mailNickname": "newMan201703",
    "securityEnabled": false,
    "graphlearn_courses": {
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
    }
}
RéponseResponse
HTTP/1.1 201 Created
Content-Type: application/json
Content-length: 420
{
    "id": "dfc8016f-db97-4c47-a582-49cb8f849355",
    "createdDateTime": "2017-02-09T00:17:05Z",
    "description": "New Managers training course for March 2017",
    "displayName": "New Managers March 2017",
    "groupTypes": [
        "Unified"
    ],
    "mail": "newMan201703@graphlearn.com",
    "mailEnabled": true,
    "mailNickname": "newMan201703",
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

4. Ajouter, mettre à jour ou supprimer des données personnalisées dans un groupe existant4. Add, update, or remove custom data in an existing group

Vous pouvez étendre et ajouter des données personnalisées pour une instance de groupe existante avec l’autre extension de type complexe graphlearn_courses définie dans le corps d’une demande PATCH.You can extend and add custom data to an existing group instance with the additional graphlearn_courses complex type extension defined in the body of a PATCH request.

DemandeRequest
PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json
Content-length: 230
{
    "graphlearn_courses":{
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
    }   
}
RéponseResponse
HTTP/1.1 204 No Content

Si vous souhaitez mettre à jour les valeurs des données d’extension, placez le type d’extension complexe entier dans le corps d’une requête PATCH (processus semblable à l’ajout de données personnalisées à une ressource existante).If you want to update the values of the extension data, put the entire extension complex type in the body of a PATCH request (similar to adding custom data to an existing resource).

Vous pouvez également supprimer des données personnalisées ajoutées à une instance de ressource en définissant la propriété d’extension correspondante sur Null.You can also remove custom data added to a resource instance by setting the corresponding extension property to null.

Pour supprimer une extension de schéma à partir d’une instance de ressource, définissez le type complexe d’extension dans cette instance sur Null.To remove a schema extension from a resource instance, set the extension complex type in that instance to null.

5. Obtention d’un groupe et de ses données d’extension5. Get a group and its extension data

Pour rechercher facilement un groupe (ou des groupes), vous pouvez utiliser $filter pour faire correspondre les valeurs de propriété d’extension spécifiques, telles qu’un nom d’extension ou un ID.A handy way to look for a group (or groups) is to use $filter to match for specific extension property values, such as an extension name or ID.

Ensuite, pour obtenir les données personnalisées dans un groupe, utilisez $select pour inclure l’extension selon le nom (dans ce cas selon graphlearn_courses).Then, to get the custom data in a group, use $select to include the extension by name (in this case by graphlearn_courses).

L’exemple suivant recherche le groupe qui contient l’extension graphlearn_courses avec une valeur de propriété courseId correspondant à 123 et obtient les propriétés de groupe displayName, id et description, ainsi que les données personnalisées dans l’extension graphlearn_courses. (Dans la requête réelle, veillez à appliquer un codage URL si nécessaire.)The following example looks for the group that has the graphlearn_courses extension with a courseId property value matching 123, and gets the group properties displayName, id, and description, and the custom data in the graphlearn_courses extension. (In the actual query, make sure you apply URL encoding as necessary.)

DemandeRequest

GET https://graph.microsoft.com/v1.0/groups?$filter=graphlearn_courses/courseId eq ‘123’&$select=displayName,id,description,graphlearn_courses
RéponseResponse
HTTP/1.1 200 OK
Content-Type: application/json
Content-length: 326
{
  "value": [
    {
      "displayName": "New Managers March 2017",
      "id": "14429ae5-3e74-41a2-9fa8-028fbb984637",
      "description": "New Managers training course for March 2017",
      "graphlearn_courses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
      }
    }
  ]
}

Voir aussiSee also