Utilizar a API de Pesquisa da Microsoft para procurar conteúdos do OneDrive e do SharePoint
Utilize a API de Pesquisa da Microsoft no Microsoft Graph para procurar conteúdos armazenados no OneDrive ou SharePoint: ficheiros, pastas, listas, itens de lista ou sites.
Cuidado
O esquema da API de pesquisa foi alterado na versão beta. Algumas propriedades num pedido de pesquisa e resposta foram renomeadas ou removidas. Para obter detalhes, veja Aviso de descontinuação da alteração de esquema. Os exemplos neste tópico mostram o esquema atualizado.
A API de Pesquisa permite-lhe definir o âmbito dos tipos de conteúdo a obter no OneDrive ou no SharePoint ao especificar a propriedade entityTypes no searchRequest. Este artigo descreve alguns exemplos.
Exemplo 1: Procurar ficheiros
Solicitação
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "contoso"
}
}
]
}
Resposta
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"
}
}
}
]
}
]
}
]
}
Exemplo 2: procurar itens de lista
Solicitação
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"listItem"
],
"query": {
"queryString": "contoso"
}
}
]
}
Resposta
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"
}
}
}
]
}
]
}
]
}
Exemplo 3: Procurar sites
Solicitação
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"site"
],
"query": {
"queryString": "contoso"
}
}
]
}
Resposta
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/"
}
}
]
}
]
}
]
}
Exemplo 4: Procurar todos os conteúdos no OneDrive e no SharePoint
Este exemplo consulta todos os conteúdos nos sites do OneDrive e do SharePoint aos quais o utilizador com sessão iniciada tem acesso de leitura. A propriedade de recurso na resposta devolve correspondências que são ficheiros e pastas como objetos driveItem , correspondências que são contentores (listas do SharePoint) como lista e todas as outras correspondências como listItem.
Solicitação
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem", "listItem", "list"
],
"query": {
"queryString": "contoso"
}
}
]
}
Resposta
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"
}
}
]
}
]
}
]
}
Exemplo 5: Utilizar filtros em consultas de pesquisa
Pode utilizar o KQL em termos de pesquisa de consultas para o OneDrive e o SharePoint. Por exemplo:
-
"query": "contoso filetype:docx OR filetype:doc"define o âmbito da consulta para documentos do Word. -
"query": "test path:\"https://contoso.sharepoint.com/sites/Team Site/Documents/Project\""define o âmbito da consulta para uma pasta específica dentro de um site. -
"query": "contoso AND isDocument=true"define o âmbito da consulta para devolver apenas documentos. Não é devolvido qualquer contentor (pasta, biblioteca de documentos). -
"query": "contoso contentclass:STS_List_Events"define o âmbito da consulta para eventos do Calendário armazenados no SharePoint. -
"query": "contoso (LastModifiedTime > 2021-02-01 AND Created > 2021-02-01)"define o âmbito da consulta para filtrar itens do SharePoint e do OneDrive por data.
Para ser válido, a restrição de propriedades deve especificar um nome de propriedade gerida válido e consultada na condição.
Exemplo 6: Especificar propriedades de seleção
Pode especificar os campos que pretende na resposta, como parte da subpropriedade de campos em listItem ou uma subpropriedade listItem interna em driveItem de um objeto searchHit na resposta. Esta é uma forma de cortar a resposta por cima do fio ou pedir algumas propriedades específicas que não fazem parte do esquema de configuração inicial.
Tenha em atenção que a seleção de propriedades para propriedades personalizadas no SharePoint só está disponível para listItem ou driveItem porque estas são as únicas duas entidades do SharePoint no Microsoft Graph que suportam propriedades personalizadas.
pedido listItem
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"listItem"
],
"query": {
"queryString": "contoso"
},
"fields": [
"title",
"contentclass"
]
}
]
}
resposta 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 "
}
}
}
]
}
]
}
]
}
pedido driveItem
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "contoso"
},
"fields": [
"listId",
"author",
"title"
]
}
]
}
resposta 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)"
}
Exemplo 7: Procurar conteúdo oculto
Utilize a propriedade includeHiddenContent para incluir conteúdo oculto, como conteúdo arquivado e SharePoint Embedded, nos resultados da pesquisa. Por predefinição, esta propriedade está definida como false, o que impede que o conteúdo oculto seja devolvido.
Opcionalmente, também pode incluir o KQL para definir o âmbito da consulta de conteúdo oculto para tipos de conteúdo específicos. Por exemplo, no SharePoint, os administradores podem marcar sites como arquivados. Se o conteúdo oculto não estiver disponível, os resultados da pesquisa incluem apenas conteúdo não histórico relevante, desde que não existam outros erros e devolva um 200 OK código de resposta.
O exemplo seguinte mostra como utilizar o queryTemplate para definir o âmbito da consulta com kQL e a propriedade includeHiddenContent para incluir conteúdo oculto. Também pode definir o âmbito de consultas em conteúdos do SharePoint Embedded através de propriedades como ContainerTypeId. Para obter mais informações sobre os tipos de contentor no SharePoint Embedded, veja Tipos de ContentorEs Incorporados do SharePoint.
Solicitação
POST /search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"driveItem"
],
"query": {
"queryString": "*",
"queryTemplate": "({searchTerms} AuthorOWSUSER:TestContoso)"
},
"sharePointOneDriveOptions": {
"includeHiddenContent": true
}
}
]
}
Resposta
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)"
}
Limitações conhecidas
Ao procurar unidade, tem de incluir na consultaString um termo contido no nome da biblioteca de documentos. A
*consulta não é suportada e não devolve todas as unidades disponíveis.A API de pesquisa não suporta o esquema de pesquisa ao nível do site. Utilize o esquema de pesquisa predefinido ou ao nível do inquilino.
A propriedade includeHiddenContent só funciona em cenários com permissões delegadas. Não é aplicável para permissões de aplicação, em que a propriedade includeHiddenContent é definida automaticamente como
false.