Добавление пользовательских данных в ресурсы с помощью расширений
Статья
Microsoft Graph предоставляет единую конечную точку API для доступа к аналитическим данным и сведениям, ориентированным на людей, с помощью таких ресурсов, как пользователь и сообщение. Вы также можете расширить Microsoft Graph, добавив настраиваемые свойства в экземпляры ресурсов без необходимости во внешнем хранилище данных.
В этой статье описывается, как Microsoft Graph поддерживает расширение своих ресурсов, доступные параметры для добавления пользовательских свойств и когда их использовать.
Важно!
Не используйте расширения для хранения конфиденциальных личных сведений, таких как учетные данные, государственные идентификационные номера, данные держателя карты, данные финансового счета, медицинские сведения или конфиденциальные справочные сведения.
Зачем добавлять пользовательские данные в Microsoft Graph?
Как независимый разработчик, вы можете решить сохранить легкость своего приложения и хранить данные профиля пользователя для конкретного приложения в Microsoft Graph, расширив ресурс пользователя.
Кроме того, может потребоваться сохранить существующее хранилище профилей пользователей приложения и добавить в ресурс пользователя идентификатор приложения.
Как корпоративный разработчик, создавая внутренние приложения, вы можете полагаться на связанные с персоналом данные своей организации. Интеграцию в нескольких приложениях можно упростить, сохранив эти пользовательские данные в Microsoft Graph.
Настраиваемые параметры данных в Microsoft Graph
Microsoft Graph предлагает четыре типа расширений для добавления пользовательских данных.
Атрибуты расширения
Расширения каталога (Microsoft Entra ID)
Расширения схемы
Открытые расширения
Атрибуты расширения
Microsoft Entra ID предлагает набор из 15 атрибутов расширения с предопределенными именами для ресурсов пользователя и устройства. Эти свойства изначально были настраиваемыми атрибутами, предоставляемыми в локальной среде Active Directory (AD) и Microsoft Exchange. Однако теперь их можно использовать не только для синхронизации локальных данных AD и Microsoft Exchange с Microsoft Entra ID через Microsoft Graph.
Среда разработки
Вы можете использовать 15 атрибутов расширения для хранения значений строки в экземплярах ресурсов пользователя или устройства через свойства onPremisesExtensionAttributes и extensionAttributes соответственно. Значения можно назначить при создании нового экземпляра ресурса или при обновлении существующего экземпляра ресурса. Вы также можете фильтровать по значениям.
Добавление или обновление данных в атрибутах расширения
В следующем примере показано, как хранить данные в extensionAttribute1 и удалять существующие данные из extensionAttribute13 с помощью операции обновления с помощью метода PATCH.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
OnPremisesExtensionAttributes = new OnPremisesExtensionAttributes
{
ExtensionAttribute1 = "skypeId.adeleVance",
ExtensionAttribute13 = null,
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
onPremisesExtensionAttributes := graphmodels.NewOnPremisesExtensionAttributes()
extensionAttribute1 := "skypeId.adeleVance"
onPremisesExtensionAttributes.SetExtensionAttribute1(&extensionAttribute1)
extensionAttribute13 := null
onPremisesExtensionAttributes.SetExtensionAttribute13(&extensionAttribute13)
requestBody.SetOnPremisesExtensionAttributes(onPremisesExtensionAttributes)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
OnPremisesExtensionAttributes onPremisesExtensionAttributes = new OnPremisesExtensionAttributes();
onPremisesExtensionAttributes.setExtensionAttribute1("skypeId.adeleVance");
onPremisesExtensionAttributes.setExtensionAttribute13(null);
user.setOnPremisesExtensionAttributes(onPremisesExtensionAttributes);
User result = graphClient.users().byUserId("{user-id}").patch(user);
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\User;
use Microsoft\Graph\Generated\Models\OnPremisesExtensionAttributes;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new User();
$onPremisesExtensionAttributes = new OnPremisesExtensionAttributes();
$onPremisesExtensionAttributes->setExtensionAttribute1('skypeId.adeleVance');
$onPremisesExtensionAttributes->setExtensionAttribute13(null);
$requestBody->setOnPremisesExtensionAttributes($onPremisesExtensionAttributes);
$result = $graphServiceClient->users()->byUserId('user-id')->patch($requestBody)->wait();
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,onPremisesExtensionAttributes
// 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.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","onPremisesExtensionAttributes" };
});
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","onPremisesExtensionAttributes"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "onPremisesExtensionAttributes"};
});
Рекомендации по использованию свойств атрибута расширения
Объект onPremisesExtensionAttributes можно обновить только для объектов, которые не синхронизированы из локальной службы AD.
15 атрибутов расширения уже предопределены в Microsoft Graph, и их имена свойств нельзя изменить. Поэтому для атрибутов расширения нельзя использовать пользовательские имена, такие как SkypeId . Поэтому ваша организация должна отслеживать используемые свойства атрибута расширения, чтобы избежать случайной перезаписи данных.
Расширения каталога (Microsoft Entra ID)
Расширения каталогов предоставляют разработчикам строго типизированные, обнаруживаемые и фильтруемые расширения для объектов каталога.
Расширения каталогов сначала регистрируются в приложении с помощью операции Create extensionProperty и должны быть явно ориентированы на конкретные и поддерживаемые объекты каталога. После того как пользователь или администратор предоставил согласие на использование приложения в клиенте, свойства расширения сразу же становятся доступными в клиенте. Все авторизованные приложения в клиенте могут считывать и записывать данные о любых свойствах расширения, определенных для экземпляра целевого объекта каталога.
Список типов ресурсов, которые можно указать в качестве целевых объектов для расширения каталога, см. в разделе Сравнение типов расширений.
Среда разработки
Определения расширения каталога управляются с помощью ресурса extensionProperty и связанных с ним методов. Управление данными осуществляется с помощью запросов REST API, которые используются для управления экземпляром ресурса.
Определение расширения каталога
Перед добавлением расширения каталога в экземпляр ресурса необходимо сначала определить расширение каталога.
Запрос
В следующем запросе — это идентификатор объекта приложения, 30a5435a-1871-485c-8c7b-65f69e287e7b которому принадлежит расширение каталога. Можно создать расширения каталогов, которые хранят коллекцию значений.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new ExtensionProperty
{
Name = "jobGroupTracker",
DataType = "String",
TargetObjects = new List<string>
{
"User",
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications["{application-id}"].ExtensionProperties.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtensionProperty()
name := "jobGroupTracker"
requestBody.SetName(&name)
dataType := "String"
requestBody.SetDataType(&dataType)
targetObjects := []string {
"User",
}
requestBody.SetTargetObjects(targetObjects)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensionProperties, err := graphClient.Applications().ByApplicationId("application-id").ExtensionProperties().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ExtensionProperty extensionProperty = new ExtensionProperty();
extensionProperty.setName("jobGroupTracker");
extensionProperty.setDataType("String");
LinkedList<String> targetObjects = new LinkedList<String>();
targetObjects.add("User");
extensionProperty.setTargetObjects(targetObjects);
ExtensionProperty result = graphClient.applications().byApplicationId("{application-id}").extensionProperties().post(extensionProperty);
Именованное свойство расширения каталога extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker создается с именем расширения, соответствующим следующему соглашению об именовании: extension_{appId-without-hyphens}_{extensionProperty-name}.
Добавление свойства расширения каталога к целевому объекту
После определения расширения каталога его можно добавить в экземпляр целевого типа объекта. Данные можно хранить в расширении каталога при создании нового экземпляра целевого объекта или при обновлении существующего объекта. В следующем примере показано, как хранить данные в расширении каталога при создании нового объекта пользователя .
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
AccountEnabled = true,
DisplayName = "Adele Vance",
MailNickname = "AdeleV",
UserPrincipalName = "AdeleV@contoso.com",
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d",
},
AdditionalData = new Dictionary<string, object>
{
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" , "JobGroupN"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
user.setAccountEnabled(true);
user.setDisplayName("Adele Vance");
user.setMailNickname("AdeleV");
user.setUserPrincipalName("AdeleV@contoso.com");
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.setForceChangePasswordNextSignIn(false);
passwordProfile.setPassword("xWwvJ]6NMw+bWH-d");
user.setPasswordProfile(passwordProfile);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "JobGroupN");
user.setAdditionalData(additionalData);
User result = graphClient.users().post(user);
Запрос возвращает код отклика 201 Created и объект пользователь в тексте отклика.
Получение расширения каталога
В следующем примере показано, как расширения каталога и связанные данные представлены в экземпляре ресурса. Свойство расширения возвращается по умолчанию через конечную точку beta , но только через $select конечную точку v1.0 .
GET https://graph.microsoft.com/beta/users?$select=id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable
// 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.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker","extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable" };
});
mgc-beta users list --select "id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker","extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable"};
});
Чтобы обновить или удалить значение расширения каталога для экземпляра ресурса, используйте метод PATCH. Чтобы удалить свойство расширения и связанное с ним значение, присвойте ей значение null.
Следующий запрос обновляет значение одного расширения каталога и удаляет другое свойство расширения.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new User
{
AdditionalData = new Dictionary<string, object>
{
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable" , null
},
{
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" , "E4"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
additionalData := map[string]interface{}{
extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable := null
requestBody.SetExtension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable(&extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable)
"extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker" : "E4",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable", null);
additionalData.put("extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker", "E4");
user.setAdditionalData(additionalData);
User result = graphClient.users().byUserId("{user-id}").patch(user);
Рекомендации по использованию расширений каталогов
При случайном удалении определения расширения каталога все данные, хранящиеся в связанном свойстве, становятся неоткрытыми. Чтобы восстановить данные, создайте новое определение расширения каталога с тем же именем, что и удаленное определение, в том же приложении-владельце.
Когда объект определения удаляется до обновления соответствующего свойства расширения до null, свойство учитывается в 100-предельном значении для объекта .
При удалении определения перед удалением данных в связанном свойстве расширения невозможно узнать о существовании свойства расширения с помощью Microsoft Graph, несмотря на то, что свойство undiscoverable учитывается с ограничением в 100.
Удаление приложения-владельца в домашнем клиенте делает связанные расширения каталогов и их данные недоступными для обнаружения. При восстановлении приложения-владельца оно восстанавливает определения расширений каталога, но не делает свойства расширения каталога или их данные немедленно обнаруживаемыми. поскольку восстановление приложения не приводит к автоматическому восстановлению связанного субъекта-службы в клиенте. Чтобы сделать свойства расширения каталога и их данные обнаруживаемыми, создайте новый субъект-службу или восстановите удаленный субъект-службу. Никакие изменения не вносятся в другие клиенты, для которых приложение было предоставлено согласие.
Расширения схемы
Расширения схемыMicrosoft Graph концептуально похожи на расширения каталогов. Сначала необходимо определить расширение схемы. Затем используйте его для расширения поддерживаемых экземпляров ресурсов строго типизированными настраиваемыми свойствами. Кроме того, вы можете контролировать состояние расширения схемы и сделать его доступным другим приложениям.
При создании определения расширения схемы необходимо присвоить уникальное имя его свойству id. Есть два варианта:
Если у вас уже есть тщеславие .com.net, или .org домен, .gov.edu проверенный клиентом, вы можете использовать доменное имя вместе с именем схемы, чтобы определить уникальное имя в этом формате {domainName}_{schemaName}. Например, если ваш личный домен — contoso.com, вы можете определить идентификатор для contoso_mySchema. Этот параметр настоятельно рекомендуется.
Кроме того, можно задать для идентификатора имя схемы (без префикса доменного имени). Например, mySchema. Microsoft Graph назначает идентификатор строки на основе предоставленного имени в следующем формате: ext{8-random-alphanumeric-chars}_{schema-name}. Например, extkvbmkofy_mySchema.
Идентификатор — это имя сложного типа, в котором хранятся данные в расширенном экземпляре ресурса.
После регистрации расширения схемы оно будет доступно для использования всеми приложениями в том же клиенте, что и связанное приложение-владелец (в InDevelopment состоянии) или всеми приложениями в любом клиенте Available (в состоянии ). Как и расширения каталогов, авторизованные приложения могут считывать и записывать данные о любых расширениях, определенных для целевого объекта.
Вы управляете определениями расширений схемы и данными в соответствующем свойстве расширения схемы с помощью отдельных наборов операций API. Для управления данными расширения схемы в экземпляре расширенного ресурса используйте тот же запрос REST, что и для управления экземпляром ресурса.
Используйте POST для хранения данных в свойстве расширения схемы при создании нового пользователя.
Используйте PATCH для хранения данных в свойстве расширения схемы или обновления или удаления сохраненных данных.
Чтобы удалить данные из свойства, присвойте nullей значение .
Чтобы удалить данные из всех свойств, задайте для каждого свойства значение null. Если все свойства имеют значение null, объект расширения схемы также удаляется.
Чтобы обновить любое свойство, укажите только измененные свойства в тексте запроса. Пропущенные свойства не обновляются и сохраняют свое предыдущее значение.
Используйте GET, чтобы прочитать свойства расширения схемы для всех пользователей или отдельных пользователей в клиенте.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new SchemaExtension
{
Id = "graphLearnCourses",
Description = "Graph Learn training courses extensions",
TargetTypes = new List<string>
{
"user",
},
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 major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewSchemaExtension()
id := "graphLearnCourses"
requestBody.SetId(&id)
description := "Graph Learn training courses extensions"
requestBody.SetDescription(&description)
targetTypes := []string {
"user",
}
requestBody.SetTargetTypes(targetTypes)
extensionSchemaProperty := graphmodels.NewExtensionSchemaProperty()
name := "courseId"
extensionSchemaProperty.SetName(&name)
type := "Integer"
extensionSchemaProperty.SetType(&type)
extensionSchemaProperty1 := graphmodels.NewExtensionSchemaProperty()
name := "courseName"
extensionSchemaProperty1.SetName(&name)
type := "String"
extensionSchemaProperty1.SetType(&type)
extensionSchemaProperty2 := graphmodels.NewExtensionSchemaProperty()
name := "courseType"
extensionSchemaProperty2.SetName(&name)
type := "String"
extensionSchemaProperty2.SetType(&type)
properties := []graphmodels.ExtensionSchemaPropertyable {
extensionSchemaProperty,
extensionSchemaProperty1,
extensionSchemaProperty2,
}
requestBody.SetProperties(properties)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
schemaExtensions, err := graphClient.SchemaExtensions().Post(context.Background(), requestBody, nil)
// 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("graphLearnCourses");
schemaExtension.setDescription("Graph Learn training courses extensions");
LinkedList<String> targetTypes = new LinkedList<String>();
targetTypes.add("user");
schemaExtension.setTargetTypes(targetTypes);
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);
После определения расширения схемы теперь можно добавить свойство расширения в экземпляр целевого типа объекта. Вы можете хранить данные в расширении схемы при создании нового экземпляра целевого объекта или при обновлении существующего объекта. В следующем примере показано, как сохранить данные в свойстве расширения схемы при создании нового объекта пользователя.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new User
{
AccountEnabled = true,
DisplayName = "Adele Vance",
MailNickname = "AdeleV",
UserPrincipalName = "AdeleV@contoso.com",
PasswordProfile = new PasswordProfile
{
ForceChangePasswordNextSignIn = false,
Password = "xWwvJ]6NMw+bWH-d",
},
AdditionalData = new Dictionary<string, object>
{
{
"extkmpdyld2_graphLearnCourses" , new
{
CourseId = 100,
CourseName = "Explore Microsoft Graph",
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.Users.PostAsync(requestBody);
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
user.setAccountEnabled(true);
user.setDisplayName("Adele Vance");
user.setMailNickname("AdeleV");
user.setUserPrincipalName("AdeleV@contoso.com");
PasswordProfile passwordProfile = new PasswordProfile();
passwordProfile.setForceChangePasswordNextSignIn(false);
passwordProfile.setPassword("xWwvJ]6NMw+bWH-d");
user.setPasswordProfile(passwordProfile);
HashMap<String, Object> additionalData = new HashMap<String, Object>();
extkmpdyld2GraphLearnCourses = new ();
extkmpdyld2GraphLearnCourses.setCourseId(100);
extkmpdyld2GraphLearnCourses.setCourseName("Explore Microsoft Graph");
extkmpdyld2GraphLearnCourses.setCourseType("Online");
additionalData.put("extkmpdyld2_graphLearnCourses", extkmpdyld2GraphLearnCourses);
user.setAdditionalData(additionalData);
User result = graphClient.users().post(user);
Запрос возвращает код отклика 201 Created и объект schemaExtension в тексте отклика.
Обновление или удаление свойства расширения схемы
Используйте операцию PATCH для обновления расширения схемы или удаления существующего расширения схемы. Чтобы удалить свойство расширения и связанное с ним значение из экземпляра ресурса, установите для него значение null.
В следующем примере удаляется значение свойства courseId и обновляется свойство courseType. Чтобы полностью удалить свойство расширения extkmpdyld2_graphLearnCourses, установите для него значение null.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new User
{
AdditionalData = new Dictionary<string, object>
{
{
"extkmpdyld2_graphLearnCourses" , new
{
CourseType = "Instructor-led",
CourseId = null,
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewUser()
additionalData := map[string]interface{}{
extkmpdyld2_graphLearnCourses := graph.New()
courseType := "Instructor-led"
extkmpdyld2_graphLearnCourses.SetCourseType(&courseType)
courseId := null
extkmpdyld2_graphLearnCourses.SetCourseId(&courseId)
requestBody.SetExtkmpdyld2_graphLearnCourses(extkmpdyld2_graphLearnCourses)
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User user = new User();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
extkmpdyld2GraphLearnCourses = new ();
extkmpdyld2GraphLearnCourses.setCourseType("Instructor-led");
extkmpdyld2GraphLearnCourses.setCourseId(null);
additionalData.put("extkmpdyld2_graphLearnCourses", extkmpdyld2GraphLearnCourses);
user.setAdditionalData(additionalData);
User result = graphClient.users().byUserId("{user-id}").patch(user);
GET https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e?$select=id,displayName,extkmpdyld2_graphLearnCourses
// 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.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","extkmpdyld2_graphLearnCourses" };
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","extkmpdyld2_graphLearnCourses"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "extkmpdyld2_graphLearnCourses"};
});
Расширение схемы должно иметь приложение-владелец. Владение расширением схемы не может быть переназначано другому приложению.
Удаление определения расширения схемы без настройки расширения null схемы делает свойство и связанные с ним пользовательские данные неоткрытыми.
Удаление приложения-владельца в домашнем клиенте не приводит к удалению связанного определения расширения схемы или свойства и хранимой в нем данных. Свойство расширения схемы по-прежнему может быть прочитано, удалено или обновлено для пользователей. Однако определение расширения схемы не может быть обновлено.
Открытые расширения
Открытые расширения Microsoft Graph — это открытые типы, которые предлагают простой и гибкий способ добавления нетипизированных данных непосредственно в экземпляр ресурса. Эти расширения не являются строго типизированными, обнаруживаемыми или фильтруемыми.
Список типов ресурсов, поддерживающих открытые расширения Microsoft Graph, см. в разделе Сравнение типов расширений.
Среда разработки
Открытые расширения вместе с их данными доступны через свойство навигации по расширениям экземпляра ресурса. Они позволяют группировать связанные свойства для облегчения доступа и управления.
Вы определяете открытые расширения и управляете ими на лету в экземплярах ресурсов. Они считаются уникальными для каждого объекта, и вам не нужно применять универсально согласованный шаблон для всех объектов. Например, в том же клиенте:
Объект пользователя для Adele может иметь открытое расширение с именем socialSettings с тремя свойствами: linkedInProfile, skypeId и xboxGamertag.
Объект user для Bruno не может иметь открытого свойства расширения.
Объект пользователя для Alex может иметь открытое расширение с именем socialSettings с пятью свойствами: тема, цвет, язык, шрифт и fontSize.
Создание открытого расширения
В следующем примере показано открытое определение расширения с тремя свойствами и способ представления пользовательских свойств и связанных данных в экземпляре ресурса.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new OpenTypeExtension
{
OdataType = "#microsoft.graph.openTypeExtension",
ExtensionName = "com.contoso.socialSettings",
Id = "com.contoso.socialSettings",
AdditionalData = new Dictionary<string, object>
{
{
"skypeId" , "skypeId.AdeleV"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
{
"xboxGamerTag" , "AwesomeAdele"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
extensionName := "com.contoso.socialSettings"
requestBody.SetExtensionName(&extensionName)
id := "com.contoso.socialSettings"
requestBody.SetId(&id)
additionalData := map[string]interface{}{
"skypeId" : "skypeId.AdeleV",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
"xboxGamerTag" : "AwesomeAdele",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
OpenTypeExtension extension = new OpenTypeExtension();
extension.setOdataType("#microsoft.graph.openTypeExtension");
extension.setExtensionName("com.contoso.socialSettings");
extension.setId("com.contoso.socialSettings");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("skypeId", "skypeId.AdeleV");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
additionalData.put("xboxGamerTag", "AwesomeAdele");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().post(extension);
Запрос возвращает код ответа 201 Created и объект openTypeExtension в тексте отклика.
Обновление существующего открытого расширения
Чтобы обновить открытое расширение, необходимо указать все его свойства в тексте запроса. В противном случае неуказаные свойства обновляются и null удаляются из открытого расширения.
В следующем запросе указываются только свойства linkedInProfile и xboxGamerTag. Значение свойства xboxGamerTag обновляется, а свойство linkedInProfile остается прежним. Этот запрос также удаляет неуказанное свойство skypeId.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new Extension
{
AdditionalData = new Dictionary<string, object>
{
{
"xboxGamerTag" , "FierceAdele"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions["{extension-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
additionalData := map[string]interface{}{
"xboxGamerTag" : "FierceAdele",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().ByExtensionId("extension-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Extension extension = new Extension();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("xboxGamerTag", "FierceAdele");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().byExtensionId("{extension-id}").patch(extension);
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new OpenTypeExtension
{
OdataType = "#microsoft.graph.openTypeExtension",
Id = "com.contoso.socialSettings",
AdditionalData = new Dictionary<string, object>
{
{
"@odata.context" , "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity"
},
{
"xboxGamerTag" , "FierceAdele"
},
{
"linkedInProfile" , "www.linkedin.com/in/testlinkedinprofile"
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Extensions["{extension-id}"].GetAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v1.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewExtension()
id := "com.contoso.socialSettings"
requestBody.SetId(&id)
additionalData := map[string]interface{}{
"@odata.context" : "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity",
"xboxGamerTag" : "FierceAdele",
"linkedInProfile" : "www.linkedin.com/in/testlinkedinprofile",
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
extensions, err := graphClient.Users().ByUserId("user-id").Extensions().ByExtensionId("extension-id").Get(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
OpenTypeExtension extension = new OpenTypeExtension();
extension.setOdataType("#microsoft.graph.openTypeExtension");
extension.setId("com.contoso.socialSettings");
HashMap<String, Object> additionalData = new HashMap<String, Object>();
additionalData.put("@odata.context", "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity");
additionalData.put("xboxGamerTag", "FierceAdele");
additionalData.put("linkedInProfile", "www.linkedin.com/in/testlinkedinprofile");
extension.setAdditionalData(additionalData);
Extension result = graphClient.users().byUserId("{user-id}").extensions().byExtensionId("{extension-id}").get(extension);
1 Из-за существующего ограничения службы делегаты не могут создавать открытые события с добавлением расширения в календарях общих почтовых ящиков. Попытка сделать это приведет к ответу ErrorAccessDenied.
2 Эти ограничения на открытые расширения применяются к следующим ресурсам каталога: пользователю, группе, устройству и организации.
3 Каждое открытое расширение хранится в именованном свойстве MAPI, которое является ограниченным ресурсом в почтовом ящике пользователя. Это ограничение распространяется на следующие ресурсы Outlook: сообщения, события и контакты
Вы можете управлять всеми расширениями, войдя в рабочую или учебную учетную запись. Кроме того, при входе с личной учетной записью Майкрософт вы можете управлять открытыми расширениями для следующих ресурсов: событие, публикация, группа, сообщение, контакт и пользователь.
Разрешения и привилегии
Те же привилегии, которые требуются приложению для чтения или записи в экземпляр ресурса, также требуются для управления любыми данными расширений в этом экземпляре ресурса. Например, в делегированном сценарии приложение может обновлять данные расширения любого пользователя только в том случае, если ему предоставлено разрешение User.ReadWrite.All, а у вошедшего пользователя есть поддерживаемая роль администратора Microsoft Entra.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.