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

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

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

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

  1. просмотреть доступные определения расширений схемы;
  2. зарегистрировать определение расширения схемы, ориентированное на группы для учебных курсов;
  3. Создайте новую группу с пользовательскими данными на основе определения расширения схемы, которое вы зарегистрировали.
  4. добавить, обновить или удалить пользовательские данные в существующей группе с помощью определения расширения схемы;
  5. Чтение группы и данных расширения.

Примечание.

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

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

Во-первых, как разработчику может потребоваться найти другие определения расширений схемы, которые наше приложение может повторно использовать.

В следующем примере вы запрашиваете ресурс schemaExtension для определенного расширения схемы по его идентификатору.

Обратите внимание, что расширение, возвращаемое в ответе, имеет значение Available в качестве значения состояния , указывающее, что любое приложение, которое имеет разрешение на доступ к ресурсам в свойстве targetTypes , может использовать и обновлять расширение с помощью добавок. Как правило, эта операция возвращает все расширения схемы, удовлетворяющие указанному фильтру независимо от состояния, поэтому перед его использованием проверка состояние расширения.

Запрос

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

Ответ

HTTP/1.1 200 OK
Content-Type: application/json

{
    "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. Регистрация определения расширения схемы, описывающего учебный курс

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

При создании определения расширения схемы необходимо указать строку для свойства id . Предположим, что вы проверили домен graphlearn.com тщеславия с клиентом, вы объедините проверенное доменное имя (graphlearn) с именем для расширения схемы (courses) и назначите идентификатор с результирующей строкой , graphlearn_courses. Этот идентификатор становится именем свойства расширения схемы в группе. См. пример другого способа назначения идентификатора в запросе , который требует указать только имя схемы.

Затем укажите описание, целевые ресурсы, к которым применяется это расширение, и пользовательские свойства, составляющие схему. В этом примере укажите настраиваемые courseIdсвойства и , courseName а courseType также их типы.

Обратите внимание, что при первоначальном создании расширения схемы его состояние — InDevelopment. Во время разработки расширения его можно сохранить в этом состоянии, в течение которого только созданное приложение может обновить его с помощью добавок или удалить его. Когда вы будете готовы предоставить общий доступ к расширению для использования другими приложениями, установите для параметра СостояниеДоступно.

Запрос

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

Ответ

HTTP/1.1 201 Created
Content-Type: application/json

{
    "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. Создание новой группы с расширенными данными

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

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

Запрос

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

Ответ

HTTP/1.1 201 Created
Content-Type: application/json

{
    "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. Добавление, обновление и удаление пользовательских данных существующей группы

Теперь вы можете расширить и добавить пользовательские данные в созданную группу, обновив сложный graphlearn_courses тип следующим образом.

Запрос

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "graphlearn_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

Ответ

HTTP/1.1 204 No Content

Если вы хотите обновить значения данных расширения, поместите весь сложный тип расширения в тексте запроса PATCH (так же, как и при добавлении пользовательских данных к существующему ресурсу).

Чтобы удалить пользовательские данные, добавленные в экземпляр ресурса, но сохранить свойство расширения схемы в экземпляре ресурса, задайте для соответствующего свойства расширения значение null.

Чтобы удалить расширение схемы из экземпляра ресурса, присвойте сложному типу расширения в этом экземпляре значение null.

5. Получение экземпляра group и его данных расширения

Удобный способ найти группу (или группы) — применить $filter с указанием определенных значений свойства расширения, например идентификатора или имени расширения.

Затем, чтобы получить пользовательские данные группы, примените $select, чтобы включить расширение с указанием имени (в данном случае graphlearn_courses).

В следующем примере выполняется поиск группы с graphlearn_courses расширением со значением courseId свойства, соответствующим 123, и возвращает свойства группы displayName, id и description, а также пользовательские данные в graphlearn_courses расширении.

Запрос

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

Отклик

HTTP/1.1 200 OK
Content-Type: application/json

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

См. также