← 返回首页目录
# 通过 Graph API 检索 Microsoft Graph 连接器内容
**作者：吉祥法师**
在 Microsoft 365 与自定义应用程序集成的复杂生态系统中，Microsoft Graph 连接器（Graph Connectors）作为连接非微软数据源与微软原生体验的桥梁，其重要性日益凸显。然而，在实际应用场景中，开发者常常面临一个核心挑战：如何通过 Search API 仅获取搜索结果片段，而无法直接获取已索引项目的完整内容。
本文将深入探讨如何利用 Microsoft Graph 的两大 API——Search API 与连接器摄取 API——协同工作，实现从搜索命中到完整内容检索的无缝衔接，并提供一个经过验证的技术落地方案。
## 场景解析：搜索片段与完整内容的鸿沟
近期，一位客户提出了一个极具代表性的技术疑问：
> “我们已通过 Graph 连接器将文件成功索引，但如何检索这些项目的完整内容以用于构建自定义搜索解决方案？我们注意到 Search API 似乎仅返回匹配结果的片段信息，而非完整全文。”
客户的观察是精准且深刻的。当应用程序调用 Microsoft Graph 的搜索 API 来检索 Graph 连接器数据时，API 允许开发者明确指定需要返回哪些字段——这些字段源自 Graph 连接器定义的结构化架构（Schema）。然而，设计上该接口**不提供**已摄取内容的全文数据。这一设计决策并非缺陷，而是基于以下考量：搜索接口的核心价值在于快速定位并展示相关结果片段，以支持高性能的自定义搜索体验界面。返回大型文本内容将显著增加网络传输负载并拖慢响应速度。
那么，当业务需求确实需要访问完整内容——例如构建企业级知识管理系统、生成内容摘要或执行深度文本分析——应当如何应对？
## 方案设计：双 API 协同策略
解决上述问题需要策略性地组合使用两个不同层级的 API，形成一个“两步走”的检索管线。
### 步骤一：借助 Search API 定位项目标识符
首先，开发者需调用 `/search/query` 端点，该端点支持 `externalItem` 实体类型，并可通过 `contentSources` 参数精确限定搜索范围至特定连接器实例。
**HTTP 请求示例：**
```
POST: https://graph.microsoft.com/v1.0/search/query
```
**请求体结构：**
```json
{
"requests": [
{
"entityTypes": ["externalItem"],
"contentSources": ["/external/connections/ServiceNowKB1"],
"query": {
"queryString": "*"
},
"from": 0,
"size": 3
}
]
}
```
在此示例中，`ServiceNowKB1` 为连接器的连接标识符，开发者需根据实际场景替换。`queryString` 被设为 `"*"`，意即返回连接器中的全部项目，在此仅为演示检索逻辑。
**关键响应解析：**
当返回结果时，开发者需特别留意名为 **`substrateContentDomainId`** 的字段。该字段值承载着定位完整内容的关键信息——其中包含了两个以逗号分隔的标识符，**需取逗号后的第二部分**，即 Graph 连接器项目的唯一标识符（`itemId`）。
假设响应结果中该字段的值为：
```
ExternalItemId,c487857187032100deddb882a2e3ec4f
```
那么实际的 `itemId` 即为 `c487857187032100deddb882a2e3ec4f`。
### 步骤二：通过摄取 API 获取完整数据流
获取到目标 `itemId` 后，即可调用 Graph 连接器摄取 API（又称“ingestion API”或“连接项 API”）来换取包含全文的完整内容实体。
**HTTP 请求示例：**
```
GET: https://graph.microsoft.com/v1.0/external/connections/ServiceNowKB1/items/c487857187032100deddb882a2e3ec4f
```
**响应结果预期：**
此端点的响应将返回该条项目在连接器中的完整数据记录，涵盖所有通过连接器架构（Schema）定义并摄取的全部属性，包括核心的 `content` 属性——该字段即存储着完整的文本内容及其内容格式类型。
在整个检索管线中，此步骤相当于“数据拉取层”，开发者无需再被动接收截断的搜索摘要。
### 检索流程示意
```
目标搜索 → 调用 /search/query → 解析 substrateContentDomainId
→ 提取 itemId（逗号后部分）
→ 调用 /external/connections/{connectionId}/items/{itemId}
→ 获取完整内容
```
## 操作要点与最佳实践
在实际编码与系统设计过程中，以下几项要点值得开发者重点关注：
### 1. 全文检索仅限单项目
当前的摄取 API 设计为**单项目检索（Get Item）**，不支持通过单个请求批量获取多个项目的完整内容。如果搜索结果包含多个命中项，开发者必须遍历每个项目的 `itemId`，分别发起 HTTP 请求以获取各自的完整数据。
### 2. 批量处理的性能考量
在处理大规模数据集时，应谨慎设计循环请求逻辑。建议采用适度并发机制避免请求过快导致 Graph API 限流（Throttling），或造成目标源系统负载压力过大。同时应设计良好的重试策略与超时机制。
### 3. 仅检索必要字段
在 Search API 请求体中，可通过 `fields` 属性限制返回的属性集合，尽量仅获取 UI 展示所需的最小字段集，以此压缩网络开销，加快首屏渲染速度。
### 4. 数据权限与合规检查
由于 Graph 连接器可用于承载企业敏感数据，在构建自定义检索体验时，务必遵循 Microsoft 365 的权限模型边界，确保检索用户具备访问其所属组织数据的合法授权，同时遵循合规性政策。
### 5. 连接器连接标识的获取
如不确定 `externalConnection` 对应的 `id`，开发者可通过 `GET https://graph.microsoft.com/v1.0/external/connections` 查询当前租户中所有已建立的连接器及其元信息。
## 应用价值与延伸思考
Graph 连接器本身已赋能多个 Microsoft 365 原生体验的跨域数据发现能力，如 Microsoft Search、Copilot for Microsoft 365 等。而如文中所述，借助双 API 协同，开发者完全可以突破原生体验边界，在自定义的部门门户或业务应用中复用连接器内已索引的第三方内容。
这种方法的引入，对此类应用场景具有切实的价值：
- **企业搜索门户**：实现统一、高性能的内部信息发现窗口；
- **AI 辅助决策**：为 Copilot 插件或企业级 AI Agent 提供高质量的完整文本上下文；
- **内容迁移与同步**：在系统间迁移或合规审核时，精准获取源数据内容；
- **创新应用开发**：满足更多定制化业务逻辑对于全文数据的需求。
## 结语
Graph 连接器是实现跨数据源统一发现的核心技术组件。本文从客户痛点切入，阐明了如何将 Microsoft Graph Search API 与连接器摄取 API 灵活串联，从而在自定义应用中获取得完整内容。文中每一步均伴随具体的 REST 请求示例及关键响应字段解析，旨在帮助技术人员快速实现符合预期的原型，节省自行摸索的时间。面对多样化的业务场景时，理解并灵活运用 API 组合策略，将促成更优雅的解决方案落地。
---
*注：文中代码片段及 API 调用路径基于 Microsoft Graph v1.0 版本，实际使用时请以微软官方文档为准，并关注版本迭代更新。*