Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Use a API de Pesquisa da Microsoft no Microsoft Graph para pesquisar conteúdo armazenado no OneDrive ou no SharePoint: arquivos, pastas, listas, itens de lista ou sites.
Cuidado
O esquema da API de pesquisa foi alterado na versão beta. Algumas propriedades em uma solicitação e resposta de pesquisa foram renomeadas ou removidas. Para obter detalhes, consulte Aviso de substituição de alteração de esquema. Os exemplos neste tópico mostram o esquema atualizado.
A API de Pesquisa permite definir o escopo dos tipos de conteúdo a serem recuperados no OneDrive ou no SharePoint especificando a propriedade entityTypes no searchRequest. Este artigo descreve alguns exemplos.
Exemplo 1: Pesquisar arquivos
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: Pesquisar itens da 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: sites de pesquisa
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: Pesquisar todo o conteúdo no OneDrive e no SharePoint
Este exemplo consulta todo o conteúdo nos sites do OneDrive e do SharePoint aos quais o usuário conectado tem acesso de leitura. A propriedade de recurso na resposta retorna correspondências que são arquivos e pastas como objetos driveItem , correspondências que são contêineres (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: Usar filtros em consultas de pesquisa
Você pode usar KQL em termos de pesquisa de consultas para OneDrive e SharePoint. Por exemplo:
-
"query": "contoso filetype:docx OR filetype:doc"define o escopo da consulta para documentos do Word. -
"query": "test path:\"https://contoso.sharepoint.com/sites/Team Site/Documents/Project\""Define o escopo da consulta para uma pasta específica em um site. -
"query": "contoso AND isDocument=true"Define o escopo da consulta para retornar apenas documentos. Nenhum contêiner (pasta, biblioteca de documentos) não é retornado. -
"query": "contoso contentclass:STS_List_Events"define o escopo da consulta para eventos do Calendar armazenados no SharePoint. -
"query": "contoso (LastModifiedTime > 2021-02-01 AND Created > 2021-02-01)"define o escopo da consulta para filtrar itens do SharePoint e do OneDrive por data.
Para ser válida, a restrição de propriedades deve especificar um nome de propriedade gerenciada válido e consultável na condição.
Exemplo 6: Especificar propriedades selecionadas
Você pode especificar os campos que deseja de volta na resposta, como parte da subpropriedade fields em listItem ou uma subpropriedade listItem interna em driveItem de um objeto searchHit na resposta. Essa é uma maneira de reduzir a resposta por fio ou solicitar algumas propriedades específicas que não fazem parte do esquema pronto para uso.
Observe que a seleção de propriedades para propriedades personalizadas no SharePoint só está disponível para listItem ou driveItem porque essas são as duas únicas entidades do SharePoint no Microsoft Graph que dão suporte a propriedades personalizadas.
solicitação 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 "
}
}
}
]
}
]
}
]
}
Solicitação 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: Pesquisar conteúdo oculto
Use a propriedade includeHiddenContent para incluir conteúdo oculto, como conteúdo arquivado e SharePoint Embedded, nos resultados da pesquisa. Por padrão, essa propriedade é definida como false, o que impede que conteúdo oculto seja retornado.
Opcionalmente, você também pode incluir KQL para definir o escopo de sua 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 incluirão apenas o conteúdo não oculto relevante, desde que não haja outros erros e retornem um código de 200 OK resposta.
O exemplo a seguir mostra como usar o queryTemplate para definir o escopo da consulta com KQL e a propriedade includeHiddenContent para incluir conteúdo oculto. Você também pode criar um escopo para consultas no conteúdo inserido do SharePoint usando propriedades como ContainerTypeId. Para obter mais informações sobre tipos de contêiner no SharePoint Embedded, consulte Tipos de contêiner do SharePoint Embedded.
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 pesquisar por drive, você precisa incluir no queryString um termo contido no nome da biblioteca de documentos. Não há suporte para
*consultas e não retorna todas as unidades disponíveis.A API de pesquisa não dá suporte ao esquema de pesquisa no nível do site. Use o esquema de pesquisa padrão ou no nível do locatário.
A propriedade includeHiddenContent só funciona em cenários com permissões delegadas. Não é aplicável para permissões de aplicativo, em que a propriedade includeHiddenContent é definida automaticamente como
false.