Тип ресурса schemaExtension (расширения схемы)

  • Статья

Пространство имен: microsoft.graph

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

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

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

Методы

Метод Возвращаемый тип Описание
Создание schemaExtension Создайте определение расширения схемы и связанное с ним свойство расширения схемы.
Перечисление schemaExtension Создание списка доступных определений schemaExtension и их свойств.
Получение schemaExtension Получение свойств указанного определения schemaExtension.
Обновление schemaExtension Обновление определения schemaExtension. Эта операция используется для обновления описания, состояния, целевых типов или добавления дополнительных свойств в определение расширения схемы.
удаление; Нет Удаление определения schemaExtension.

Свойства

Свойство Тип Описание
description String Описание расширения схемы. Поддерживает $filter (eq).
id String Уникальный идентификатор для определения расширения схемы.
Значение можно присвоить одним из двух способов:
  • Сцепить имя одного из проверенных доменов с именем расширения схемы, чтобы сформировать уникальную строку в этом формате, {domainName}_{schemaName}. Пример: contoso_mySchema.
  • Укажите имя схемы и позвольте Microsoft Graph использовать это имя схемы для завершения назначения идентификатора в следующем формате: ext{8-random-alphanumeric-chars}_{schema-name}. Примером может быть extkvbmkofy_mySchema.
После создания это свойство невозможно изменить. Поддерживает $filter (eq). Примечание: Рекомендуется, чтобы ваш ИД начинался с буквы алфавита от А до Я, так как возможности запроса могут быть ограничены для идентификаторов, начинающихся с целых чисел.

Поддерживает $filter (eq).
owner String Идентификатор appId приложения, которое является владельцем расширения схемы. Владелец определения схемы должен быть явно указан во время операций создания и обновления, иначе он будет подразумеваться и автоматически назначаться Microsoft Entra ID следующим образом:
  • В делегированном доступе:
    • Для создания определения расширения схемы пользователь, вошедшего в систему, должен быть владельцем приложения, которое вызывает Microsoft Graph.
    • Если пользователь, выполнившего вход, не является владельцем вызывающего приложения, он должен явно указать свойство owner и назначить ему appId приложения, которым он владеет.
  • В доступе только для приложений:
    • Свойство owner не требуется в тексте запроса. Вместо этого вызывающему приложению назначается владелец расширения схемы.

Например, при создании нового определения расширения схемы с помощью Обозреватель Graph необходимо указать свойство owner. После задания свойства оно будет доступно только для чтения, и вам не удастся изменить его. Поддерживает $filter (eq).
properties Коллекция extensionSchemaProperty Коллекция имен и типов свойств, составляющих определение расширения схемы.
status String Состояние жизненного цикла расширения схемы. Возможные состояния: InDevelopment, Available и Deprecated. При создании свойство автоматически получает значение InDevelopment. Дополнительные сведения о возможных переходах состояния и о поведении истории состояний см. в статье Жизненный цикл расширений схемы. Поддерживает $filter (eq).
targetTypes Коллекция String Набор типов Microsoft Graph (поддерживающих расширения), к которым можно применить это расширение схемы. Выберите из administrativeUnit, contact, device, event, group, message, organization, post, todoTask, todoTaskList или user.

Жизненный цикл расширений схемы

Когда приложение создает определение расширения схемы, оно помечается как владелец такого расширения.

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

Состояние Поведение в состоянии жизненного цикла
InDevelopment
  • Начальное состояние после создания. Приложение-владелец по-прежнему разрабатывает расширение схемы.
  • В этом состоянии любое приложение в том каталоге, в котором зарегистрировано приложение-владелец, может расширять экземпляры ресурса с использованием этого определения схемы (при наличии у приложения разрешений для данного ресурса).
  • Для мультитенантного приложения владельца только экземпляр приложения-владельца, который находится в каталоге, отличном от домашнего каталога, может расширить экземпляры ресурсов с помощью этого определения схемы (если приложение имеет разрешения для этого ресурса) или считывать данные расширения.
  • Только приложение-владелец может добавлять изменения в определение расширения.
  • Только приложение-владелец может удалять определение расширения.
  • Приложение-владелец может переместить расширение из InDevelopment в Available состояние .
Available
  • Расширение схемы доступно для всех приложений в любом клиенте.
  • После того как приложение-владелец установит для расширения значение Available, любое приложение может добавлять пользовательские данные в экземпляры этих типов ресурсов, указанных в расширении (если приложение имеет разрешения для этого ресурса). Приложение может назначать пользовательские данные при создании нового экземпляра или обновлении существующего.
  • Только приложение-владелец может добавлять изменения в определение расширения. Если указано это состояние, удалить определение расширения не может никакое приложение.
  • Приложение-владелец может переместить расширение схемы из Available в Deprecated состояние .
Deprecated
  • Определение расширения схемы больше не доступно для чтения или изменения.
  • Приложения не могут просмотреть, обновить, добавить свойства или удалить расширение.
  • Однако приложения могут по-прежнему считывать, обновлять или удалять существующие значения свойств расширения.

Примечание.

Определения расширений схемы (помеченные как Available), созданные другими разработчиками из других клиентов, видны всем разработчикам (путем перечисления всех расширений схемы). Это отличается от других API-интерфейсов, возвращающих только данные определенного клиента. С другой стороны, данные расширения, созданные на основе определений расширений схемы, относятся к конкретному клиенту и доступны только приложениям, которым явным образом предоставлено разрешение.

Представление JSON

В следующем представлении JSON показан тип ресурса.

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

Связанные материалы