Executar pesquisa usando a API de pesquisa do Microsoft 365 Copilot

Importante

As APIs sob a /beta versão estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção.

Realize pesquisas híbridas (semânticas e lexicais) no OneDrive para conteúdo corporativo ou de estudante usando consultas em linguagem natural com compreensão contextual. Descubra documentos e arquivos relevantes aos quais você tem acesso, respeitando os controles de acesso definidos dentro da organização. Tente emitir sua primeira consulta para a API de pesquisa do Microsoft 365 Copilot. Saiba como você pode agrupar até 20 solicitações para a API de pesquisa.

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.

Para acessar os dados da fonte de dados do OneDrive corporativo ou de estudante, você precisa do Files. Read.All ou Files. ReadWrite.All. Você também precisa das permissões Sites.Read.All ou Sites.ReadWrite.All.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) Files. Read.All, Sites.Read.All Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Aplicativo Sem suporte. Sem suporte.

Solicitação HTTP

POST https://graph.microsoft.com/beta/copilot/search

Cabeçalhos de solicitação

Nome Descrição
Authorization Bearer {token}. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON dos parâmetros.

A tabela a seguir lista os parâmetros necessários quando você chama essa ação.

Parâmetro Tipo Descrição
query Cadeia de caracteres Consulta em linguagem natural para procurar arquivos relevantes. Máximo de 1.500 caracteres. Obrigatório.
pageSize Int32 Número de resultados a serem retornados por página (1 a 100). Padrão: 25. Opcional.
dataSources copilotSearchDataSourcesConfiguration Configuração para fontes de dados a serem incluídas na pesquisa. Opcional.

Resposta

Se for bem-sucedida, essa ação retornará um código de 200 OK resposta e um copilotSearchResponse no corpo da resposta.

Exemplos

Exemplo 1: solicitação de pesquisa básica

O exemplo a seguir mostra os parâmetros mínimos necessários para executar uma pesquisa híbrida (semântica e lexical) no OneDrive para conteúdo corporativo ou de estudante.

Solicitação

O exemplo a seguir mostra a solicitação. Experimente este exemplo com o Graph Explorer.

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "How to setup corporate VPN?"
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "totalCount": 2,
  "searchHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/VPNAccess.docx",
      "preview": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option...",
      "resourceType": "driveItem"
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/Corporate_VPN.docx",
      "preview": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials...",
      "resourceType": "driveItem"
    }
  ]
}

Exemplo 2: Pesquisa com filtragem e metadados

O exemplo a seguir mostra uma solicitação com filtragem de caminho e coleta de metadados específicos do OneDrive. A solicitação pede que os title metadados and author sejam retornados para cada resultado de pesquisa.

Solicitação

O exemplo a seguir mostra a solicitação. Experimente este exemplo com o Graph Explorer.

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "quarterly budget analysis",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/\" OR path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "@odata.nextLink": "https://graph.microsoft.com/beta/copilot/searchNextPage?$skipToken=eyJDb250aW51YXRpb25Ub2tlbiI6...",
  "totalCount": 24,
  "searchHits": [
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/Q1_Budget_Analysis.xlsx",
      "preview": "This quarterly budget analysis shows significant improvements in operational efficiency and cost reduction across all departments...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Q1 Budget Analysis 2025",
        "author": "Megan Bowen"
      }
    },
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget/Annual_Financial_Review.docx",
      "preview": "The annual financial review demonstrates strong performance indicators and provides recommendations for the upcoming quarter...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Annual Financial Review",
        "author": "Alex Wilber"
      }
    }
  ]
}

Exemplo 3: Pesquisar com filtragem baseada em caminho

O exemplo a seguir mostra como pesquisar em caminhos específicos do OneDrive usando expressões de caminho QL por palavra-chave (KQL).

Solicitação

O exemplo a seguir mostra a solicitação. Experimente este exemplo com o Graph Explorer.

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "project timeline milestones",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "totalCount": 12,
  "searchHits": [
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/Project_Timeline_2026.docx",
      "preview": "The project timeline outlines key milestones for Q1 and Q2, including deliverable dates and resource requirements...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Project Timeline 2026",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/Milestone_Review.pptx",
      "preview": "Milestone review presentation covering completed deliverables, upcoming deadlines, and project status updates...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Milestone Review Presentation",
        "author": "Sarah Connor"
      }
    }
  ]
}

Exemplo 4: solicitações em lote para a API de Pesquisa

O exemplo a seguir mostra como fazer solicitações em lote para a API de Pesquisa. A API de Pesquisa dá suporte a até 20 solicitações por lote. O id conteúdo da solicitação deve ser uma cadeia de caracteres que identifica exclusivamente cada solicitação no lote.

Solicitação

O exemplo a seguir mostra a solicitação. Experimente este exemplo com o Graph Explorer.

POST https://graph.microsoft.com/beta/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "quarterly budget reports"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "project planning documents"
      }
    }
  ]
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "responses": [
    {
      "id": "1",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "totalCount": 15,
        "searchHits": [
          {
            "webUrl": "https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/Finance/Q1_Budget.xlsx",
            "preview": "Q1 budget analysis showing revenue growth and expense optimization across departments...",
            "resourceType": "driveItem"
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "totalCount": 8,
        "searchHits": [
          {
            "webUrl": "https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/Projects/Planning_Guide.docx",
            "preview": "Comprehensive project planning guide with templates and best practices for successful delivery...",
            "resourceType": "driveItem"
          }
        ]
      }
    }
  ]
}

Conteúdo relacionado

  • Last updated on