searchEntity: query

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Executar uma consulta de pesquisa especificada. Os resultados da pesquisa são fornecidos na resposta.

Cuidado

Os recursos usados em uma solicitação e resposta da API Pesquisa da Microsoft têm propriedades renomeadas ou removidas ou estão sendo preteridas. Encontre mais detalhes sobre a substituição. Atualize as consultas da API de pesquisa em todos os aplicativos anteriores.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) Mail.Read Acronym.Read.All, Bookmark.Read.All, Calendars.Read, Chat. Read, ExternalItem.Read.All, Files. Read.All, QnA.Read.All, Sites.Read.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Files.Read.All Sites.Read.All

Solicitação HTTP

POST /search/query

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-type application/json. Obrigatório.

Corpo da solicitação

Forneça um objeto JSON com os seguintes parâmetros no corpo da solicitação.

Parâmetro Tipo Descrição
de solicitações coleção searchRequest Uma coleção de uma ou mais solicitações de pesquisa, cada uma formatada em um blob JSON. Cada blob JSON contém os tipos de recursos esperados na resposta, as fontes subjacentes, os parâmetros de paginação, os campos solicitados e a consulta de pesquisa real. Esteja ciente das limitações conhecidas na pesquisa de combinações específicas de tipos de entidade e na classificação ou agregação dos resultados da pesquisa.

Resposta

Se for bem-sucedido, esse método retornará um HTTP 200 OK código de resposta e uma coleção de objetos searchResponse no corpo da resposta.

Cada objeto searchHit pode incluir a propriedade sensitivityLabel quando o recurso de resultado tem um rótulo de confidencialidade.

Exemplos

Exemplo 1: chamada básica para executar uma solicitação de pesquisa

O exemplo a seguir mostra como executar uma pesquisa para obter os itens de conector esperados.

Solicitação

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

{
  "requests": [
    {
      "entityTypes": [
        "externalItem"
      ],
      "contentSources": [
        "/external/connections/connectionfriendlyname"
      ],
      "region": "US",
      "query": {
        "queryString": "contoso product"
      },
      "from": 0,
      "size": 25,
      "fields": [
        "title",
        "description"
      ]
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
  "value": [
    {
      "searchTerms": [
        "searchTerms-value"
      ],
      "hitsContainers": [
        {
          "hits": [
            {
              "hitId": "1",
              "rank": 1,
              "summary": "_summary-value",
              "resource": "The source field will contain the underlying graph entity part of the response"
            }
          ],
          "total": 47,
          "moreResultsAvailable": true
        }
      ]
    }
  ]
}

Exemplo 2: chamada básica para usar queryTemplate

O exemplo a seguir mostra como usar a propriedade queryable createdBy para recuperar todos os arquivos criados por um usuário.

Solicitação

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

{
  "requests": [
    {
      "entityTypes": [
        "listItem"
      ],
      "region": "US",
      "query": {
        "queryString": "contoso",
        "queryTemplate":"{searchTerms} CreatedBy:Bob"
      },
      "from": 0,
      "size": 25
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
    "value": [
        {
            "searchTerms": [
                "contoso"
            ],
            "hitsContainers": [
                {
                    "hits": [
                        {
                            "hitId": "1",
                            "rank": 1,
                            "summary": "_summary-value",
                            "resource": {
                                "@odata.type": "#microsoft.graph.listItem",
                                "id": "c23c7035-73d6-4bad-8901-9e2930d4be8e",
                                "createdBy": {
                                    "user": {
                                        "displayName": "Bob",
                                        "email": "[email protected]"
                                    }
                                },
                                "createdDateTime": "2021-11-19T17:04:18Z",
                                "lastModifiedDateTime": "2023-03-09T18:52:26Z"
                            },
                            "sensitivityLabel": {
                                "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e288",
                                "displayName": "Confidential",
                                "tooltip": "Data intended only for approved recipients.",
                                "priority": 4,
                                "color": "#FF8C00"
                            }
                        }
                    ],
                    "total": 1,
                    "moreResultsAvailable": false
                }
            ]
        }
    ]
}