Recuperar dados de aterramento

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.

A API de recuperação do Microsoft 365 Copilot recupera trechos de texto relevantes do conteúdo dos conectores do SharePoint, OneDrive e Copilot. A segurança da API corta o conteúdo do usuário que está chamando e respeita os controles de acesso definidos no locatário. Use a API de recuperação para fundamentar suas soluções de IA generativa com dados do Microsoft 365 e, ao mesmo tempo, otimizar a recuperação de contexto.

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)	Files. Read.All, Sites.Read.All*	ExternalItem.Read.All
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Aplicativo	Sem suporte.	Sem suporte.

* Para recuperar o conteúdo do SharePoint e do OneDrive, você precisa de ambos os Files. Permissões Read.All e Sites.Read.All.

Solicitação HTTP

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

POST https://graph.microsoft.com/v1.0/copilot/retrieval

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 opcionais e obrigatórios que você pode usar ao chamar essa ação.

Parâmetro	Tipo	Descrição
`queryString`	Cadeia de caracteres	Cadeia de caracteres de consulta em linguagem natural usada para recuperar trechos de texto relevantes. Esse parâmetro tem um limite de 1.500 caracteres. Deve `queryString` ser uma única frase e você deve evitar erros de ortografia em palavras-chave ricas em contexto. Obrigatório.
`dataSource`	Cadeia de caracteres	Indica se as extrações devem ser recuperadas dos conectores do SharePoint, do OneDrive ou do Copilot. Os valores aceitáveis são `sharePoint`, `oneDriveBusiness`, e `externalItem`. Obrigatório.
`dataSourceConfiguration`	dataSourceConfiguration	Contém informações de configuração adicionais para fontes de dados aplicáveis. `dataSourceConfiguration` inclui um objeto chamado `externalItem`, no qual você pode configurar a recuperação de conectores do Copilot. Opcional.
`filterExpression`	Cadeia de caracteres	expressão KQL (QL por palavra-chave) com propriedades e atributos de conectores do SharePoint, OneDrive ou Copilot que podem ser consultados para definir o escopo da recuperação antes que a consulta seja executada. Você pode usar `AND`os operadores , `OR`, e de desigualdade, quando aplicável, `NOT`ao criar seu `filterExpression`. As propriedades do SharePoint e do OneDrive com suporte para filtragem são: `Author`, `FileExtension`, `Filename`, `FileTypeInformationProtectionLabelId`, , `LastModifiedTime`, `PathModifiedBySiteID`, e .`Title` Ao filtrar o conteúdo dos conectores do Copilot, você pode usar qualquer propriedade marcada como consultável no esquema do conector do Copilot. Entre em contato com o administrador ou desenvolvedor que configurou o conector Copilot desejado para obter uma lista de propriedades marcadas como consultáveis. A Microsoft não resolverá nenhum problema com a filtragem nas propriedades de conectores do SharePoint e do Copilot não mencionadas aqui. Você pode usar várias propriedades e operadores ao construir seu `filterExpression`arquivo . Por padrão, nenhum escopo é aplicado. Verifique se esse parâmetro tem a sintaxe KQL correta antes de chamar a API. Caso contrário, a consulta será executada como se não houvesse nenhum `filterExpression`domínio . Opcional. Para obter práticas recomendadas para consultas filtradas, consulte Práticas recomendadas.
`resourceMetadata`	String collection	Uma lista de campos de metadados a serem retornados para cada item na resposta. Somente propriedades de metadados recuperáveis podem ser incluídas nesta lista. Por padrão, nenhum metadado é retornado. Opcional.
`maximumNumberOfResults`	Int32	O número de resultados retornados na resposta. Deve estar entre 1 e 25. Por padrão, retorna até 25 resultados. Opcional.

Parâmetro	Tipo	Descrição
`queryString`	Cadeia de caracteres	Cadeia de caracteres de consulta em linguagem natural usada para recuperar trechos de texto relevantes. Esse parâmetro tem um limite de 1.500 caracteres. Deve `queryString` ser uma única frase e você deve evitar erros de ortografia em palavras-chave ricas em contexto. Obrigatório.
`dataSource`	Cadeia de caracteres	Indica se as extrações devem ser recuperadas dos conectores do SharePoint, do OneDrive ou do Copilot. Os valores aceitáveis são `sharePoint`, `oneDriveBusiness`, e `externalItem`. Obrigatório.
`dataSourceConfiguration`	dataSourceConfiguration	Contém informações de configuração adicionais para fontes de dados aplicáveis. `dataSourceConfiguration` inclui um objeto chamado `externalItem`, no qual você pode configurar a recuperação de conectores do Copilot. Opcional.
`filterExpression`	Cadeia de caracteres	expressão KQL (QL por palavra-chave) com propriedades e atributos de conectores do SharePoint, OneDrive ou Copilot que podem ser consultados para definir o escopo da recuperação antes que a consulta seja executada. Você pode usar `AND`os operadores , `OR`, e de desigualdade, quando aplicável, `NOT`ao criar seu `filterExpression`. As propriedades do SharePoint e do OneDrive com suporte para filtragem são: `Author`, `FileExtension`, `Filename`, `FileTypeInformationProtectionLabelId`, , `LastModifiedTime`, `PathModifiedBySiteID`, e .`Title` Ao filtrar o conteúdo dos conectores do Copilot, você pode usar qualquer propriedade marcada como consultável no esquema do conector do Copilot. Entre em contato com o administrador ou desenvolvedor que configurou o conector Copilot desejado para obter uma lista de propriedades marcadas como consultáveis. A Microsoft não resolverá nenhum problema com a filtragem nas propriedades de conectores do SharePoint e do Copilot não mencionadas aqui. Você pode usar várias propriedades e operadores ao construir seu `filterExpression`arquivo . Por padrão, nenhum escopo é aplicado. Verifique se esse parâmetro tem a sintaxe KQL correta antes de chamar a API. Caso contrário, a consulta será executada como se não houvesse nenhum `filterExpression`domínio . Opcional. Para obter práticas recomendadas para consultas filtradas, consulte Práticas recomendadas.
`resourceMetadata`	String collection	Uma lista de campos de metadados a serem retornados para cada item na resposta. Somente propriedades de metadados recuperáveis podem ser incluídas nesta lista. Por padrão, nenhum metadado é retornado. Opcional.
`maximumNumberOfResults`	Int32	O número de resultados retornados na resposta. Deve estar entre 1 e 25. Por padrão, retorna até 25 resultados. Opcional.
`includeThumbnails`	Booliano	Indica se os números de página e as miniaturas devem ser incluídos na resposta de recuperação, se disponível. Se várias extrações fizerem referência à mesma página, apenas uma única cópia da miniatura associada será retornada com a ocorrência de recuperação. Opcional.

Resposta

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

Exemplos

Exemplo 1: recuperar dados do SharePoint

O exemplo a seguir mostra uma solicitação para recuperar dados do SharePoint. A solicitação solicita que os title metadados and author sejam retornados para cada item do qual uma extração de texto é recuperada. A resposta inclui um máximo de 10 documentos.

Solicitação

O exemplo a seguir mostra a solicitação.

▶ Experimente na demonstração interativa

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
          "relevanceScore": 0.7588038775683956
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.6696818957446697
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "Corporate VPN",
        "author": "Jane Doe"
      },
        "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Exemplo 2: recuperar dados de conectores do Copilot

O exemplo a seguir mostra uma solicitação para recuperar dados de conectores do Copilot. A solicitação solicita que os title metadados and author sejam retornados para cada item do qual uma extração de texto é recuperada. A resposta inclui um máximo de 10 documentos.

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

Exemplo 3: Solicitações em lote para a API de recuperação

O exemplo a seguir mostra como fazer solicitações em lote para a API de recuperação. A API de recuperação 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.

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

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "sharePoint"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "externalItem"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

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

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "sharePoint"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "How to setup corporate VPN?",
        "dataSource": "externalItem"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

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": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
                "relevanceScore": 0.8374363553387588
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.7465472642498679
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00"
            }
          },
          {
            "webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
                "relevanceScore": 0.7588038775683956
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.6696818957446697
              }
            ],
            "resourceType": "listItem",
            "resourceMetadata": {},
            "sensitivityLabel": {
              "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
              "displayName": "Confidential\\Any User (No Protection)",
              "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
              "priority": 4,
              "color": "#FF8C00"
            }
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "headers": {
        "Content-Type": "application/json; charset=utf-8"
      },
      "body": {
        "retrievalHits": [
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
            "extracts": [
              {
                "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
                "relevanceScore": 0.874
              },
              {
                "text": "You will need to sign in with 2FA to access the corporate VPN.",
                "relevanceScore": 0.801
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          },
          {
            "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
            "extracts": [
              {
                "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
                "relevanceScore": 0.772
              },
              {
                "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
                "relevanceScore": 0.655
              }
            ],
            "resourceType": "externalItem",
            "resourceMetadata": {}
          }
        ]
      }
    }
  ]
}

Exemplo 4: recuperar dados de um site específico do SharePoint

O exemplo a seguir mostra uma solicitação para recuperar dados de um site específico do SharePoint. O filterExpression parâmetro especifica o caminho para o site. A solicitação solicita que os title metadados and author sejam retornados para cada item do qual uma extração de texto é recuperada. A resposta inclui até quatro documentos.

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Exemplo 5: recuperar dados de vários sites do SharePoint

O exemplo a seguir mostra uma solicitação para recuperar dados de vários sites do SharePoint. O filterExpression parâmetro especifica os caminhos para os sites. A solicitação solicita que os title metadados and author sejam retornados para cada item do qual uma extração de texto é recuperada. A resposta deve incluir um máximo de quatro documentos.

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 4
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Config",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679
        },
        {
          "text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
          "relevanceScore": 0.7374363553387588
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Instructions",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Exemplo 6: recuperar dados de conectores do Copilot usando IDs de conexão específicas

O exemplo a seguir mostra uma solicitação que restringe a recuperação de conectores do Copilot a IDs de conexão específicas. A solicitação solicita que os title metadados and author sejam retornados para cada item do qual uma extração de texto é recuperada. A resposta inclui até 10 documentos.

Solicitação

O exemplo a seguir mostra a solicitação.

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "dataSourceConfiguration": {
    "externalItem": {
      "connections": [
        {
          "connectionId": "ContosoITServiceNowKB"
        },
        {
          "connectionId": "ContosoHRServiceNowKB"
        }
      ]
    }
  },
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "externalItem",
  "dataSourceConfiguration": {
    "externalItem": {
      "connections": [
        {
          "connectionId": "ContosoITServiceNowKB"
        },
        {
          "connectionId": "ContosoHRServiceNowKB"
        }
      ]
    }
  },
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.874
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.801
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      }
    },
    {
      "webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
      "extracts": [
        {
          "text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
          "relevanceScore": 0.772
        },
        {
          "text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
          "relevanceScore": 0.655
        }
      ],
      "resourceType": "externalItem",
      "resourceMetadata": {
        "title": "Corporate VPN"
      }
    }
  ]
}

Exemplo 7: Usar expressões de filtro

Os exemplos a seguir mostram expressões KQL que você pode usar na filterExpression propriedade para cenários específicos.

Filtrar nas propriedades do conector do Copilot

Neste exemplo, Label_Title é uma propriedade consultável no esquema do conector do Copilot do ServiceNow. A consulta filtra os itens que contêm Corporate VPN a Label_Title propriedade.

"filterExpression": "Label_Title:\"Corporate VPN\""

Filtrar resultados do `Author` SharePoint na propriedade

Neste exemplo, a consulta filtra itens com Megan Bowen como autora.

"filterExpression": "Author:\"Megan Bowen\""

Filtrar resultados do SharePoint em um intervalo de datas específico usando a `LastModifiedTime` propriedade

Neste exemplo, a consulta filtra itens modificados entre 22 de julho de 2024 e 8 de janeiro de 2025.

"filterExpression": "LastModifiedTime>= 2024-07-22 AND LastModifiedTime<= 2025-01-08"

Filtrar resultados do SharePoint usando a `FileExtension` propriedade

Neste exemplo, a consulta filtra arquivos com a extensão de arquivo .docx, .pdf ou .pptx.

"filterExpression": "FileExtension:\"docx\" OR FileExtension:\"pdf\" OR FileExtension:\"pptx\""

Filtrar resultados do SharePoint usando a `Filename` propriedade

Neste exemplo, os filtros de consulta em arquivos chamados Contoso Mission Statement.docx.

"filterExpression": "Filename:\"Contoso Mission Statement.docx\""

Filtrar resultados do SharePoint usando a `FileType` propriedade

Neste exemplo, a consulta filtra arquivos PDF, apresentações do PowerPoint e documentos do Word.

"filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\""

Determinar a confidencialidade dos resultados do SharePoint filtrando usando a `InformationProtectionLabelId` propriedade

Neste exemplo, a consulta filtra itens com um rótulo de proteção de informações específico.

"filterExpression": "InformationProtectionLabelId:\"f0ddcc93-d3c0-4993-b5cc-76b0a283e252\""

Filtrar resultados do SharePoint usando a `ModifiedBy` propriedade

Neste exemplo, a consulta filtra itens modificados por Adele Vance.

"filterExpression": "ModifiedBy:\"Adele Vance\""

Filtrar resultados do SharePoint usando a `SiteID` propriedade

Neste exemplo, a consulta filtra itens de um site específico do SharePoint.

"filterExpression": "SiteID:\"e2cf7e40-d689-41de-99ee-a423811a253c\""

Filtrar resultados do SharePoint usando a `Title` propriedade

Neste exemplo, a consulta filtra itens com Windows 10 Device no título.

"filterExpression": "Title:\"Windows 10 Device\""

Exemplo 8: Incluir miniaturas para extrações

O exemplo a seguir mostra uma solicitação que adiciona a includeThumbnails propriedade e a resposta associada que inclui miniaturas e os números de página associados.

Solicitação

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

{
  "queryString": "How to setup corporate VPN?",
  "dataSource": "sharePoint",
  "filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\"",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 2,
  "includeThumbnails": true
}

Resposta

O exemplo a seguir mostra a resposta.

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

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
      "extracts": [
        {
          "text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
          "relevanceScore": 0.8374363553387588,
          "pageNumbers": [
            1
          ]
        },
        {
          "text": "You will need to sign in with 2FA to access the corporate VPN.",
          "relevanceScore": 0.7465472642498679,
          "pageNumbers": [
            2
          ]
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Access",
        "author": "John Doe"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      },
      "thumbnails": [
        {
          "pageNumber": 1,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
        {
          "pageNumber": 2,
          "content": "base64/9j/4AAQSkZJRgABAQEAYABgAAD/2wBD",
          "mimeType": "image/jpg"
        },
      ]
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
      "extracts": [
        {
          "text": "Have your VPN username and password ready prior to starting the configuration.",
          "relevanceScore": 0.6465472642498679,
          "pageNumbers": [
            1,2
          ]
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "VPN Config",
        "author": "Elisa Mueller"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
        "displayName": "Confidential\\Any User (No Protection)",
        "toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
        "priority": 4,
        "color": "#FF8C00"
      }
    }
  ]
}

Comentários

Esta página foi útil?

Last updated on 2026-08-20

Recuperar dados de aterramento

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: recuperar dados do SharePoint

Solicitação

Resposta

Exemplo 2: recuperar dados de conectores do Copilot

Solicitação

Resposta

Exemplo 3: Solicitações em lote para a API de recuperação

Solicitação

Resposta

Exemplo 4: recuperar dados de um site específico do SharePoint

Solicitação

Resposta

Exemplo 5: recuperar dados de vários sites do SharePoint

Solicitação

Resposta

Exemplo 6: recuperar dados de conectores do Copilot usando IDs de conexão específicas

Solicitação

Resposta

Exemplo 7: Usar expressões de filtro

Filtrar nas propriedades do conector do Copilot

Filtrar resultados do Author SharePoint na propriedade

Filtrar resultados do SharePoint em um intervalo de datas específico usando a LastModifiedTime propriedade

Filtrar resultados do SharePoint usando a FileExtension propriedade

Filtrar resultados do SharePoint usando a Filename propriedade

Filtrar resultados do SharePoint usando a FileType propriedade

Determinar a confidencialidade dos resultados do SharePoint filtrando usando a InformationProtectionLabelId propriedade

Filtrar resultados do SharePoint usando a ModifiedBy propriedade

Filtrar resultados do SharePoint usando a SiteID propriedade

Filtrar resultados do SharePoint usando a Title propriedade

Exemplo 8: Incluir miniaturas para extrações

Solicitação

Resposta

Conteúdo relacionado

Comentários

Recursos adicionais

Filtrar resultados do `Author` SharePoint na propriedade

Filtrar resultados do SharePoint em um intervalo de datas específico usando a `LastModifiedTime` propriedade

Filtrar resultados do SharePoint usando a `FileExtension` propriedade

Filtrar resultados do SharePoint usando a `Filename` propriedade

Filtrar resultados do SharePoint usando a `FileType` propriedade

Determinar a confidencialidade dos resultados do SharePoint filtrando usando a `InformationProtectionLabelId` propriedade

Filtrar resultados do SharePoint usando a `ModifiedBy` propriedade

Filtrar resultados do SharePoint usando a `SiteID` propriedade

Filtrar resultados do SharePoint usando a `Title` propriedade