Представьте, что вы являетесь разработчиком в компании По управлению обучением под названием Bellows College , которая создает учебные курсы и материалы для бизнеса. Вы используете совместный опыт групп Microsoft 365 для предоставления содержимого курса и записи упражнений среди участников как для онлайн-курсов, так и для курсов под руководством инструктора. Вы хотите, чтобы группы Microsoft 365, используемые для учебных курсов, легко идентифицировались как учебные курсы, что позволит другим разработчикам обнаруживать ваши группы и создавать богатые возможности на основе ваших учебных курсов.
Для этого сценария в этой статье показано, как:
Найдите доступные определения расширений схемы, которые можно использовать.
зарегистрировать определение расширения схемы, ориентированное на группы для учебных курсов;
Создайте новую группу с пользовательскими данными на основе определения расширения схемы, которое вы зарегистрировали.
добавить, обновить или удалить пользовательские данные в существующей группе с помощью определения расширения схемы;
Чтение группы и данных расширения.
Удалите определение расширения схемы и данные расширения.
Примечание.
Помимо групп, поддерживаются и расширения схемы, которыми можно управлять для других типов ресурсов.
Предварительные требования
Чтобы воспроизвести действия, описанные в этой статье, вам потребуются следующие привилегии:
Предоставьте приложению делегированные разрешения 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'
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.SchemaExtensions.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "id eq 'bellowscollege_courses'";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
SchemaExtensionCollectionResponse result = graphClient.schemaExtensions().get(requestConfiguration -> {
requestConfiguration.queryParameters.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 приложения, которое вам назначено, в свойстве владельца .
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new SchemaExtension
{
Id = "bellowscollege_courses",
Description = "Bellows College training courses extensions",
TargetTypes = new List<string>
{
"Group",
},
Owner = "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
Properties = new List<ExtensionSchemaProperty>
{
new ExtensionSchemaProperty
{
Name = "courseId",
Type = "Integer",
},
new ExtensionSchemaProperty
{
Name = "courseName",
Type = "String",
},
new ExtensionSchemaProperty
{
Name = "courseType",
Type = "String",
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.SchemaExtensions.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
SchemaExtension schemaExtension = new SchemaExtension();
schemaExtension.setId("bellowscollege_courses");
schemaExtension.setDescription("Bellows College training courses extensions");
LinkedList<String> targetTypes = new LinkedList<String>();
targetTypes.add("Group");
schemaExtension.setTargetTypes(targetTypes);
schemaExtension.setOwner("d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2");
LinkedList<ExtensionSchemaProperty> properties = new LinkedList<ExtensionSchemaProperty>();
ExtensionSchemaProperty extensionSchemaProperty = new ExtensionSchemaProperty();
extensionSchemaProperty.setName("courseId");
extensionSchemaProperty.setType("Integer");
properties.add(extensionSchemaProperty);
ExtensionSchemaProperty extensionSchemaProperty1 = new ExtensionSchemaProperty();
extensionSchemaProperty1.setName("courseName");
extensionSchemaProperty1.setType("String");
properties.add(extensionSchemaProperty1);
ExtensionSchemaProperty extensionSchemaProperty2 = new ExtensionSchemaProperty();
extensionSchemaProperty2.setName("courseType");
extensionSchemaProperty2.setType("String");
properties.add(extensionSchemaProperty2);
schemaExtension.setProperties(properties);
SchemaExtension result = graphClient.schemaExtensions().post(schemaExtension);
В ответе начальное состояние расширения схемы по умолчанию — InDevelopment. Во время разработки расширения его можно оставить в этом состоянии, в течение которого только созданное приложение может обновить его с помощью добавок или удалить его. Когда вы будете готовы предоставить общий доступ к расширению для использования другими приложениями, установите для параметра СостояниеДоступно.
Этап 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"
}
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
DisplayName = "New Managers March 2024",
Description = "New Managers training course for March 2024",
GroupTypes = new List<string>
{
"Unified",
},
MailEnabled = true,
MailNickname = "newMan202403",
SecurityEnabled = false,
AdditionalData = new Dictionary<string, object>
{
{
"bellowscollege_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups create --body '{\
"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"\
}\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
group.setDisplayName("New Managers March 2024");
group.setDescription("New Managers training course for March 2024");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("newMan202403");
group.setSecurityEnabled(false);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
bellowscollegeCourses = new ();
bellowscollegeCourses.setCourseId("123");
bellowscollegeCourses.setCourseName("New Managers");
bellowscollegeCourses.setCourseType("Online");
additionalData.put("bellowscollege_courses", bellowscollegeCourses);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().post(group);
Ниже показан пример отклика. Ответ не включает новое расширение. Необходимо явно $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 ответ.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"bellowscollege_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Online",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups patch --group-id {group-id} --body '{\
"bellowscollege_courses": {\
"courseId": "123",\
"courseName": "New Managers",\
"courseType": "Online"\
}\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
bellowscollegeCourses = new ();
bellowscollegeCourses.setCourseId("123");
bellowscollegeCourses.setCourseName("New Managers");
bellowscollegeCourses.setCourseType("Online");
additionalData.put("bellowscollege_courses", bellowscollegeCourses);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);
Этап 4. Обновление пользовательских данных в группе
Следующий запрос обновляет свойство courseType в bellowscollege_courses расширении для группы до Hybrid. Хотя требуется обновить только свойство courseType , необходимо также включить другие свойства и их существующие значения в текст запроса. В противном случае Microsoft Graph задает для них значение null и удаляет их данные.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"bellowscollege_courses" , new
{
CourseId = "123",
CourseName = "New Managers",
CourseType = "Hybrid",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups patch --group-id {group-id} --body '{\
"bellowscollege_courses": {\
"courseId": "123",\
"courseName": "New Managers",\
"courseType": "Hybrid"\
}\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
bellowscollegeCourses = new ();
bellowscollegeCourses.setCourseId("123");
bellowscollegeCourses.setCourseName("New Managers");
bellowscollegeCourses.setCourseType("Hybrid");
additionalData.put("bellowscollege_courses", bellowscollegeCourses);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);
Чтобы получить пользовательские данные в группе, используйте $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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "bellowscollege_courses/courseId eq '123'";
requestConfiguration.QueryParameters.Select = new string []{ "displayName","id","description","bellowscollege_courses" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups list --filter "bellowscollege_courses/courseId eq '123'" --select "displayName,id,description,bellowscollege_courses"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "bellowscollege_courses/courseId eq '123'";
requestConfiguration.queryParameters.select = new String []{"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 ответ.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"bellowscollege_courses" , null
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("bellowscollege_courses", null);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.SchemaExtensions["{schemaExtension-id}"].DeleteAsync();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.schemaExtensions().bySchemaExtensionId("{schemaExtension-id}").delete();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->schemaExtensions()->bySchemaExtensionId('schemaExtension-id')->delete()->wait();
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.