Criar uma fonte de conhecimento remota do SharePoint

Uma fonte de conhecimento remota do SharePoint usa a API de Recuperação do Copilot para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando resultados ao mecanismo de recuperação por meio de agentes para mesclagem, classificação e formulação de resposta. Não há nenhum índice de pesquisa usado por essa fonte de conhecimento e somente o conteúdo textual é consultado.

No momento da consulta, a fonte de conhecimento remota do SharePoint chama a API de Recuperação do Copilot em nome do usuário, portanto, nenhuma cadeia de conexão é necessária na definição da fonte de conhecimento. Todo o conteúdo ao qual um usuário tem acesso está no escopo para recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. Seu locatário do Azure e o locatário do Microsoft 365 devem usar o mesmo locatário do Microsoft Entra ID, e a identidade do autor da chamada deve ser reconhecida por ambos os locatários.

• Você pode usar filtros para definir o escopo da pesquisa por URLs, intervalos de datas, tipos de arquivo e outros metadados.

• As permissões do SharePoint e os rótulos do Purview são respeitados em solicitações de conteúdo.

• O uso é cobrado por meio do Microsoft 365 e de uma licença copilot.

Como qualquer outra fonte de conhecimento, você especifica uma fonte de conhecimento remota do SharePoint em uma base de dados de conhecimento e usa os resultados como dados de aterramento quando um agente ou chatbot chama uma ação de recuperação no momento da consulta.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado.

• SharePoint em um locatário do Microsoft 365 que está dentro do mesmo locatário do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um usuário de um aplicativo cliente.

• A versão prévia mais recente da Azure.Search.Documents biblioteca de clientes para o SDK do .NET.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função, mas você pode usar chaves de API se uma atribuição de função não for viável.

Para desenvolvimento local, o mecanismo de recuperação por meio de agentes usa seu token de acesso para chamar o SharePoint em seu nome. Para obter mais informações sobre como usar um token de acesso pessoal em solicitações, consulte Conectar-se ao Azure AI Search.

Limitações

As limitações a seguir na API de Recuperação do Copilot se aplicam a fontes de conhecimento remotas do SharePoint.

• Não há suporte para conectores Copilot ou conteúdo do OneDrive. O conteúdo é recuperado somente de sites do SharePoint.

• Limite de 200 solicitações por usuário por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• As consultas híbridas só têm suporte para as seguintes extensões de arquivo: .doc, .docx, .pptx, .pdf, .aspx e .one.

• Não há suporte para a recuperação multimodal (conteúdo nãoxtual, incluindo tabelas, imagens e gráficos).

• Máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot sem ordem.

• Expressões de filtro KQL (Linguagem de Consulta de Palavra-Chave) inválidas são ignoradas e a consulta continua a ser executada sem o filtro.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Saber sobre fontes de conhecimento existentes é útil para reutilizar ou nomear novos objetos.

Execute o código a seguir para listar fontes de conhecimento por nome e tipo.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

Você também pode retornar uma única fonte de conhecimento por nome para revisar sua definição de JSON.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

O JSON a seguir é uma resposta de exemplo para uma fonte de conhecimento remota do SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Criar uma fonte de conhecimento

Execute o código a seguir para criar uma fonte de conhecimento remota do SharePoint.

As chaves de API são usadas para a conexão do cliente com o Azure AI Search e o Azure OpenAI. Seu token de acesso é usado pelo Azure AI Search para se conectar ao SharePoint no Microsoft 365 em seu nome. Você só pode recuperar o conteúdo que tem permissão para acessar. Para obter mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Conectar-se ao Azure AI Search.

// Create a remote SharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

var knowledgeSource = new RemoteSharePointKnowledgeSource(name: "my-remote-sharepoint-ks")
{
    Description = "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    RemoteSharePointParameters = new RemoteSharePointKnowledgeSourceParameters()
    {
        FilterExpression = "filetype:docx",
        ResourceMetadata = { "Author", "Title" }
    }
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Propriedades específicas da origem

Você pode passar as propriedades a seguir para criar uma fonte de conhecimento remota do SharePoint.

Exemplos de expressão de filtro

Nem todas as propriedades do SharePoint têm suporte na filterExpression. Para obter uma lista das propriedades com suporte, confira a Referência da API. Veja mais informações sobre as propriedades que podem ser consultadas que podem ser usadas no filtro: propriedades que podem ser consultadas.

Saiba mais sobre filtros KQL na referência de sintaxe.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperação na base de dados de conhecimento fornece a identidade do usuário que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search usa o token de acesso para chamar a Copilot Retrieval API em nome da identidade do usuário. O token de acesso é fornecido no endpoint de recuperação como um cabeçalho HTTP xMsQuerySourceAuthorization.

using Azure;
using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

// Get access token
var credential = new DefaultAzureCredential();
var tokenRequestContext = new Azure.Core.TokenRequestContext(new[] { "https://search.azure.com/.default" });
var accessToken = await credential.GetTokenAsync(tokenRequestContext);
string token = accessToken.Token;

// Create knowledge base retrieval client
var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    credential: new AzureKeyCredential()
);

var spMessages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "user" },
        { "content", @"contoso product planning" }
    }
};

// Create retrieval request
var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in spMessages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest, xMsQuerySourceAuthorization: token);

Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text);

A resposta pode ser semelhante à seguinte:

Contoso's product planning for the NextGen Camera includes a 2019 launch with a core package design and minor modifications for three product versions, featuring Wi-Fi enabled technology and a new mobile app for photo organization and sharing, aiming for 100,000 users within six months [ref_id:0][ref_id:1]. Research and forecasting are central to their planning, with phase two research focusing on feedback from a diverse user group to shape deliverables and milestones [ref_id:0][ref_id:1].

A solicitação de recuperação também usa um filtro KQL (filterExpressionAddOn) se você quiser aplicar restrições no momento da consulta. Se você especificar filterExpressionAddOn a origem do conhecimento e a ação de recuperação da base de dados de conhecimento, os filtros serão AND'd juntos.

As consultas que fazem perguntas sobre o conteúdo em si são mais eficazes do que perguntas sobre onde um arquivo está localizado ou quando foi atualizado pela última vez. Por exemplo, se você perguntar: "Onde está o documento principal do Ignite 2024", você poderá obter "Nenhum conteúdo relevante foi encontrado para sua consulta" porque o conteúdo em si não divulga sua localização. Um filtro nos metadados é uma solução melhor para o local do arquivo ou consultas específicas de data.

Uma pergunta melhor a ser feita é: "Qual é o documento principal do Ignite 2024". A resposta inclui a resposta sintetizada, a atividade de consulta e as contagens de tokens, além da URL e outros metadados.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Excluir uma fonte de conhecimento

Antes de excluir uma fonte de conhecimento, exclua qualquer base de dados de conhecimento que faça referência a ela ou atualize a definição da base de dados de conhecimento para remover a referência. Para fontes de conhecimento que geram um pipeline de índice e indexador, todos os objetos gerados também são excluídos . No entanto, se você usou um índice existente para criar uma fonte de conhecimento, seu índice não será excluído.

Se você tentar excluir uma fonte de conhecimento que está em uso, a ação falhará e retornará uma lista de bases de dados de conhecimento afetadas.

Para excluir uma fonte de conhecimento:

1. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

   using Azure.Search.Documents.Indexes;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
   
   Console.WriteLine("Knowledge Bases:");
   
   await foreach (var kb in knowledgeBases)
   {
       Console.WriteLine($"  - {kb.Name}");
   }
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    Knowledge Bases:
      - earth-knowledge-base
      - hotels-sample-knowledge-base
      - my-demo-knowledge-base
   

2. Obtenha uma definição de base de conhecimento individual para verificar referências de fonte de conhecimento.

   using Azure.Search.Documents.Indexes;
   using System.Text.Json;
   
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   // Specify the knowledge base name to retrieve
   string kbNameToGet = "earth-knowledge-base";
   
   // Get a specific knowledge base definition
   var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
   var kb = knowledgeBaseResponse.Value;
   
   // Serialize to JSON for display
   string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
   Console.WriteLine(json);
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    {
      "Name": "earth-knowledge-base",
      "KnowledgeSources": [
        {
          "Name": "earth-knowledge-source"
        }
      ],
      "Models": [
        {}
      ],
      "RetrievalReasoningEffort": {},
      "OutputMode": {},
      "ETag": "\u00220x8DE278629D782B3\u0022",
      "EncryptionKey": null,
      "Description": null,
      "RetrievalInstructions": null,
      "AnswerInstructions": null
    }
   

3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento para remover a fonte de conhecimento se você tiver várias fontes. Este exemplo mostra a exclusão.

   using Azure.Search.Documents.Indexes;
   var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
   
   await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
   System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
   

4. Exclua a fonte de conhecimento.

   await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
   System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
   

Uma fonte de conhecimento remota do SharePoint usa a API de Recuperação do Copilot para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando resultados ao mecanismo de recuperação por meio de agentes para mesclagem, classificação e formulação de resposta. Não há nenhum índice de pesquisa usado por essa fonte de conhecimento e somente o conteúdo textual é consultado.

No momento da consulta, a fonte de conhecimento remota do SharePoint chama a API de Recuperação do Copilot em nome do usuário, portanto, nenhuma cadeia de conexão é necessária na definição da fonte de conhecimento. Todo o conteúdo ao qual um usuário tem acesso está no escopo para recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. Seu locatário do Azure e o locatário do Microsoft 365 devem usar o mesmo locatário do Microsoft Entra ID, e a identidade do autor da chamada deve ser reconhecida por ambos os locatários.

• Você pode usar filtros para definir o escopo da pesquisa por URLs, intervalos de datas, tipos de arquivo e outros metadados.

• As permissões do SharePoint e os rótulos do Purview são respeitados em solicitações de conteúdo.

• O uso é cobrado por meio do Microsoft 365 e de uma licença copilot.

Como qualquer outra fonte de conhecimento, você especifica uma fonte de conhecimento remota do SharePoint em uma base de dados de conhecimento e usa os resultados como dados de aterramento quando um agente ou chatbot chama uma ação de recuperação no momento da consulta.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado.

• SharePoint em um locatário do Microsoft 365 que está dentro do mesmo locatário do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um usuário de um aplicativo cliente.

• A versão prévia mais recente da azure-search-documents biblioteca de clientes para Python.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função, mas você pode usar chaves de API se uma atribuição de função não for viável.

Para desenvolvimento local, o mecanismo de recuperação por meio de agentes usa seu token de acesso para chamar o SharePoint em seu nome. Para obter mais informações sobre como usar um token de acesso pessoal em solicitações, consulte Conectar-se ao Azure AI Search.

Limitações

As limitações a seguir na API de Recuperação do Copilot se aplicam a fontes de conhecimento remotas do SharePoint.

• Não há suporte para conectores Copilot ou conteúdo do OneDrive. O conteúdo é recuperado somente de sites do SharePoint.

• Limite de 200 solicitações por usuário por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• As consultas híbridas só têm suporte para as seguintes extensões de arquivo: .doc, .docx, .pptx, .pdf, .aspx e .one.

• Não há suporte para a recuperação multimodal (conteúdo nãoxtual, incluindo tabelas, imagens e gráficos).

• Máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot sem ordem.

• Expressões de filtro KQL (Linguagem de Consulta de Palavra-Chave) inválidas são ignoradas e a consulta continua a ser executada sem o filtro.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Saber sobre fontes de conhecimento existentes é útil para reutilizar ou nomear novos objetos.

Execute o código a seguir para listar fontes de conhecimento por nome e tipo.

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Você também pode retornar uma única fonte de conhecimento por nome para revisar sua definição de JSON.

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

O JSON a seguir é uma resposta de exemplo para uma fonte de conhecimento remota do SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Criar uma fonte de conhecimento

Execute o código a seguir para criar uma fonte de conhecimento remota do SharePoint.

As chaves de API são usadas para a conexão do cliente com o Azure AI Search e o Azure OpenAI. Seu token de acesso é usado pelo Azure AI Search para se conectar ao SharePoint no Microsoft 365 em seu nome. Você só pode recuperar o conteúdo que tem permissão para acessar. Para obter mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Conectar-se ao Azure AI Search.

# Create a remote SharePoint knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import RemoteSharePointKnowledgeSource, RemoteSharePointKnowledgeSourceParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = RemoteSharePointKnowledgeSource(
    name = "my-remote-sharepoint-ks",
    description= "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    encryption_key = None,
    remote_share_point_parameters = RemoteSharePointKnowledgeSourceParameters(
        filter_expression = "filetype:docx",
        resource_metadata = ["Author", "Title"],
        container_type_id = None
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Propriedades específicas da origem

Você pode passar as propriedades a seguir para criar uma fonte de conhecimento remota do SharePoint.

Exemplos de expressão de filtro

Nem todas as propriedades do SharePoint têm suporte na filterExpression. Para obter uma lista das propriedades com suporte, confira a Referência da API. Veja mais informações sobre as propriedades que podem ser consultadas que podem ser usadas no filtro: propriedades que podem ser consultadas.

Saiba mais sobre filtros KQL na referência de sintaxe.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperação na base de dados de conhecimento fornece a identidade do usuário que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search usa o token de acesso para chamar a Copilot Retrieval API em nome da identidade do usuário. O token de acesso é fornecido no endpoint de recuperação como um cabeçalho HTTP x-ms-query-source-authorization.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, RemoteSharePointKnowledgeSourceParams

# Get access token
identity_token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://search.azure.com/.default")
token = identity_token_provider()

# Create knowledge base retrieval client
kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

# Create retrieval request
request = KnowledgeBaseRetrievalRequest(
    include_activity = True,
    messages = [
        KnowledgeBaseMessage(role = "user", content = [KnowledgeBaseMessageTextContent(text = "What was covered in the keynote doc for Ignite 2024?")])
    ],
    knowledge_source_params = [
        RemoteSharePointKnowledgeSourceParams(
            knowledge_source_name = "my-remote-sharepoint-ks",
            filter_expression_add_on = "ModifiedBy:\"Adele Vance\"",
            include_references = True,
            include_reference_source_data = True
        )
    ]
)

# Pass access token to retrieve from knowledge base
result = kb_client.retrieve(retrieval_request = request, x_ms_query_source_authorization = token)
print(result.response[0].content[0].text)

A solicitação de recuperação também usa um filtro KQL (filter_expression_add_on) se você quiser aplicar restrições no momento da consulta. Se você especificar filter_expression_add_on a origem do conhecimento e a ação de recuperação da base de dados de conhecimento, os filtros serão AND'd juntos.

As consultas que fazem perguntas sobre o conteúdo em si são mais eficazes do que perguntas sobre onde um arquivo está localizado ou quando foi atualizado pela última vez. Por exemplo, se você perguntar: "Onde está o documento principal do Ignite 2024", você poderá obter "Nenhum conteúdo relevante foi encontrado para sua consulta" porque o conteúdo em si não divulga sua localização. Um filtro nos metadados é uma solução melhor para o local do arquivo ou consultas específicas de data.

Uma pergunta melhor a ser feita é: "Qual é o documento principal do Ignite 2024". A resposta inclui a resposta sintetizada, a atividade de consulta e as contagens de tokens, além da URL e outros metadados.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Excluir uma fonte de conhecimento

Antes de excluir uma fonte de conhecimento, exclua qualquer base de dados de conhecimento que faça referência a ela ou atualize a definição da base de dados de conhecimento para remover a referência. Para fontes de conhecimento que geram um pipeline de índice e indexador, todos os objetos gerados também são excluídos . No entanto, se você usou um índice existente para criar uma fonte de conhecimento, seu índice não será excluído.

Se você tentar excluir uma fonte de conhecimento que está em uso, a ação falhará e retornará uma lista de bases de dados de conhecimento afetadas.

Para excluir uma fonte de conhecimento:

1. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

   # Get knowledge bases
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases"
   params = {"api-version": "2025-11-01-preview", "$select": "name"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. Obtenha uma definição de base de conhecimento individual para verificar referências de fonte de conhecimento.

   # Get a knowledge base definition
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
   params = {"api-version": "2025-11-01-preview"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento para remover a fonte de conhecimento se você tiver várias fontes. Este exemplo mostra a exclusão.

   # Delete a knowledge base
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_base("knowledge_base_name")
   print(f"Knowledge base deleted successfully.")
   

4. Exclua a fonte de conhecimento.

   # Delete a knowledge source
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_source("knowledge_source_name")
   print(f"Knowledge source deleted successfully.")
   

Uma fonte de conhecimento remota do SharePoint usa a API de Recuperação do Copilot para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando resultados ao mecanismo de recuperação por meio de agentes para mesclagem, classificação e formulação de resposta. Não há nenhum índice de pesquisa usado por essa fonte de conhecimento e somente o conteúdo textual é consultado.

No momento da consulta, a fonte de conhecimento remota do SharePoint chama a API de Recuperação do Copilot em nome do usuário, portanto, nenhuma cadeia de conexão é necessária na definição da fonte de conhecimento. Todo o conteúdo ao qual um usuário tem acesso está no escopo para recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. Seu locatário do Azure e o locatário do Microsoft 365 devem usar o mesmo locatário do Microsoft Entra ID, e a identidade do autor da chamada deve ser reconhecida por ambos os locatários.

• Você pode usar filtros para definir o escopo da pesquisa por URLs, intervalos de datas, tipos de arquivo e outros metadados.

• As permissões do SharePoint e os rótulos do Purview são respeitados em solicitações de conteúdo.

• O uso é cobrado por meio do Microsoft 365 e de uma licença copilot.

Como qualquer outra fonte de conhecimento, você especifica uma fonte de conhecimento remota do SharePoint em uma base de dados de conhecimento e usa os resultados como dados de aterramento quando um agente ou chatbot chama uma ação de recuperação no momento da consulta.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado.

• SharePoint em um locatário do Microsoft 365 que está dentro do mesmo locatário do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um usuário de um aplicativo cliente.

• A versão 2025-11-01-preview das APIs REST do Serviço de Pesquisa.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função, mas você pode usar chaves de API se uma atribuição de função não for viável.

Para desenvolvimento local, o mecanismo de recuperação por meio de agentes usa seu token de acesso para chamar o SharePoint em seu nome. Para obter mais informações sobre como usar um token de acesso pessoal em solicitações, consulte Conectar-se ao Azure AI Search.

Limitações

As limitações a seguir na API de Recuperação do Copilot se aplicam a fontes de conhecimento remotas do SharePoint.

• Não há suporte para conectores Copilot ou conteúdo do OneDrive. O conteúdo é recuperado somente de sites do SharePoint.

• Limite de 200 solicitações por usuário por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• As consultas híbridas só têm suporte para as seguintes extensões de arquivo: .doc, .docx, .pptx, .pdf, .aspx e .one.

• Não há suporte para a recuperação multimodal (conteúdo nãoxtual, incluindo tabelas, imagens e gráficos).

• Máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot sem ordem.

• Expressões de filtro KQL (Linguagem de Consulta de Palavra-Chave) inválidas são ignoradas e a consulta continua a ser executada sem o filtro.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Saber sobre fontes de conhecimento existentes é útil para reutilizar ou nomear novos objetos.

Use Fontes de Conhecimento – Obter (API REST) para listar fontes de conhecimento por nome e tipo.

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

Você também pode retornar uma única fonte de conhecimento por nome para revisar sua definição de JSON.

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

O JSON a seguir é uma resposta de exemplo para uma fonte de conhecimento remota do SharePoint.

{
  "name": "my-sharepoint-ks",
  "kind": "remoteSharePoint",
  "description": "A sample remote SharePoint knowledge source",
  "encryptionKey": null,
  "remoteSharePointParameters": {
    "filterExpression": "filetype:docx",
    "containerTypeId": null,
    "resourceMetadata": [
      "Author",
      "Title"
    ]
  }
}

Criar uma fonte de conhecimento

Use fontes de conhecimento – Criar ou atualizar (API REST) para criar uma fonte de conhecimento remota do SharePoint.

As chaves de API são usadas para a conexão do cliente com o Azure AI Search e o Azure OpenAI. Seu token de acesso é usado pelo Azure AI Search para se conectar ao SharePoint no Microsoft 365 em seu nome. Você só pode recuperar o conteúdo que tem permissão para acessar. Para obter mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Conectar-se ao Azure AI Search.

POST {{search-url}}/knowledgesources/my-remote-sharepoint-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-remote-sharepoint-ks",
    "kind": "remoteSharePoint",
    "description": "This knowledge source queries .docx files in a trusted Microsoft 365 tenant.",
    "encryptionKey": null,
    "remoteSharePointParameters": {
        "filterExpression": "filetype:docx",
        "resourceMetadata": [ "Author", "Title" ],
        "containerTypeId": null
    }
}

Propriedades específicas da origem

Você pode passar as propriedades a seguir para criar uma fonte de conhecimento remota do SharePoint.

Exemplos de expressão de filtro

Nem todas as propriedades do SharePoint têm suporte na filterExpression. Para obter uma lista das propriedades com suporte, confira a Referência da API. Veja mais informações sobre as propriedades que podem ser consultadas que podem ser usadas no filtro: propriedades que podem ser consultadas.

Saiba mais sobre filtros KQL na referência de sintaxe.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperação na base de dados de conhecimento fornece a identidade do usuário que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search usa o token de acesso para chamar a Copilot Retrieval API em nome da identidade do usuário. O token de acesso é fornecido no endpoint de recuperação como um cabeçalho HTTP x-ms-query-source-authorization.

Certifique-se de gerar um token de acesso para o locatário que tem seu serviço de pesquisa.

POST {{search-url}}/knowledgebases/remote-sp-kb/retrieve?api-version={{api-version}}
api-key: {{api-key}}
Content-Type: application/json
x-ms-query-source-authorization: {{access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What was covered in the keynote doc for Ignite 2024?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "filterExpressionAddOn": "ModifiedBy:\"Adele Vance\"",
            "knowledgeSourceName": "my-remote-sharepoint-ks",
            "kind": "remoteSharePoint",
            "includeReferences": true,
            "includeReferenceSourceData": true
        }
    ]
}

A solicitação de recuperação também usa um filtro KQL (filterExpressionAddOn) se você quiser aplicar restrições no momento da consulta. Se você especificar filterExpressionAddOn a origem do conhecimento e a ação de recuperação da base de dados de conhecimento, os filtros serão AND'd juntos.

As consultas que fazem perguntas sobre o conteúdo em si são mais eficazes do que perguntas sobre onde um arquivo está localizado ou quando foi atualizado pela última vez. Por exemplo, se você perguntar: "Onde está o documento principal do Ignite 2024", você poderá obter "Nenhum conteúdo relevante foi encontrado para sua consulta" porque o conteúdo em si não divulga sua localização. Um filtro nos metadados é uma solução melhor para o local do arquivo ou consultas específicas de data.

Uma pergunta melhor a ser feita é: "Qual é o documento principal do Ignite 2024". A resposta inclui a resposta sintetizada, a atividade de consulta e as contagens de tokens, além da URL e outros metadados.

{
    "resourceMetadata": {
        "Author": "Nuwan Amarathunga;Nurul Izzati",
        "Title": "Ignite 2024 Keynote Address"
    }
},
"rerankerScore": 2.489522,
"webUrl": "https://contoso-my.sharepoint.com/keynotes/nuamarth_contoso_com/Documents/Keynote-Ignite-2024.docx",
"searchSensitivityLabelInfo": {
        "displayName": "Confidential\\Contoso Extended",
        "sensitivityLabelId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
        "tooltip": "Data is classified and protected. Contoso Full Time Employees (FTE) and non-employees can edit, reply, forward and print. Recipient can unprotect content with the right justification.",
        "priority": 5,
        "color": "#FF8C00",
        "isEncrypted": true
    }

Excluir uma fonte de conhecimento

Antes de excluir uma fonte de conhecimento, exclua qualquer base de dados de conhecimento que faça referência a ela ou atualize a definição da base de dados de conhecimento para remover a referência. Para fontes de conhecimento que geram um pipeline de índice e indexador, todos os objetos gerados também são excluídos . No entanto, se você usou um índice existente para criar uma fonte de conhecimento, seu índice não será excluído.

Se você tentar excluir uma fonte de conhecimento que está em uso, a ação falhará e retornará uma lista de bases de dados de conhecimento afetadas.

Para excluir uma fonte de conhecimento:

1. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

   ### Get knowledge bases
   GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
   api-key: {{api-key}}
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. Obtenha uma definição de base de conhecimento individual para verificar referências de fonte de conhecimento.

   ### Get a knowledge base definition
   GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

   Uma resposta de exemplo pode ser semelhante à seguinte:

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento removendo a fonte de conhecimento se você tiver várias fontes. Este exemplo mostra a exclusão.

   ### Delete a knowledge base
   DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}
   

4. Exclua a fonte de conhecimento.

   ### Delete a knowledge source
   DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
   api-key: {{api-key}}