schemaExtension 资源类型（架构扩展）

  • 项目

命名空间：microsoft.graph

可以通过架构扩展定义架构来扩展强类型的自定义数据并将其添加到资源类型。 自定义数据在扩展资源上作为复杂类型显示。 以下资源类型支持架构扩展：

使用此资源和关联的方法来管理 架构扩展定义。 要管理扩展资源实例上的架构扩展数据，请使用你用于管理资源实例的同一 REST 请求。 请参阅架构扩展示例了解如何将自定义数据添加到组。

有关Microsoft Graph扩展性的详细信息，包括架构扩展的限制， 请参阅使用扩展向资源添加自定义属性。

方法

方法 返回类型 说明
创建 schemaExtension 创建架构扩展定义及其关联的架构扩展属性。
List schemaExtension 列出可用的 schemaExtension 定义及其属性。
Get schemaExtension 读取特定的 schemaExtension 定义的属性。
Update schemaExtension 更新 schemaExtension 定义。 使用此操作可更新说明、状态、目标类型，或向架构扩展定义添加更多属性。
删除 无 删除 schemaExtension 定义。

属性

属性 类型 说明
说明 String 架构扩展的说明。 支持 $filter（eq）。
id String 架构扩展定义的唯一标识符。
你可以使用下面两种方法之一分配值：
  • 将其中一个已验证域的名称与架构扩展的名称连接在一起，以形成此格式 {domainName}_{schemaName} 的唯一字符串。 示例：contoso_mySchema。
  • 提供架构名称，让 Microsoft Graph 使用该架构名称完成以下格式的 ID 分配：ext{8-random-alphanumeric-chars}_{schema-name}。 例如 extkvbmkofy_mySchema。
此属性一旦创建，便无法更改。 支持 $filter（eq）。 注意：建议 ID 以 A-Z 之间的字母开头，因为查询功能可能限制为以整数开头的 ID。

支持 $filter（eq）。
所有者 String 属于架构扩展的所有者的应用程序的 appId。 必须在创建和更新操作期间显式指定架构定义的所有者，否则由Microsoft Entra ID进行隐式和自动分配，如下所示：
  • 在委派访问中：
    • 登录用户必须是调用 Microsoft Graph 来创建架构扩展定义的应用的所有者。
    • 如果已登录用户不是调用应用的所有者，则必须显式指定 所有者 属性，并为其分配他们拥有的应用的 appId 。
  • 在仅应用访问中：
    • 请求正文中不需要 owner 属性。 相反，为调用应用分配架构扩展的所有权。

因此，例如，如果使用 Graph 资源管理器创建新的架构扩展定义， 则必须 提供 owner 属性。 设置后，此属性为只读，且无法更改。 支持 $filter（eq）。
properties extensionSchemaProperty 集合 构成架构扩展定义的属性名称和类型的集合。
status String 架构扩展的生命周期状态。 可能的状态为 InDevelopment、Available 和 Deprecated。 创建后将自动设置为 InDevelopment。 有关可能的状态转换和行为的详细信息，请参阅 架构扩展生命周期。 支持 $filter（eq）。
targetTypes String collection 架构扩展适用的支持扩展的 Microsoft Graph 类型集。 从 administrativeUnit、 联系人、 设备、 事件、 组、 消息、 组织、 帖子、 todoTask、 todoTaskList或 用户中进行选择。

架构扩展生命周期

当应用创建架构扩展定义时，系统会将该应用标记为该架构扩展的所有者。

所有者应用可以在状态属性上使用 PATCH 操作将扩展转换为生命周期中的不同状态。 基于当前状态，所有者应用可以更新或删除扩展。 架构扩展的任何更新始终只能累加且不能间断。

状态 生命周期状态行为
InDevelopment
  • 创建后的初始状态。 所有者应用仍然在开发架构扩展。
  • 在此状态下，注册所有者应用的同一目录中的任何应用都可以使用此架构定义（如果应用对该资源具有权限）扩展资源实例。
  • 对于多租户所有者应用，只有位于主目录不同目录中的所有者应用的实例才能使用此架构定义扩展资源实例， (应用有权访问该资源) 或读取扩展数据。
  • 只有所有者应用，才能使用增量更改更新扩展定义。
  • 只有所有者应用可以删除扩展定义。
  • 所有者应用可以将扩展从 InDevelopment 移动到 Available 状态。
可用
  • 架构扩展可供任意租户中的所有应用使用。
  • 所有者应用将扩展设置为 Available后，如果应用有权访问该资源) ，则任何应用都可以将自定义数据添加到扩展中指定的这些资源类型的实例 (。 新建实例或更新现有实例时，应用可以分配自定义数据。
  • 只有所有者应用，才能使用增量更改更新扩展定义。 任何应用都无法删除这种状态下的扩展定义。
  • 所有者应用可以将架构扩展从 Available 移动到 Deprecated 状态。
不推荐使用
  • 架构扩展定义不再可供读取或修改。
  • 任何应用都无法查看、更新、添加新属性或删除扩展。
  • 但是，应用仍可以读取、更新或删除现有扩展 属性值。

注意

架构扩展定义 (标记为 Available 由其他租户中的其他开发人员创建的) ，通过列出所有架构扩展) ， (所有开发人员可见。 这不同于仅返回租户特定数据的其他 API。 另一方面，基于架构扩展定义创建的扩展数据是特定于租户的，并且只能由被显式授予权限的应用访问。

JSON 表示形式

以下 JSON 表示形式显示了资源类型。

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

相关内容