使用架构扩展向组添加自定义数据Add custom data to groups using schema extensions

本文将通过一个示例逐步介绍如何使用架构扩展This article walks you through an example to demonstrate how to use schema extensions.

假设你是一个名为“Graph Learn”的学习管理软件公司的开发人员,工作是为企业构建培训课程和材料。Microsoft 365 组具有丰富的协作体验,是为在线课程和教师引导式课程的参与者提供交付课程内容和记录练习的绝佳方式。你可能希望将那些 Microsoft 365 组用于使培训课程可轻松地被识别为培训课程,从而使其他开发人员可以发现你的组,并在你的学习课程的基础上构建丰富的体验。Imagine you're a developer in a Learning Management Software company called “Graph Learn” that builds training courses and materials for businesses. Microsoft 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 might want to make those Microsoft 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.

在此情况下,本文将介绍如何:For this scenario, this article will show you how to:

  1. 查看可以使用的可用架构扩展定义。View available schema extension definitions that you could use.
  2. 注册以培训课程组为目标的架构扩展定义。Register a schema extension definition that targets groups for training courses.
  3. 根据你刚刚注册的架构扩展定义,创建具有扩展数据的新组。Create a new group with extended data based on the schema extension definition that you just registered.
  4. 根据架构扩展定义向现有组添加、更新或删除自定义数据。Add, update, or remove custom data in an existing group based on a schema extension definition.
  5. 读回组和扩展数据。Read back a group and the extension data.

注意: 本主题介绍如何在资源上创建和读取架构扩展值(步骤 3-5)。管理单元设备事件邮件组织帖子用户资源类型也支持相同方法。你可以对任意资源执行与本文中的请求示例相似的操作。请注意,administrativeUnit 仅适用于 beta 终结点。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. You can carry out operations similar to the request examples in this article on any of those resources. Note that administrativeUnit is available only in the beta endpoint.

1.查看可用的架构扩展1. View available schema extensions

首先,作为开发人员,可能希望找到应用可以重复使用的任何其他架构扩展定义。这可以通过查询 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.
在下面的示例中,将按 id 查询特定的架构扩展。In the example below, you're going to query for a specific schema extension by id.

请注意响应中返回的扩展将可用作为状态值,即表示具有 targetTypes 属性中的资源访问权限的所有应用都可使用此扩展并通过增量更改更新此扩展。通常,无论状态如何,此操作都将返回满足指定筛选器的所有架构扩展,因此在使用扩展前请务必先检查其状态。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.

请求Request

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

响应Response

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.注册可描述培训课程的架构扩展定义2. Register a schema extension definition that describes a training course

如果找不到符合你的需求的架构扩展,则可以在资源上为培训课程创建并注册新的扩展定义。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.

在创建架构扩展定义时,应为 id 属性提供一个字符串。可以通过两种方式来执行此操作。以下示例演示首选方法,它使用一个经租户验证的虚域名 (graphlearn.com)。将验证的域名 (graphlearn) 与架构扩展的名称 (courses) 相连接,并使用结果字符串 graphlearn_courses 分配 idWhen 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.

然后,还要指定说明(以启用可发现性)、目标类型(定义该扩展适用于哪些资源)以及构成架构的自定义属性。在本示例中,指定 courseIdcourseNamecourseType 自定义属性及其类型。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.

请参阅分配请求中 id 的其他方法示例,仅需要提供架构名称。See an example of the other way to assign id in the request, that requires you to provide only a schema name.

请注意,初次创建架构扩展时,其状态是 InDevelopment。在开发扩展期间,可以将其保持在此状态,在此期间仅创建该扩展的应用可以使用增量更改更新它或将其删除。准备共享此扩展以供其他应用使用时,请将状态设置为可用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.

请求Request

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

响应Response

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.创建具有扩展数据的新组3. Create a new group with extended data

使用我们刚刚注册的 graphlearn_courses 架构扩展定义创建一个_新_组并使用额外数据进行扩展。这是资源的标准 POST,其他 graphlearn_courses 复杂类型扩展在请求正文中定义。响应将不会返回任何数据扩展的镜像。我们需要使用 GET 操作按名称显式 $select 扩展。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.

请求Request

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

响应Response

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.在现有组中添加、更新或删除自定义数据4. Add, update, or remove custom data in an existing group

可以使用在 PATCH 请求的正文中定义的其他 graphlearn_courses 复杂类型扩展来扩展自定义数据并将其添加到_现有_组实例。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.

请求Request

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

响应Response

HTTP/1.1 204 No Content

如果要更新扩展数据的值,请将整个扩展复杂类型置于 PATCH 请求正文中(类似于向现有资源添加自定义数据)。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).

还可以将相应的扩展属性设置为 null,从而删除添加到资源实例中的自定义数据。You can also remove custom data added to a resource instance by setting the corresponding extension property to null.

若要将架构扩展从资源实例中删除,请将该实例中的扩展复杂类型设置为 null。To remove a schema extension from a resource instance, set the extension complex type in that instance to null.

5.获取组及其扩展数据5. Get a group and its extension data

查找组的简便方法有:使用 $filter 匹配特定的扩展属性值,比如扩展名或 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.

然后,使用 $select 按名称包含扩展(在此情况下按 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).

下面的示例查找了具有 graphlearn_courses 扩展且 courseId 属性值与 123 相匹配的组,获取了组属性 displayNameiddescription,以及 graphlearn_courses 扩展中的自定义数据。(在实际查询中,请确保根据需要应用 URL 编码。)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.)

请求Request

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

响应Response

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

另请参阅See also