如何通过Graph API获取SharePoint文档合规详情的Expiration Status

问题概述 #

需要从SharePoint文档的Compliance Details中提取Expiration Status，用于API调用或Purview的KQL查询，以识别带保留标签的文档，或排除已触发到期事件的文档。手动获取路径为：右键文档 → 「More」→「Compliance Details」，在弹窗中查看状态。

已尝试操作 #

• 调用多个API获取文档/保留标签/列详情
• 查看SharePoint爬网属性（Craweled properties）和托管属性（managed properties）
• 咨询ChatGPT、微软支持及微软问答平台

解决方案 #

1. 通过Microsoft Graph API编程获取 #

可以通过Graph API的保留标签端点直接获取文档的到期相关信息，进而推导Expiration Status：

针对文档库文件

调用以下端点获取指定文件的保留标签详情：

GET /sites/{site-id}/drive/items/{item-id}/retentionLabel

返回的retentionLabel资源包含关键字段：

• expirationDateTime：文档的到期时间
• labelAppliedDateTime：标签应用时间
• retentionSettings：保留策略的具体配置

通过这些字段可计算Expiration Status：

• 若expirationDateTime < 当前时间：状态为已过期
• 若expirationDateTime在未来30天内：状态为即将过期
• 其他情况：状态为有效

针对列表项

如果文档存储在列表中，使用以下端点：

GET /sites/{site-id}/lists/{list-id}/items/{item-id}/retentionLabel

2. 将Expiration Status同步为可查询的自定义列 #

如果需要将状态直接暴露为SharePoint列表的可查询列，可通过以下步骤实现：

1. 在目标文档库中创建一个文本类型的自定义列，命名为ExpirationStatus
2. 使用Power Automate创建自动化流：
   • 触发条件：当文档的保留标签被应用/更新时
   • 操作步骤：调用Graph API获取该文档的expirationDateTime，计算状态后更新ExpirationStatus列的值
3. 完成配置后，该列可直接在列表视图、SharePoint REST API或Power BI中查询使用

3. 在Purview中通过KQL查询推导状态 #

在Purview的搜索查询中，可利用内置的保留标签属性通过KQL计算Expiration Status：

DataSourceType = "SharePoint"
| where RetentionLabelName != ""
| extend ExpirationStatus = case(
    RetentionExpirationDate < now(), "已过期",
    RetentionExpirationDate between (now() .. now()+30d), "即将过期",
    "有效"
)
| project Name, RetentionLabelName, RetentionExpirationDate, ExpirationStatus

4. 通过SharePoint搜索API查询 #

如果已将保留标签的到期属性映射为托管属性（例如RetentionLabelExpirationDate），可通过搜索API直接筛选：

GET /sites/{site-id}/search?q=RetentionLabelExpirationDate:[* TO NOW()]

搜索结果会返回包含已过期状态的文档，也可通过返回的RetentionLabelExpirationDate字段自行计算状态。

内容的提问来源于stack exchange，提问作者Chris