Поделиться через


Добавление пользовательских данных в группы с помощью расширений схемы

В этом руководстве описано, как использовать расширения схемы.

Представьте, что вы являетесь разработчиком в компании По управлению обучением под названием Bellows College , которая создает учебные курсы и материалы для бизнеса. Вы используете совместный опыт групп Microsoft 365 для предоставления содержимого курса и записи упражнений среди участников как для онлайн-курсов, так и для курсов под руководством инструктора. Вы хотите, чтобы группы Microsoft 365, используемые для учебных курсов, легко идентифицировались как учебные курсы, что позволит другим разработчикам обнаруживать ваши группы и создавать богатые возможности на основе ваших учебных курсов.

Для этого сценария в этой статье показано, как:

  • Найдите доступные определения расширений схемы, которые можно использовать.
  • зарегистрировать определение расширения схемы, ориентированное на группы для учебных курсов;
  • Создайте новую группу с пользовательскими данными на основе определения расширения схемы, которое вы зарегистрировали.
  • добавить, обновить или удалить пользовательские данные в существующей группе с помощью определения расширения схемы;
  • Чтение группы и данных расширения.
  • Удалите определение расширения схемы и данные расширения.

Примечание.

Помимо групп, поддерживаются и расширения схемы, которыми можно управлять для других типов ресурсов.

Предварительные требования

Чтобы воспроизвести действия, описанные в этой статье, вам потребуются следующие привилегии:

  • Войдите в клиент API, например Graph Обозреватель.
  • Предоставьте приложению делегированные разрешения Group.ReadWrite.All и Application.ReadWrite.All для вошедшего пользователя.
  • Будьте владельцем приложения, которому вы назначаете право владения определением расширения схемы в этом руководстве. В этом руководстве приложение называется extensions-application и имеет appIdd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2.

Этап 1. Просмотр доступных расширений схемы

Во-первых, как разработчик может потребоваться, чтобы приложение повторно использует все существующие определения расширений схемы, если они подходят для целей. В следующем примере вы запрашиваете расширения схемы с именами (по идентификатору). 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": []
}

Вы также можете запросить идентификатор в качестве параметра пути следующим образом: GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses. Если нет расширений схемы, соответствующих идентификатору, ответом будет 404 Not Found.

Этап 2. Регистрация определения расширения схемы

Вы хотите создать и зарегистрировать новое определение расширения для учебных курсов в ресурсе группы . Укажите следующие свойства:

  • id: укажите строку для этого свойства одним из двух способов:
    • Вариант 1. Объединение проверенного доменного имени тщеславия для клиента с именем расширения схемы. Например, если домен — bellowscollege.com, а имя расширения схемы — courses, то можно использовать идентификаторbellowscollege_courses .

    • Вариант 2. Альтернативный способ — указать только имя схемы, например courses, и позволить Microsoft Graph автоматически создать идентификатор для вас путем префикса предоставленного имени случайной буквенно-цифровой строкой.

      Этот идентификатор становится именем свойства расширения схемы в группе.

  • description
  • targetTypes: укажите типы ресурсов, к которым можно применить расширение схемы. В этом примере тип ресурса — Group. Вы можете добавить дополнительные типы ресурсов, обновив определение расширения схемы позже.
  • properties: укажите настраиваемые свойства, составляющие схему. В этом примере укажите настраиваемые courseIdсвойства и , courseName а courseType также их типы. После создания определения расширения схемы допускаются только аддитивные изменения.
  • 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 и использует расширение схемы для расширения группы пользовательскими данными. Если у вас есть группа, ее можно также расширить с помощью пользовательских данных, обновив группу данными расширения.

Ответ не зеркало расширения данных. Необходимо явно $select использовать расширение по имени с помощью GET /group/{id} операции.

Запрос

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

Отклик

Ниже показан пример отклика. Ответ не включает новое расширение. Необходимо явно $select использовать расширение по имени с помощью GET /group/{id} операции.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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. Обновление пользовательских данных в группе

Следующий запрос обновляет свойство courseType в bellowscollege_courses расширении для группы до 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 для включения расширения по имени.

Помимо фильтрации по идентификатору расширения схемы, можно также выполнить фильтрацию по значениям свойств расширения. В следующем примере выполняется поиск группы с bellowscollege_courses расширением со значением courseId свойства, соответствующим 123, и получает данные расширения и свойства 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. Удаление данных расширения и определения расширения схемы

Вы можете удалить определение расширения схемы, если оно больше не требуется. Если к экземплярам ресурсов применено свойство расширения, удаление определения расширения схемы не приводит к удалению данных расширения в экземплярах ресурсов. Вместо этого данные расширения доступны, но больше не доступны. Чтобы удалить данные расширения схемы, можно повторно создать определение расширения схемы с той же конфигурацией, если вы использовали проверенный домен для идентификатора расширения схемы.

Следующий запрос удаляет 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