使用 Microsoft 搜索 API 折叠搜索结果

  • 项目

可以使用 Microsoft Graph 中的 Microsoft 搜索 API 折叠搜索结果集中的项目。 这允许你以简明易读的方式显示结果。 可以在 searchRequest 对象中使用 collapseProperties 属性来指定折叠条件，该属性包含一个或多个 collapseProperty 参数来设置要折叠的字段并限制结果的大小。 以下实体类型支持 collapseProperties 属性：

  • site
  • drive
  • driveItem
  • 列表
  • listItem
  • externalItem

下表列出了可以启用的折叠方案。

应用场景 说明 示例
基本折叠 按任何单个可查询和可排序或可精简属性折叠。 此限制值必须是介于 1 和 32767 之间的整数。 "collapseProperties":[{"fields":["filename"],"limit":3}]
复合折叠 按属性的复合字段折叠。 没有最大字段数，但必须至少指定两个字段。 此限制值必须是介于 1 和 32767 之间的整数。 "collapseProperties":[{"fields":["filename","author"],"limit":2}]
多级折叠 按级别折叠 折叠属性。 没有最大级别数，但必须至少指定两个级别。 每个级别的限制值必须是介于 1 和 32767 之间的整数，并且必须等于或小于上限限制值。 "collapseProperties":[{"fields":["filename"],"limit":3},{"fields":["author"],"limit":1}]

示例

下表显示了 SharePoint 中的示例列表。 本部分中的示例使用此列表来显示 collapseProperties 属性的工作原理。

Filename 作者 主题 Rank
注意 安 迪 诗歌 1
注意 詹姆斯 历史记录 2
注意 罗伯特 Culture 3
注意 詹姆斯 数学 4
注意 詹姆斯 科学 5
笔记本 詹姆斯 科学 6
笔记本 安 迪 Culture 7
笔记本 詹姆斯 科学 8

示例 1：基本折叠

请求

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "listItem"
            ],
            "query": {
                "queryString": "note"
            },
            "fields": [
                "filename"
            ],
            "collapseProperties": [
                {
                    "fields": [
                        "filename"
                    ],
                    "limit": 3
                }
            ]
        }
    ]
}

根据 文件名 对项进行分组，并显示前三 (“限制”：每个组的 3) 。 如下表所示，将维护排名。 前三行和最后三行保留，但排除第四行和第五行，因为 collapseProperties 限制为 3。

Filename 作者 主题 Rank
注意 安 迪 诗歌 1
注意 詹姆斯 历史记录 2
注意 罗伯特 Culture 3
笔记本 詹姆斯 科学 6
笔记本 安 迪 Culture 7
笔记本 詹姆斯 科学 8

示例 2：复合折叠

请求

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "listItem"
            ],
            "query": {
                "queryString": "note"
            },
            "fields": [
                "filename",
                "author"
            ],
            "collapseProperties": [
                {
                    "fields": [
                        "filename",
                        "author"
                    ],
                    "limit": 2
                }
            ]
        }
    ]
}

在下表中，排名会保持，但结果由两个属性同时折叠，以查找 Filename 和 Author 的唯一组合。 这会导致保留前四行并排除第五行，因为 Note (Filename) 和 James (Author) 的组合最多只能允许 2 次。 最后三行保留的原因相同。

Filename 作者 主题 Rank
注意 安 迪 诗歌 1
注意 詹姆斯 历史记录 2
注意 罗伯特 Culture 3
注意 詹姆斯 数学 4
笔记本 詹姆斯 科学 6
笔记本 安 迪 Culture 7
笔记本 詹姆斯 科学 8

示例 3：多级折叠

请求

POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json

{
    "requests": [
        {
            "entityTypes": [
                "listItem"
            ],
            "query": {
                "queryString": "note"
            },
            "fields": [
                "filename",
                "author"
            ],
            "collapseProperties": [
                {
                    "fields": [
                        "filename"
                    ],
                    "limit": 3
                },
                {
                    "fields": [
                        "author"
                    ],
                    "limit": 1
                }
            ]
        }
    ]
}

在下表中，排名保持不变，但结果首先在文件名上折叠，然后在作者上折叠。 对于 Filename 的第一级折叠，限制为 3，前三行将保留，删除第四行和第五行，最后三行保持原样。 对于限制为 1 的第二级折叠，前三行不会更改，因为每个行都有唯一的 Author 值。 排除第 8 行，因为 James 再次列为 Author，并且该属性必须具有唯一值。

Filename 作者 主题 Rank
注意 安 迪 诗歌 1
注意 詹姆斯 历史记录 2
注意 罗伯特 Culture 3
笔记本 詹姆斯 科学 6
笔记本 安 迪 Culture 7

响应

使用 collapseProperties 时，响应包含每个结果的 isCollapsed 布尔属性。 此属性指示结果的折叠状态。

HTTP/1.1 200 OK
Content-type: application/json

{
    "value": [
        {
            "searchTerms": [
                "note"
            ],
            "hitsContainers": [
                {
                    "hits": [
                        {
                            "hitId": "94149344-55e4-4678-b22a-b37a9ed1ffff",
                            "rank": 1,
                            "isCollapsed": true,
                            "summary": "",
                            "resource": {
                                "@odata.type": "#microsoft.graph.listItem",
                                "sharepointIds": {
                                    "listId": "9b786f01-4668-4862-8bbf-443159c0ffff",
                                    "listItemId": "3"
                                },
                                "id": "94149344-55e4-4678-b22a-b37a9ed1ffff",
                                "createdDateTime": "2012-10-10T12:07:57Z",
                                "lastModifiedDateTime": "2022-11-30T08:38:47Z",
                                "parentReference": {
                                    "id": "01PPFMTLYPOGQADPQCOJAJTXZLKETTQP6F",
                                    "siteId": "microsoftapc-my.sharepoint.com,5b8af7a0-0c23-4719-ab6c-457c2104ea8a,2e4df0d0-c83a-473b-bed1-2d2046966d31"
                                },
                                "webUrl": "https://microsoftapc-my.sharepoint.com/Documents/Notes"
                            }
                        }
                    ],
                    "total": 4281349,
                    "moreResultsAvailable": true
                }
            ]
        }
    ],
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.searchResponse)"
}

已知限制

以下资源不支持 collapseProperties 属性： message、chatMessage、 event、 person、 externalItem、 bookmark、 acronym 或 qna。

后续步骤