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

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.

PATCH https://graph.microsoft.com/v1.0/users/071cc716-8147-4397-a5ba-b2105951cc0b

{
    "onPremisesExtensionAttributes": {
        "extensionAttribute1": "skypeId.adeleVance",
        "extensionAttribute13": null
    }
}

Запрос возвращает объект отклика 204 No Content.

Чтение атрибутов расширения

Запрос
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,onPremisesExtensionAttributes
Отклик
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,onPremisesExtensionAttributes)",
    "value": [
        {
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "displayName": "Adele Vance",
            "onPremisesExtensionAttributes": {
                "extensionAttribute1": "Contractor",
                "extensionAttribute2": "50",
                "extensionAttribute3": null,
                "extensionAttribute4": "1478354",
                "extensionAttribute5": "10239390",
                "extensionAttribute6": null,
                "extensionAttribute7": null,
                "extensionAttribute8": null,
                "extensionAttribute9": null,
                "extensionAttribute10": "11",
                "extensionAttribute11": null,
                "extensionAttribute12": "/o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF47SPDLT)/cn=Recipients/cn=5ee781fc7egc7aa0b9394bddb44e7f04-Adele Vance",
                "extensionAttribute13": null,
                "extensionAttribute14": null,
                "extensionAttribute15": null
            }
        }
    ]
}

Рекомендации по использованию свойств атрибута расширения

Объект onPremisesExtensionAttributes можно обновить только для объектов, которые не синхронизированы из локальной службы AD.

15 атрибутов расширения уже предопределены в Microsoft Graph, и их имена свойств нельзя изменить. Поэтому для атрибутов расширения нельзя использовать пользовательские имена, такие как SkypeId . Поэтому ваша организация должна отслеживать используемые свойства атрибута расширения, чтобы избежать случайной перезаписи данных.

Расширения каталога (Microsoft Entra ID)

Расширения каталогов предоставляют разработчикам строго типизированные, обнаруживаемые и фильтруемые расширения для объектов каталога.

Расширения каталогов сначала регистрируются в приложении с помощью операции Create extensionProperty и должны быть явно ориентированы на конкретные и поддерживаемые объекты каталога. После того как пользователь или администратор предоставил согласие на использование приложения в клиенте, свойства расширения сразу же становятся доступными в клиенте. Все авторизованные приложения в клиенте могут считывать и записывать данные о любых свойствах расширения, определенных для экземпляра целевого объекта каталога.

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

Среда разработки

Определения расширения каталога управляются с помощью ресурса extensionProperty и связанных с ним методов. Управление данными осуществляется с помощью запросов REST API, которые используются для управления экземпляром ресурса.

Определение расширения каталога

Перед добавлением расширения каталога в экземпляр ресурса необходимо сначала определить расширение каталога.

Запрос

В следующем запросе — это идентификатор объекта приложения, 30a5435a-1871-485c-8c7b-65f69e287e7b которому принадлежит расширение каталога. Можно создать расширения каталогов, которые хранят коллекцию значений.

POST https://graph.microsoft.com/v1.0/applications/30a5435a-1871-485c-8c7b-65f69e287e7b/extensionProperties

{
    "name": "jobGroupTracker",
    "dataType": "String",
    "targetObjects": [
        "User"
    ]
}
Отклик

Именованное свойство расширения каталога extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker создается с именем расширения, соответствующим следующему соглашению об именовании: extension_{appId-without-hyphens}_{extensionProperty-name}.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications('30a5435a-1871-485c-8c7b-65f69e287e7b')/extensionProperties/$entity",
    "id": "4e3dbc8f-ca32-41b4-825a-346215d7d20f",
    "deletedDateTime": null,
    "appDisplayName": "HR-sync-app",
    "dataType": "String",
    "isMultiValued": false,
    "isSyncedFromOnPremises": false,
    "name": "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker",
    "targetObjects": [
        "User"
    ]
}

Добавление свойства расширения каталога к целевому объекту

После определения расширения каталога его можно добавить в экземпляр целевого типа объекта. Данные можно хранить в расширении каталога при создании нового экземпляра целевого объекта или при обновлении существующего объекта. В следующем примере показано, как хранить данные в расширении каталога при создании нового объекта пользователя .

POST https://graph.microsoft.com/v1.0/users

{
    "accountEnabled": true,
    "displayName": "Adele Vance",
    "mailNickname": "AdeleV",
    "userPrincipalName": "AdeleV@contoso.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": false,
        "password": "xWwvJ]6NMw+bWH-d"
    },
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "JobGroupN"
}

Запрос возвращает код отклика 201 Created и объект пользователь в тексте отклика.

Получение расширения каталога

В следующем примере показано, как расширения каталога и связанные данные представлены в экземпляре ресурса. Свойство расширения возвращается по умолчанию через конечную точку beta , но только через $select конечную точку v1.0 .

Запрос

GET https://graph.microsoft.com/beta/users?$select=id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable

Отклик

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker,extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable)",
    "value": [
        {
            "id": "63384f56-42d2-4aa7-b1d6-b10c78f143a2",
            "displayName": "Adele Vance",
            "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "E4",
            "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable": true
        }
    ]
}

Обновление или удаление расширений каталогов

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

Следующий запрос обновляет значение одного расширения каталога и удаляет другое свойство расширения.

PATCH https://graph.microsoft.com/v1.0/users/63384f56-42d2-4aa7-b1d6-b10c78f143a2

{
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_permanent_pensionable": null,
    "extension_b7d8e648520f41d3b9c0fdeb91768a0a_jobGroupTracker": "E4"
}

Запрос возвращает код отклика 204 No Content.

Рекомендации по использованию расширений каталогов

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

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

Определение расширения схемы

Запрос
POST https://graph.microsoft.com/v1.0/schemaExtensions

{
    "id": "graphLearnCourses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "user"
    ],
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}
Отклик
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#schemaExtensions/$entity",
    "id": "extkmpdyld2_graphLearnCourses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "user"
    ],
    "status": "InDevelopment",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

Добавление расширения схемы к экземпляру ресурса

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

POST https://graph.microsoft.com/beta/users

{
    "accountEnabled": true,
    "displayName": "Adele Vance",
    "mailNickname": "AdeleV",
    "userPrincipalName": "AdeleV@contoso.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": false,
        "password": "xWwvJ]6NMw+bWH-d"
    },
    "extkmpdyld2_graphLearnCourses": {
        "courseId": 100,
        "courseName": "Explore Microsoft Graph",
        "courseType": "Online"
    }
}

Запрос возвращает код отклика 201 Created и объект schemaExtension в тексте отклика.

Обновление или удаление свойства расширения схемы

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

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

PATCH https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e

{
    "extkmpdyld2_graphLearnCourses": {
        "courseType": "Instructor-led",
        "courseId": null
    }
}

Запрос возвращает объект отклика 204 No Content.

Получение свойства расширения схемы

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

Запрос
GET https://graph.microsoft.com/beta/users/0668e673-908b-44ea-861d-0661297e1a3e?$select=id,displayName,extkmpdyld2_graphLearnCourses
Отклик
HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,extkmpdyld2_graphLearnCourses)/$entity",
    "id": "63384f56-42d2-4aa7-b1d6-b10c78f143a2",
    "displayName": "Adele Vance",
    "extkmpdyld2_graphLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Instructor-led",
        "courseName": "Explore Microsoft Graph",
        "courseId": null
    }
}

Рекомендации по использованию расширений схемы

Расширение схемы должно иметь приложение-владелец. Владение расширением схемы не может быть переназначано другому приложению.

Удаление определения расширения схемы без настройки расширения null схемы делает свойство и связанные с ним пользовательские данные неоткрытыми.

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

Открытые расширения

Открытые расширения Microsoft Graph — это открытые типы, которые предлагают простой и гибкий способ добавления нетипизированных данных непосредственно в экземпляр ресурса. Эти расширения не являются строго типизированными, обнаруживаемыми или фильтруемыми.

Список типов ресурсов, поддерживающих открытые расширения Microsoft Graph, см. в разделе Сравнение типов расширений.

Среда разработки

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

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

  • Объект пользователя для Adele может иметь открытое расширение с именем socialSettings с тремя свойствами: linkedInProfile, skypeId и xboxGamertag.
  • Объект user для Bruno не может иметь открытого свойства расширения.
  • Объект пользователя для Alex может иметь открытое расширение с именем socialSettings с пятью свойствами: тема, цвет, язык, шрифт и fontSize.

Создание открытого расширения

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

POST https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions

{
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "extensionName": "com.contoso.socialSettings",
    "skypeId": "skypeId.AdeleV",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile",
    "xboxGamerTag": "AwesomeAdele",
    "id": "com.contoso.socialSettings"
}

Запрос возвращает код ответа 201 Created и объект openTypeExtension в тексте отклика.

Обновление существующего открытого расширения

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

В следующем запросе указываются только свойства linkedInProfile и xboxGamerTag. Значение свойства xboxGamerTag обновляется, а свойство linkedInProfile остается прежним. Этот запрос также удаляет неуказанное свойство skypeId.

PATCH https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions/com.contoso.socialSettings

{
    "xboxGamerTag": "FierceAdele",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile"
}

Этот запрос возвращает код отклика 204 No Content.

Извлечение открытых расширений

GET https://graph.microsoft.com/v1.0/users/3fbd929d-8c56-4462-851e-0eb9a7b3a2a5/extensions/com.contoso.socialSettings

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('3fbd929d-8c56-4462-851e-0eb9a7b3a2a5')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "xboxGamerTag": "FierceAdele",
    "linkedInProfile": "www.linkedin.com/in/testlinkedinprofile",
    "id": "com.contoso.socialSettings"
}

Рекомендации по использованию открытых расширений

Удаление приложения-создателя не влияет на открытое расширение и данные, которые оно хранит.

Сравнение типов расширений

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

Возможность Атрибуты расширения 1–15 Расширения каталогов Расширения схемы Открытые расширения
Поддерживаемые типы ресурсов user
device
user
group
administrativeUnit
application
device
organization
user
group
administrativeUnit
contact
device
event (календари пользователей и групп)
message
organization
post
user
Группы
contact
device
event1 (как пользовательский, так и групповой календари)
message
organization
post
todoTask
todoTaskList
Строго типизированные Нет Да Да Нет
Filterable Да Да Да Нет
Может хранить коллекцию Нет Да Нет Нет
Привязка к приложению владельца Нет Да Да Нет
Управляется через Microsoft Graph
Центр администрирования Exchange
Microsoft Graph Microsoft Graph Microsoft Graph
Синхронизация данных из локальной среды с расширениями с помощью AD Connect Да, для пользователей Да Нет Нет
Создание правил динамического членства с использованием свойств и данных настраиваемых расширений. Да Да Нет Нет
Может использоваться для настройки требований токена Да Да (1, 2) Нет Нет
Доступно в Azure AD B2C Да Да Да Да
Ограничения
  • 15 предопределенных атрибутов для каждого пользователя или экземпляра ресурса устройства
  • 100 значений расширения на экземпляр ресурса
  • Максимум пять определений на одного владельца приложения
  • 100 значений расширения на экземпляр ресурса (только объекты каталога)
  • Два открытых расширения на приложение-создатель на экземпляр ресурса2
  • Максимальная 2 КБ на открытое расширение2
  • Для ресурсов Outlook каждое открытое расширение хранится в именованном свойстве MAPI3
  • Примечание.

    1 Из-за существующего ограничения службы делегаты не могут создавать открытые события с добавлением расширения в календарях общих почтовых ящиков. Попытка сделать это приведет к ответу ErrorAccessDenied.

    2 Эти ограничения на открытые расширения применяются к следующим ресурсам каталога: пользователю, группе, устройству и организации.

    3 Каждое открытое расширение хранится в именованном свойстве MAPI, которое является ограниченным ресурсом в почтовом ящике пользователя. Это ограничение распространяется на следующие ресурсы Outlook: сообщения, события и контакты

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

    Разрешения и привилегии

    Те же привилегии, которые требуются приложению для чтения или записи в экземпляр ресурса, также требуются для управления любыми данными расширений в этом экземпляре ресурса. Например, в делегированном сценарии приложение может обновлять данные расширения любого пользователя только в том случае, если ему предоставлено разрешение User.ReadWrite.All, а у вошедшего пользователя есть поддерживаемая роль администратора Microsoft Entra.