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

  • 项目

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

假设你是一家名为 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。 可以通过稍后更新架构扩展定义来添加更多资源类型。
  • properties：指定构成架构的自定义属性。 在本示例中，指定 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

相关内容