Использование API поиска (Майкрософт) для поиска содержимого OneDrive и SharePoint
Используйте API поиска (Майкрософт) в Microsoft Graph для поиска содержимого, хранящегося в OneDrive или SharePoint: файлов, папок, списков, элементов списка или сайтов.
Предостережение
Схема API поиска изменилась в бета-версии. Некоторые свойства в поисковом запросе и ответе были переименованы или удалены. Дополнительные сведения см. в разделе Предупреждение об изменении схемы об устаревании. В примерах в этом разделе показана актуальная схема.
API поиска позволяет определить типы контента, извлекаемого в OneDrive или SharePoint, указав свойство entityTypes в searchRequest. В этой статье описаны некоторые примеры.
Пример 1. Поиск файлов
Запрос
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "contoso"
}
}
]
}
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "FlULeN/ui/1GjLx1rUfio5UAAEl",
"rank": 1,
"summary": "<c0>Contoso</c0> Detailed Design <ddd/>",
"resource": {
"@odata.type": "#microsoft.graph.driveItem",
"createdDateTime": "2019-06-10T06:37:43Z",
"lastModifiedDateTime": "2019-06-10T06:37:43Z",
"name": "web_part_test_long Notebook",
"webUrl": "https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx",
"createdBy": {
"user": {
"displayName": "Michaelvincent Santos;Provisioning User"
}
},
"lastModifiedBy": {
"user": {
"displayName": "Richard Mayer"
}
},
"parentReference": {
"siteId": "m365x231305.sharepoint.com,5724d91f-650c-4810-83cc-61a8818917d6,c3ba25dc-2c9f-48cb-83be-74cdf68ea5a0",
"driveId": "da61a2b0-4120-4a3f-812b-0fc0d79bf16b",
"sharepointIds": {
"listId": "c61d1892-ca82-4f53-b16f-6bb8a379e2b2",
"listItemId": "1027",
"listItemUniqueId": "E320AFEB-AD73-46A2-83D7-985FAA4B206D"
}
},
"fileSystemInfo": {
"createdDateTime": "2019-06-10T06:37:43Z",
"lastModifiedDateTime": "2019-06-10T06:37:43Z"
}
}
}
]
}
]
}
]
}
Пример 2. Поиск элементов списка
Запрос
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"listItem"
],
"query": {
"queryString": "contoso"
}
}
]
}
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "FlULeN/ui/1GjLx1rUfio5UAAEl",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.listItem",
"createdDateTime": "2019-06-10T06:37:43Z",
"lastModifiedDateTime": "2019-06-10T06:37:43Z",
"name": "web_part_test_long Notebook",
"webUrl": "https://contoso.sharepoint.com/sites/contoso-team/Lists/Issue tracker list/DispForm.aspx?ID=1",
"sharepointIds": {
"listId": "33498de0-d695-4d23-ac26-e1bf95a3206e",
"listItemId": "13"
},
"createdBy": {
"user": {
"displayName": "Michaelvincent Santos;Provisioning User"
}
},
"lastModifiedBy": {
"user": {
"displayName": "Richard Mayer"
}
},
"parentReference": {
"sharepointIds":{
"listId":"da61a2b0-4120-4a3f-812b-0fc0d79bf16b"
},
"siteId": "m365x231305.sharepoint.com,5724d91f-650c-4810-83cc-61a8818917d6,c3ba25dc-2c9f-48cb-83be-74cdf68ea5a0"
}
}
}
]
}
]
}
]
}
Пример 3. Поиск сайтов
Запрос
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"site"
],
"query": {
"queryString": "contoso"
}
}
]
}
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "contoso.sharepoint.com,6598ee0b-0f5f-4416-a0ae-66d864efb43a,60024ce8-e74d-4d63-a939-ad00cd738670",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.site",
"id": "contoso.sharepoint.com,6598ee0b-0f5f-4416-a0ae-66d864efb43a,60024ce8-e74d-4d63-a939-ad00cd738670",
"createdDateTime": "2019-06-10T06:37:43Z",
"description": "Contoso Communication Site",
"lastModifiedDateTime": "2020-08-30T06:41:56Z",
"webUrl": "https://contoso.sharepoint.com/sites/contoso-team/"
}
}
]
}
]
}
]
}
Пример 4. Поиск всего содержимого в OneDrive и SharePoint
В этом примере запрашивается все содержимое на сайтах OneDrive и SharePoint, к которым у пользователя, выполнившего вход, есть доступ на чтение. Свойство ресурса в ответе возвращает совпадения, которые представляют собой файлы и папки как объекты driveItem , совпадения, которые являются контейнерами (списки SharePoint) в виде списка, а все остальные совпадения — listItem.
Запрос
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem", "listItem", "list"
],
"query": {
"queryString": "contoso"
}
}
]
}
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"@odata.type": "#microsoft.graph.searchHitsContainer",
"hitId": "FlULeN/ui/1GjLx1rUfio5UAAEl",
"rank": 1,
"summary": "<c0>Contoso</c0> Detailed Design <ddd/>",
"resource": {
"@odata.type": "#microsoft.graph.driveItem",
"createdDateTime": "2019-06-10T06:37:43Z",
"lastModifiedDateTime": "2019-06-10T06:37:43Z",
"name": "web_part_test_long Notebook",
"webUrl": "https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx",
"createdBy": {
"user": {
"displayName": "Michaelvincent Santos;Provisioning User"
}
},
"lastModifiedBy": {
"user": {
"displayName": "Richard Mayer"
}
},
"parentReference": {
"siteId": "m365x231305.sharepoint.com,5724d91f-650c-4810-83cc-61a8818917d6,c3ba25dc-2c9f-48cb-83be-74cdf68ea5a0",
"driveId": "da61a2b0-4120-4a3f-812b-0fc0d79bf16b",
"sharepointIds": {
"listId": "c61d1892-ca82-4f53-b16f-6bb8a379e2b2",
"listItemId": "1027",
"listItemUniqueId": "E320AFEB-AD73-46A2-83D7-985FAA4B206D"
}
},
"fileSystemInfo": {
"createdDateTime": "2019-06-10T06:37:43Z",
"lastModifiedDateTime": "2019-06-10T06:37:43Z"
}
}
},
{
"@odata.type": "#microsoft.graph.searchHit",
"hitId": "51eef59e-5d49-4d28-96f0-864cf90765e0",
"rank": 2,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.list",
"displayName": "Contoso - Documents",
"id": "51eef59e-5d49-4d28-96f0-864cf90765e0",
"description": "",
"lastModifiedDateTime": "2020-07-08T18:17:59+00:00",
"name": "Shared Documents",
"parentReference": {
"siteId": "microsoft.sharepoint-df.com,220fd155-0ea2-477c-a816-5c08fdc45f5d,fad16ab6-0736-4fbc-a053-087296b47c99"
},
"webUrl": "https://microsoft.sharepoint-df.com/teams/spoppe/collab/TaskBoard/Contoso/Shared Documents/Forms/AllItems.aspx"
}
}
]
}
]
}
]
}
Пример 5. Использование фильтров в поисковых запросах
KQL можно использовать в поисковых запросах для OneDrive и SharePoint. Например:
-
"query": "contoso filetype:docx OR filetype:doc"ограничивает запрос документами Word. -
"query": "test path:\"https://contoso.sharepoint.com/sites/Team Site/Documents/Project\""область запроса к определенной папке на сайте. -
"query": "contoso AND isDocument=true"область запроса, чтобы возвращать только документы. Контейнер (папка, библиотека документов) не возвращается. -
"query": "contoso contentclass:STS_List_Events"ограничивает запрос событиями календаря, хранящимися в SharePoint. -
"query": "contoso (LastModifiedTime > 2021-02-01 AND Created > 2021-02-01)"область запроса для фильтрации элементов SharePoint и OneDrive по дате.
Чтобы быть допустимым, ограничение свойств должно указывать допустимое, запрашиваемое имя управляемого свойства в условии.
Пример 6. Указание свойств выбора
Вы можете указать нужные поля в ответе как часть подсвойства полей в listItem или внутреннего подсвойства listItem в driveItem объекта searchHit в ответе. Это способ либо обрезать ответ по сети, либо запросить некоторые конкретные свойства, которые не являются частью готовых схем.
Обратите внимание, что выбор свойств для пользовательских свойств в SharePoint доступен только для listItem или driveItem , так как это единственные две сущности SharePoint в Microsoft Graph, которые поддерживают пользовательские свойства.
Запрос listItem
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"listItem"
],
"query": {
"queryString": "contoso"
},
"fields": [
"title",
"contentclass"
]
}
]
}
Ответ listItem
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#search",
"value": [
{
"searchTerms": [
"contoso"
],
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "contoso.sharepoint.com,6598ee0b-0f5f-4416-a0ae-66d864efb43a,60024ce8-e74d-4d63-a939-ad00cd738670",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.listItem",
"createdDateTime": "2019-06-10T06:37:43Z",
"webUrl": "https://contoso.sharepoint.com/sites/contoso-team/contoso-designs.docx",
"sharepointIds": {
"listId": "33498de0-d695-4d23-ac26-e1bf95a3206e",
"listItemId": "13"
},
"parentReference": {
"siteId": "m365x231305.sharepoint.com,5724d91f-650c-4810-83cc-61a8818917d6,c3ba25dc-2c9f-48cb-83be-74cdf68ea5a0"
},
"fields": {
"contentclass": "STS_ListItem_GenericList",
"title": "Contoso issue "
}
}
}
]
}
]
}
]
}
запрос driveItem
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "contoso"
},
"fields": [
"listId",
"author",
"title"
]
}
]
}
Ответ driveItem
POST /search/query
Content-Type: application/json
{
"value": [
{
"searchTerms": [],
"hitsContainers": [
{
"hits": [
{
"hitId": "01YOWRGSD34TVVP25X7NAZAW3P2JRL7FWE",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.driveItem",
"listItem": {
"@odata.type": "#microsoft.graph.listItem",
"fields": {
"listId": "3b6a49d3-6bea-4549-bed8-8b1c92a12345",
"author": "Robin",
"title": "Test Notebook"
},
"id": "57ebe47b-b7eb-41fb-905b-123452bf96c4"
}
}
}
],
"total": 371,
"moreResultsAvailable": true
}
]
}
],
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)"
}
Пример 7. Поиск скрытого содержимого
Используйте свойство includeHiddenContent , чтобы включить в результаты поиска скрытое содержимое, например архивное содержимое и SharePoint Embedded. По умолчанию для этого свойства задано значение false, что предотвращает возврат скрытого содержимого.
Вы также можете добавить KQL, чтобы ограничить запрос скрытого содержимого определенными типами контента. Например, в SharePoint администраторы могут помечать сайты как архивные. Если скрытое содержимое недоступно, результаты поиска включают только соответствующее содержимое, не включаемое, при условии отсутствия других ошибок, и возвращают 200 OK код ответа.
В следующем примере показано, как использовать queryTemplate для области запроса с помощью KQL и свойства includeHiddenContent , чтобы включить скрытое содержимое. Вы также можете ограничить запросы к содержимому SharePoint Embedded с помощью таких свойств, как ContainerTypeId. Дополнительные сведения о типах контейнеров в SharePoint Embedded см. в статье Типы контейнеров SharePoint Embedded.
Запрос
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "*",
"queryTemplate": "({searchTerms} AuthorOWSUSER:TestContoso)"
},
"sharePointOneDriveOptions": {
"includeHiddenContent": true
}
}
]
}
Отклик
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"searchTerms": [],
"hitsContainers": [
{
"hits": [
{
"hitId": "fc78bcb9-8b26-4bba-a250-389def493e0f",
"rank": 2,
"summary": "<c0>STS</c0>_<c0>View</c0> <c0>MySiteDocumentLibrary</c0> <c0>domain</c0>_<c0>allow</c0>:<c0>ALL</c0><ddd/>",
"resource": {
"@odata.type": "#microsoft.graph.list",
"displayName": "TestContoso - Documents",
"id": "fc78bcb9-8b26-4bba-a250-389def493e0f",
"createdBy": {
"user": {
"displayName": "System Account"
}
},
"lastModifiedDateTime": "2024-03-08T18:06:33Z",
"name": "Documents",
"parentReference": {
"siteId": "contoso-my.sharepoint.com,44776ebc-4ddc-4f7e-afb8-b706c77e0883,a118ff93-1105-40b9-bed0-2cd07cd4b2a4"
},
"webUrl": "https://contoso-my.sharepoint.com/personal/contoso_onmicrosoft_com/Documents/Forms/All.aspx"
}
}
],
"total": 1,
"moreResultsAvailable": false
}
]
}
],
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.searchResponse)"
}
Известные ограничения
При поиске диска необходимо включить в queryString термин, содержащийся в имени библиотеки документов.
*Запросы не поддерживаются и не возвращают все доступные диски.API поиска не поддерживает схему поиска на уровне сайта. Используйте схему поиска на уровне клиента или схему поиска по умолчанию.
Свойство includeHiddenContent работает только в сценариях с делегированными разрешениями. Он не применяется для разрешений приложения, где свойство includeHiddenContent автоматически имеет значение
false.
Дальнейшие действия
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по