Добавление пользовательских данных в группы с помощью расширений схемы
Статья
В этой статье показано, как использовать расширения схемы.
Представьте, что вы являетесь разработчиком в компании по управлению обучением под названием Graph Learn, которая создает учебные курсы и материалы для бизнеса. Вы используете совместный опыт групп Microsoft 365 для предоставления содержимого курса и записи упражнений среди участников как для онлайн-курсов, так и для курсов под руководством инструктора. Вы хотите, чтобы группы Microsoft 365, используемые для учебных курсов, легко идентифицировались как учебные курсы, что позволит другим разработчикам обнаружить ваши группы и создать богатый опыт на основе ваших учебных курсов.
Для этого сценария в этой статье показано, как:
просмотреть доступные определения расширений схемы;
зарегистрировать определение расширения схемы, ориентированное на группы для учебных курсов;
Создайте новую группу с пользовательскими данными на основе определения расширения схемы, которое вы зарегистрировали.
добавить, обновить или удалить пользовательские данные в существующей группе с помощью определения расширения схемы;
Чтение группы и данных расширения.
Примечание.
Помимо групп, поддерживаются и расширения схемы, которыми можно управлять для других типов ресурсов.
1. Просмотр доступных расширений схемы
Во-первых, как разработчику может потребоваться найти другие определения расширений схемы, которые наше приложение может повторно использовать.
В следующем примере вы запрашиваете ресурс schemaExtension для определенного расширения схемы по его идентификатору.
Обратите внимание, что расширение, возвращаемое в ответе, имеет значение Available в качестве значения состояния , указывающее, что любое приложение, которое имеет разрешение на доступ к ресурсам в свойстве targetTypes , может использовать и обновлять расширение с помощью добавок. Как правило, эта операция возвращает все расширения схемы, удовлетворяющие указанному фильтру независимо от состояния, поэтому перед его использованием проверка состояние расширения.
GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'graphlearn_test'
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.SchemaExtensions.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "id eq 'graphlearn_test'";
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new SchemaExtensionsRequestBuilderGetRequestConfiguration();
$queryParameters = SchemaExtensionsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "id eq 'graphlearn_test'";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->schemaExtensions()->get($requestConfiguration);
2. Регистрация определения расширения схемы, описывающего учебный курс
Если вам не удастся найти расширение схемы, соответствующее вашим потребностям, вы можете создать и зарегистрировать новое определение расширения для учебных курсов в ресурсе group.
При создании определения расширения схемы необходимо указать строку для свойства id . Предположим, что вы проверили домен graphlearn.com тщеславия с клиентом, вы объедините проверенное доменное имя (graphlearn) с именем для расширения схемы (courses) и назначите идентификатор с результирующей строкой , graphlearn_courses. Этот идентификатор становится именем свойства расширения схемы в группе. См. пример другого способа назначения идентификатора в запросе , который требует указать только имя схемы.
Затем укажите описание, целевые ресурсы, к которым применяется это расширение, и пользовательские свойства, составляющие схему. В этом примере укажите настраиваемые courseIdсвойства и , courseName а courseType также их типы.
Обратите внимание, что при первоначальном создании расширения схемы его состояние — InDevelopment. Во время разработки расширения его можно сохранить в этом состоянии, в течение которого только созданное приложение может обновить его с помощью добавок или удалить его. Когда вы будете готовы предоставить общий доступ к расширению для использования другими приложениями, установите для параметра СостояниеДоступно.
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new SchemaExtension
{
Id = "graphlearn_courses",
Description = "Graph Learn training courses extensions",
TargetTypes = new List<string>
{
"Group",
},
Properties = new List<ExtensionSchemaProperty>
{
new ExtensionSchemaProperty
{
Name = "courseId",
Type = "Integer",
},
new ExtensionSchemaProperty
{
Name = "courseName",
Type = "String",
},
new ExtensionSchemaProperty
{
Name = "courseType",
Type = "String",
},
},
};
var result = await graphClient.SchemaExtensions.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new SchemaExtension();
$requestBody->setId('graphlearn_courses');
$requestBody->setDescription('Graph Learn training courses extensions');
$requestBody->setTargetTypes(['Group', ]);
$propertiesExtensionSchemaProperty1 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty1->setName('courseId');
$propertiesExtensionSchemaProperty1->setType('Integer');
$propertiesArray []= $propertiesExtensionSchemaProperty1;
$propertiesExtensionSchemaProperty2 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty2->setName('courseName');
$propertiesExtensionSchemaProperty2->setType('String');
$propertiesArray []= $propertiesExtensionSchemaProperty2;
$propertiesExtensionSchemaProperty3 = new ExtensionSchemaProperty();
$propertiesExtensionSchemaProperty3->setName('courseType');
$propertiesExtensionSchemaProperty3->setType('String');
$propertiesArray []= $propertiesExtensionSchemaProperty3;
$requestBody->setProperties($propertiesArray);
$result = $graphServiceClient->schemaExtensions()->post($requestBody);
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"
}
}
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Group
{
DisplayName = "New Managers March 2017",
Description = "New Managers training course for March 2017",
GroupTypes = new List<string>
{
"Unified",
},
MailEnabled = true,
MailNickname = "newMan201703",
SecurityEnabled = false,
AdditionalData = new Dictionary<string, object>
{
{
"graphlearn_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
var result = await graphClient.Groups.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Group();
$requestBody->setDisplayName('New Managers March 2017');
$requestBody->setDescription('New Managers training course for March 2017');
$requestBody->setGroupTypes(['Unified', ]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('newMan201703');
$requestBody->setSecurityEnabled(false);
$additionalData = [
'graphlearn_courses' => $requestBody = new Graphlearn_courses();
$ requestBody->setCourseId('123');
$ requestBody->setCourseName('New Managers');
$ requestBody->setCourseType('Online');
$requestBody->setGraphlearn_courses($graphlearn_courses);
];
$requestBody->setAdditionalData($additionalData);
$result = $graphServiceClient->groups()->post($requestBody);
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"graphlearn_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Group();
$additionalData = [
'graphlearn_courses' => $requestBody = new Graphlearn_courses();
$ requestBody->setCourseId('123');
$ requestBody->setCourseName('New Managers');
$ requestBody->setCourseType('Online');
$requestBody->setGraphlearn_courses($graphlearn_courses);
];
$requestBody->setAdditionalData($additionalData);
$result = $graphServiceClient->groups()->byGroupId('group-id')->patch($requestBody);
Если вы хотите обновить значения данных расширения, поместите весь сложный тип расширения в тексте запроса 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
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "graphlearn_courses/courseId eq '123'";
requestConfiguration.QueryParameters.Select = new string []{ "displayName","id","description","graphlearn_courses" };
});
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "graphlearn_courses/courseId eq '123'";
$queryParameters->select = ["displayName","id","description","graphlearn_courses"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->groups()->get($requestConfiguration);
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"
}
}
]
}