Crie uma fonte de conhecimento remota do SharePoint

Uma fonte remota de conhecimento SharePoint utiliza a API Copilot Retrieval para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando os resultados ao motor de recuperação agential para fusão, classificação e formulação de respostas. Não existe um índice de pesquisa utilizado por esta fonte de conhecimento, e apenas 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 da identidade do utilizador, pelo que não são necessárias strings de ligação na definição da fonte de conhecimento. Todo o conteúdo ao qual um utilizador tem acesso está dentro do âmbito da recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. O seu tenant Azure e o tenant Microsoft 365 devem usar o mesmo tenant Microsoft Entra ID, e a identidade do chamador deve ser reconhecida por ambos os inquilinos.

• Pode usar filtros para definir a pesquisa por URLs, intervalos de datas, tipos de ficheiros e outros metadados.

• Permissões do SharePoint e etiquetas Purview são respeitadas em pedidos de conteúdo.

• A utilização é faturada através do Microsoft 365 e de uma licença Copilot.

Como em qualquer outra fonte de conhecimento, especifica uma fonte remota de SharePoint numa base de conhecimento e usa os resultados como dados de base 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 que forneça recuperação agentiva. Deve ter o ranker semântico ativado.

• SharePoint numa instância do Microsoft 365 que está na mesma instância do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um utilizador a partir de uma aplicação cliente.

• A versão de pré-visualização mais recente da Azure.Search.Documents biblioteca cliente para o SDK .NET.

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

Para desenvolvimento local, o motor de recuperação baseado em agentes usa o seu token de acesso para aceder ao SharePoint em seu nome. Para mais informações sobre o uso de um token de acesso pessoal em pedidos, consulte Conectar ao Azure AI Search.

Limitações

As seguintes limitações na API Copilot Retrieval aplicam-se às fontes remotas de conhecimento do SharePoint.

• Não há suporte para conectores Copilot nem para conteúdos do OneDrive. O conteúdo é retirado apenas de sites do SharePoint.

• Limite de 200 pedidos por utilizador por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• Consultas híbridas são suportadas apenas para as seguintes extensões de ficheiro: .doc, .docx, .pptx, .pdf, .aspx e .one.

• A recuperação multimodal (conteúdo não textual, incluindo tabelas, imagens e gráficos) não é suportada.

• Um máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot de forma não ordenada.

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

Verifique se há fontes de conhecimento existentes

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

Execute o seguinte código para listar as 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 pelo nome para revisar sua definição 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 seguinte é um exemplo de resposta para uma fonte remota de conhecimento 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 seguinte para criar uma fonte remota de conhecimento do SharePoint.

As chaves API são usadas para a ligação do cliente ao Azure AI Search e ao Azure OpenAI. O seu token de acesso é utilizado pelo Azure AI Search para se ligar ao SharePoint no Microsoft 365 em seu nome. Só pode recuperar conteúdos a que tem permissão para aceder. Para mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Connect to 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 fonte

Pode passar as seguintes propriedades para criar uma fonte remota de conhecimento do SharePoint.

Exemplos de expressões de filtros

Nem todas as propriedades do SharePoint são suportadas no arquivo filterExpression. Para uma lista de propriedades suportadas, consulte a referência da API. Aqui tens mais informações sobre propriedades consultáveis que podes usar no filtro: propriedades consultáveis.

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

Atribuir a uma base de conhecimento

Se estiver satisfeito com a fonte de conhecimento, continue para o passo seguinte: especifique a fonte de conhecimento numa base de conhecimento.

Depois de a base de conhecimento estar configurada, use a ação de recuperar para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperar na base de conhecimento fornece a identidade do utilizador que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search utiliza o token de acesso para chamar a API de Recuperação do Copilot em nome da identidade do utilizador. O token de acesso é fornecido no endpoint de obtenção como um xMsQuerySourceAuthorization cabeçalho HTTP.

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 a 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].

O pedido de recuperação também utiliza um filtro KQL (filterExpressionAddOn) se quiser aplicar restrições no momento da consulta. Se especificares filterExpressionAddOn tanto na fonte de conhecimento como na ação de recuperação da base de conhecimento, os filtros são AND juntos.

Consultas que fazem perguntas sobre o próprio conteúdo são mais eficazes do que perguntas sobre onde um ficheiro está localizado ou quando foi atualizado pela última vez. Por exemplo, se perguntar, "Onde está o documento principal do Ignite 2024", pode receber "Não foi encontrado conteúdo relevante para a sua consulta" porque o próprio conteúdo não revela a sua localização. Um filtro de metadados é uma solução melhor para localização de ficheiros ou consultas específicas por data.

Uma pergunta melhor a fazer é: "Qual é o documento principal do Ignite 2024?" A resposta inclui a resposta sintetizada, a atividade da consulta e a contagem de tokens, além do 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 poder eliminar uma fonte de conhecimento, deve eliminar qualquer base de conhecimento que a faça referência ou atualizar a definição da base 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 eliminados. No entanto, se usou um índice existente para criar uma fonte de conhecimento, o seu índice não é eliminado.

Se tentar eliminar uma fonte de conhecimento que está em uso, a ação falha e devolve uma lista das bases de conhecimento afetadas.

Para eliminar uma fonte de conhecimento:

1. Obtenha uma lista de todas as bases de conhecimento do 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}");
   }
   

   Um exemplo de resposta pode ter a seguinte aparência:

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

2. Obtenha uma definição individual da base de conhecimento para verificar referências de fontes 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);
   

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apaga a base de conhecimento ou atualiza a base de conhecimento para remover a fonte de conhecimento se tiveres 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 remota de conhecimento SharePoint utiliza a API Copilot Retrieval para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando os resultados ao motor de recuperação agential para fusão, classificação e formulação de respostas. Não existe um índice de pesquisa utilizado por esta fonte de conhecimento, e apenas 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 da identidade do utilizador, pelo que não são necessárias strings de ligação na definição da fonte de conhecimento. Todo o conteúdo ao qual um utilizador tem acesso está dentro do âmbito da recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. O seu tenant Azure e o tenant Microsoft 365 devem usar o mesmo tenant Microsoft Entra ID, e a identidade do chamador deve ser reconhecida por ambos os inquilinos.

• Pode usar filtros para definir a pesquisa por URLs, intervalos de datas, tipos de ficheiros e outros metadados.

• Permissões do SharePoint e etiquetas Purview são respeitadas em pedidos de conteúdo.

• A utilização é faturada através do Microsoft 365 e de uma licença Copilot.

Como em qualquer outra fonte de conhecimento, especifica uma fonte remota de SharePoint numa base de conhecimento e usa os resultados como dados de base 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 que forneça recuperação agentiva. Deve ter o ranker semântico ativado.

• SharePoint numa instância do Microsoft 365 que está na mesma instância do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um utilizador a partir de uma aplicação cliente.

• A versão mais recente de pré-visualização da azure-search-documents biblioteca cliente para Python.

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

Para desenvolvimento local, o motor de recuperação baseado em agentes usa o seu token de acesso para aceder ao SharePoint em seu nome. Para mais informações sobre o uso de um token de acesso pessoal em pedidos, consulte Conectar ao Azure AI Search.

Limitações

As seguintes limitações na API Copilot Retrieval aplicam-se às fontes remotas de conhecimento do SharePoint.

• Não há suporte para conectores Copilot nem para conteúdos do OneDrive. O conteúdo é retirado apenas de sites do SharePoint.

• Limite de 200 pedidos por utilizador por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• Consultas híbridas são suportadas apenas para as seguintes extensões de ficheiro: .doc, .docx, .pptx, .pdf, .aspx e .one.

• A recuperação multimodal (conteúdo não textual, incluindo tabelas, imagens e gráficos) não é suportada.

• Um máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot de forma não ordenada.

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

Verifique se há fontes de conhecimento existentes

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

Execute o seguinte código para listar as 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 pelo nome para revisar sua definição 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 seguinte é um exemplo de resposta para uma fonte remota de conhecimento 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 seguinte para criar uma fonte remota de conhecimento do SharePoint.

As chaves API são usadas para a ligação do cliente ao Azure AI Search e ao Azure OpenAI. O seu token de acesso é utilizado pelo Azure AI Search para se ligar ao SharePoint no Microsoft 365 em seu nome. Só pode recuperar conteúdos a que tem permissão para aceder. Para mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Connect to 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 fonte

Pode passar as seguintes propriedades para criar uma fonte remota de conhecimento do SharePoint.

Exemplos de expressões de filtros

Nem todas as propriedades do SharePoint são suportadas no arquivo filterExpression. Para uma lista de propriedades suportadas, consulte a referência da API. Aqui tens mais informações sobre propriedades consultáveis que podes usar no filtro: propriedades consultáveis.

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

Atribuir a uma base de conhecimento

Se estiver satisfeito com a fonte de conhecimento, continue para o passo seguinte: especifique a fonte de conhecimento numa base de conhecimento.

Depois de a base de conhecimento estar configurada, use a ação de recuperar para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperar na base de conhecimento fornece a identidade do utilizador que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search utiliza o token de acesso para chamar a API de Recuperação do Copilot em nome da identidade do utilizador. O token de acesso é fornecido no endpoint de obtenção como um x-ms-query-source-authorization cabeçalho HTTP.

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)

O pedido de recuperação também utiliza um filtro KQL (filter_expression_add_on) se quiser aplicar restrições no momento da consulta. Se especificares filter_expression_add_on tanto na fonte de conhecimento como na ação de recuperação da base de conhecimento, os filtros são AND juntos.

Consultas que fazem perguntas sobre o próprio conteúdo são mais eficazes do que perguntas sobre onde um ficheiro está localizado ou quando foi atualizado pela última vez. Por exemplo, se perguntar, "Onde está o documento principal do Ignite 2024", pode receber "Não foi encontrado conteúdo relevante para a sua consulta" porque o próprio conteúdo não revela a sua localização. Um filtro de metadados é uma solução melhor para localização de ficheiros ou consultas específicas por data.

Uma pergunta melhor a fazer é: "Qual é o documento principal do Ignite 2024?" A resposta inclui a resposta sintetizada, a atividade da consulta e a contagem de tokens, além do 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 poder eliminar uma fonte de conhecimento, deve eliminar qualquer base de conhecimento que a faça referência ou atualizar a definição da base 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 eliminados. No entanto, se usou um índice existente para criar uma fonte de conhecimento, o seu índice não é eliminado.

Se tentar eliminar uma fonte de conhecimento que está em uso, a ação falha e devolve uma lista das bases de conhecimento afetadas.

Para eliminar uma fonte de conhecimento:

1. Obtenha uma lista de todas as bases de conhecimento do 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))
   

   Um exemplo de resposta pode ter a seguinte aparência:

    {
        "@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 individual da base de conhecimento para verificar referências de fontes 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))
   

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apaga a base de conhecimento ou atualiza a base de conhecimento para remover a fonte de conhecimento se tiveres 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 remota de conhecimento SharePoint utiliza a API Copilot Retrieval para consultar conteúdo textual diretamente do SharePoint no Microsoft 365, retornando os resultados ao motor de recuperação agential para fusão, classificação e formulação de respostas. Não existe um índice de pesquisa utilizado por esta fonte de conhecimento, e apenas 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 da identidade do utilizador, pelo que não são necessárias strings de ligação na definição da fonte de conhecimento. Todo o conteúdo ao qual um utilizador tem acesso está dentro do âmbito da recuperação de conhecimento. Para limitar sites ou restringir a pesquisa, defina uma expressão de filtro. O seu tenant Azure e o tenant Microsoft 365 devem usar o mesmo tenant Microsoft Entra ID, e a identidade do chamador deve ser reconhecida por ambos os inquilinos.

• Pode usar filtros para definir a pesquisa por URLs, intervalos de datas, tipos de ficheiros e outros metadados.

• Permissões do SharePoint e etiquetas Purview são respeitadas em pedidos de conteúdo.

• A utilização é faturada através do Microsoft 365 e de uma licença Copilot.

Como em qualquer outra fonte de conhecimento, especifica uma fonte remota de SharePoint numa base de conhecimento e usa os resultados como dados de base 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 que forneça recuperação agentiva. Deve ter o ranker semântico ativado.

• SharePoint numa instância do Microsoft 365 que está na mesma instância do Microsoft Entra ID que o Azure.

• Um token de acesso pessoal para desenvolvimento local ou a identidade de um utilizador a partir de uma aplicação cliente.

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

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

Para desenvolvimento local, o motor de recuperação baseado em agentes usa o seu token de acesso para aceder ao SharePoint em seu nome. Para mais informações sobre o uso de um token de acesso pessoal em pedidos, consulte Conectar ao Azure AI Search.

Limitações

As seguintes limitações na API Copilot Retrieval aplicam-se às fontes remotas de conhecimento do SharePoint.

• Não há suporte para conectores Copilot nem para conteúdos do OneDrive. O conteúdo é retirado apenas de sites do SharePoint.

• Limite de 200 pedidos por utilizador por hora.

• Limite de caracteres de consulta de 1.500 caracteres.

• Consultas híbridas são suportadas apenas para as seguintes extensões de ficheiro: .doc, .docx, .pptx, .pdf, .aspx e .one.

• A recuperação multimodal (conteúdo não textual, incluindo tabelas, imagens e gráficos) não é suportada.

• Um máximo de 25 resultados de uma consulta.

• Os resultados são devolvidos pela API de Recuperação do Copilot de forma não ordenada.

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

Verifique se há fontes de conhecimento existentes

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

Usar 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 pelo nome para revisar sua definição 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 seguinte é um exemplo de resposta para uma fonte remota de conhecimento 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 remota de conhecimento do SharePoint.

As chaves API são usadas para a ligação do cliente ao Azure AI Search e ao Azure OpenAI. O seu token de acesso é utilizado pelo Azure AI Search para se ligar ao SharePoint no Microsoft 365 em seu nome. Só pode recuperar conteúdos a que tem permissão para aceder. Para mais informações sobre como obter um token de acesso pessoal e outros valores, consulte Connect to 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 fonte

Pode passar as seguintes propriedades para criar uma fonte remota de conhecimento do SharePoint.

Exemplos de expressões de filtros

Nem todas as propriedades do SharePoint são suportadas no arquivo filterExpression. Para uma lista de propriedades suportadas, consulte a referência da API. Aqui tens mais informações sobre propriedades consultáveis que podes usar no filtro: propriedades consultáveis.

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

Atribuir a uma base de conhecimento

Se estiver satisfeito com a fonte de conhecimento, continue para o passo seguinte: especifique a fonte de conhecimento numa base de conhecimento.

Depois de a base de conhecimento estar configurada, use a ação de recuperar para consultar a fonte de conhecimento.

Consultar uma base de dados de conhecimento

A ação de recuperar na base de conhecimento fornece a identidade do utilizador que autoriza o acesso ao conteúdo no Microsoft 365.

O Azure AI Search utiliza o token de acesso para chamar a API de Recuperação do Copilot em nome da identidade do utilizador. O token de acesso é fornecido no endpoint de obtenção como um x-ms-query-source-authorization cabeçalho HTTP.

Certifique-se de que gera um token de acesso para o locatário que tem o 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
        }
    ]
}

O pedido de recuperação também utiliza um filtro KQL (filterExpressionAddOn) se quiser aplicar restrições no momento da consulta. Se especificares filterExpressionAddOn tanto na fonte de conhecimento como na ação de recuperação da base de conhecimento, os filtros são AND juntos.

Consultas que fazem perguntas sobre o próprio conteúdo são mais eficazes do que perguntas sobre onde um ficheiro está localizado ou quando foi atualizado pela última vez. Por exemplo, se perguntar, "Onde está o documento principal do Ignite 2024", pode receber "Não foi encontrado conteúdo relevante para a sua consulta" porque o próprio conteúdo não revela a sua localização. Um filtro de metadados é uma solução melhor para localização de ficheiros ou consultas específicas por data.

Uma pergunta melhor a fazer é: "Qual é o documento principal do Ignite 2024?" A resposta inclui a resposta sintetizada, a atividade da consulta e a contagem de tokens, além do 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 poder eliminar uma fonte de conhecimento, deve eliminar qualquer base de conhecimento que a faça referência ou atualizar a definição da base 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 eliminados. No entanto, se usou um índice existente para criar uma fonte de conhecimento, o seu índice não é eliminado.

Se tentar eliminar uma fonte de conhecimento que está em uso, a ação falha e devolve uma lista das bases de conhecimento afetadas.

Para eliminar uma fonte de conhecimento:

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

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

   Um exemplo de resposta pode ter a seguinte aparência:

    {
        "@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 individual da base de conhecimento para verificar referências de fontes de conhecimento.

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

   Um exemplo de resposta pode ter a seguinte aparência:

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

3. Ou apaga a base de conhecimento ou atualiza a base de conhecimento removendo a fonte de conhecimento se tiveres múltiplas 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}}