适用于： 开发人员版
当应用需要对 SharePoint Embedded 容器中的文件进行结构化字段时，请使用元数据。 元数据存储为容器驱动器项上的 fileStorageContainer 列和字段值。 应用程序负责为每个容器实例创建和管理列架构。 有关容器资源属性的完整列表，请参阅 fileStorageContainer 资源类型。
权限和支持的调用方
使用仅限应用或委托的持有者令牌调用元数据 API。 用于 FileStorageContainer.Selected 应用程序和委派调用。
容器所有者和管理员可以创建、更新和删除列。 容器成员可以读取和列出列。
选择列类型
SharePoint Embedded 元数据支持以下列类型属性：boolean、、choice、numbertextcurrencydateTimehyperlinkOrPicturepersonOrGroup和。 它还支持列设置，例如 indexed、 isDeletable、 readOnlyisSealednametype、 和 。
列名必须遵循 SharePoint 规则。 不要使用包含以下名称 !：以数字或标点符号开头、包含空格、看起来像电子表格单元格引用、表示本地化的 true 或 false 值，或使用保留名称（例如 Author、 Created或 Description）。
创建列
在文件上写入字段值之前，在容器上创建一个列。
POST https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
Content-Type: application/json
{
"description": "test",
"displayName": "Title",
"enforceUniqueValues": false,
"hidden": false,
"indexed": false,
"name": "Title",
"text": {
"allowMultipleLines": false,
"appendChangesToExistingText": false,
"linesForEditing": 0,
"maxLength": 255
}
}
创建请求不支持 type，文本 maxLength 必须小于或等于 255。
注意
自 2026 年 1 月起，容器列 API (列出、创建、更新、删除列) 也在 v1.0 Microsoft Graph 终结点上正式发布。 可以在下面的列请求中替换 /beta/ 为 /v1.0/ 。 beta 终结点仍可用。
管理列
使用创建或列表操作返回的列 ID。
GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns
GET https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
PATCH https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
DELETE https://graph.microsoft.com/beta/storage/fileStorage/containers/{container-id}/columns/{column-id}
架构更改时修补支持的属性。 可以更新列的任何属性（属性除外 id ）。
{
"required": true,
"hidden": false,
"description": "This is my new column description"
}
读取和写入文件元数据
字段值存储在驱动器项的列表项字段中。 阅读所有字段或选择 UI 所需的字段。
GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
GET https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields?$select=Name,Color
修补字段值以更新元数据。
null用于在列允许空值时清除字段值。
PATCH https://graph.microsoft.com/beta/drives/{drive-id}/items/{item-id}/listitem/fields
Content-Type: application/json
{
"Color": "Fuchsia",
"Quantity": 934
}
{
"Color": null
}
按元数据查询文件
当你需要在容器驱动器内进行结构化筛选或排序时，在自定义列上使用 OData 查询选项。
GET https://graph.microsoft.com/beta/drives/{drive-id}/items?$orderby=listitem/fields/TestField asc&$filter=startswith(listitem/fields/TestField, '3')&$expand=listitem($expand=fields)
当结果需要响应中的字段值时使用 $expand=listitem($expand=fields) 。 为应用经常运行的高基数筛选器创建索引列。
有关跨容器和自定义元数据的全文搜索，请参阅 搜索容器和文件。 若要按索引自定义元数据筛选语义检索，请参阅 按自定义元数据筛选检索。 这两种体验都使用 SharePoint 托管属性，例如为文本列生成的 OWSTEXT 属性。
在一个容器驱动器内使用 OData $filter 进行结构化查询。 使用搜索跨多个容器进行自由文本查询，或使用检索 API 返回 AI 基础数据的提取。
保持架构一致
在容器预配期间创建必需列。 将预期的架构版本存储在应用数据中，并在引入新列时运行迁移。 在发现工作流、查询、导出或搜索体验都不依赖于列的值之前，请避免删除列。