通过

使用架构扩展向组添加自定义数据

本教程介绍如何使用 架构扩展。

假设你是一家名为 Bellows College 的学习管理软件公司的开发人员，该公司为企业构建培训课程和材料。 你利用Microsoft 365 个小组的协作体验，为在线课程和讲师引导式课程的参与者提供课程内容和记录练习。 你希望使用于培训课程的Microsoft 365 组易于识别为培训课程，这使其他开发人员能够发现你的组，并在学习课程的基础上构建丰富的体验。

对于此方案，本文介绍如何：

  • 发现可以使用的可用架构扩展定义。
  • 注册以培训课程组为目标的架构扩展定义。
  • 根据注册的架构扩展定义创建包含自定义数据的新组。
  • 根据架构扩展定义向现有组添加、更新或删除自定义数据。
  • 读取组和扩展数据。
  • 删除架构扩展定义和扩展数据。

注意

除组外，还支持架构扩展，并且可以针对 其他资源类型进行管理。

先决条件

若要重现本文中的步骤，需要具有以下权限：

  • 登录到 API 客户端，例如 Graph 资源管理器。
  • 为应用授予已登录用户的 Group.ReadWrite.All 和 Application.ReadWrite.All 委派权限。
  • 成为在本教程中分配架构扩展定义的所有权的应用程序的所有者。 在本教程中，该应用程序名为 extensions-application ，并且具有 appIdd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2。

步骤 1. 查看可用的架构扩展

首先，作为开发人员，你可能希望应用重用任何现有架构扩展定义（如果它们适合用途）。 在以下示例中，查询由 id) 命名为 (的 bellowscollege_courses架构扩展。 假设响应显示租户中没有命名 bellowscollege_courses 的架构扩展。

请求

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

响应

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

还可以按 ID 作为路径参数进行查询，如下所示： GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses。 如果没有与 ID 匹配的架构扩展，则响应为 404 Not Found。

步骤 2. 注册架构扩展定义

你希望为 组 资源上的培训课程创建和注册新的扩展定义。 指定以下属性：

  • id： 必需。 按照以下两种方式之一为此属性提供字符串：

    • 选项 1：将租户 的已验证 虚域名与架构扩展的名称连接在一起。 例如，如果域为 bellowscollege.com，并且架构扩展的名称为 courses，则可以使用 IDbellowscollege_courses。如果使用未通过租户验证的域名，请求将失败。

    • 选项 2：另一种方法是仅提供架构名称（如 courses），并让 Microsoft Graph 通过为提供的名称添加随机字母数字字符串的前缀来自动生成 ID 。

      此 ID 将成为组上的架构扩展属性的名称。

  • description： 可选。

  • targetTypes： 必需。 指定架构扩展可应用于的资源类型。 在此示例中，资源类型为 Group。 可以通过稍后更新架构扩展定义来添加更多资源类型。 创建架构扩展定义后，仅允许进行累加更改。

  • 属性： 必需。 指定构成架构的自定义属性。 在此示例中，指定 courseId、 courseName和 courseType 自定义属性及其类型。 创建架构扩展定义后，仅允许进行累加更改。

  • owner： 有条件。 指定拥有架构扩展定义的应用程序。 如果从未分配为所有者的应用运行此示例，请在 owner 属性中指定你分配的应用程序的 appId。

请求

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

响应

以下示例显示了相应的响应。

在响应中，架构扩展的默认初始状态为 InDevelopment。 开发扩展时，可以将其保持此状态，在此期间，只有创建扩展的应用才能使用累加更改来更新它或删除它。 准备好共享扩展以供其他应用使用时，请将 状态 设置为 “可用”。

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

步骤 3. 使用自定义数据扩展组

可以使用自定义数据在组创建期间扩展组，也可以通过更新现有组来扩展组。

选项 1：使用扩展数据创建新组

以下请求创建一个新组， bellowscollege_courses 并使用架构扩展来扩展包含自定义数据的组。 如果有现有组，则还可以使用扩展数据更新该组，从而使用自定义数据对其进行扩展。

响应不会镜像备份任何数据扩展插件。 需要使用 操作按名称GET /group/{id}显式扩展$select。

请求

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

响应

以下示例显示了相应的响应。 响应不包括新扩展。 需要使用 操作按名称GET /group/{id}显式扩展$select。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

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

选项 2：使用扩展数据更新现有组

如果有现有组，还可以使用自定义数据对其进行扩展，如下所示。 请求返回 204 No Content 响应。

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

步骤 4. 更新组中的自定义数据

以下请求将组的扩展中的 bellowscollege_coursescourseType 属性更新为 Hybrid。 虽然只想更新 courseType 属性，但还必须在请求正文中包含其他属性及其现有值。 否则，Microsoft Graph 将它们设置为 null 并删除其数据。

以下请求返回 204 No Content 响应。

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

步骤 5. 获取组及其扩展数据

若要获取组中的自定义数据，请使用 $select 按名称包含扩展。

除了按架构扩展的 ID 进行筛选外，还可以按扩展属性值进行筛选。 以下示例查找具有 属性值匹配 123的bellowscollege_courses扩展名courseId的组，并获取该组的扩展数据以及 displayName、id 和 description 属性。

请求

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

响应

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

步骤 6：删除扩展数据和架构扩展定义

如果不再需要架构扩展定义，可以将其删除。 如果资源实例应用了扩展属性，则删除架构扩展定义不会删除资源实例中的扩展数据。 相反，扩展数据可用，但不再可访问。 可以使用相同的配置重新创建架构扩展定义（如果使用架构扩展 ID 的已验证域）以便能够删除扩展数据。

以下请求从组中删除 bellowscollege_courses 架构扩展属性及其关联数据。 请求返回 204 No Content 响应。

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

{
    "bellowscollege_courses": null
}

以下请求删除 bellowscollege_courses 架构扩展定义。 请求返回 204 No Content 响应。

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

相关内容