Использование API поиска (Майкрософт) для поиска содержимого OneDrive и SharePoint

Статья
05/09/2024

Используйте 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.

Дальнейшие действия

Использование API Поиска (Майкрософт) для запроса данных

Поделиться через

Использование API поиска (Майкрософт) для поиска содержимого OneDrive и SharePoint

Пример 1. Поиск файлов

Запрос

Отклик

Пример 2. Поиск элементов списка

Запрос

Отклик

Пример 3. Поиск сайтов

Запрос

Отклик

Пример 4. Поиск всего содержимого в OneDrive и SharePoint

Запрос

Отклик

Пример 5. Использование фильтров в поисковых запросах

Пример 6. Указание свойств выбора

Запрос listItem

Ответ listItem

запрос driveItem

Ответ driveItem

Пример 7. Поиск скрытого содержимого

Запрос

Отклик

Известные ограничения

Дальнейшие действия

Обратная связь

Дополнительные ресурсы