Een externe SharePoint-kennisbron maken

Een externe SharePoint-kennisbron maakt gebruik van de Copilot Retrieval-API om tekstuele inhoud rechtstreeks vanuit SharePoint in Microsoft 365 op te vragen, en resultaten te retourneren naar de agentische ophaalengine voor het samenvoegen, rangschikten en formuleren van antwoorden. Er is geen zoekindex die door deze kennisbron wordt gebruikt en alleen tekstuele inhoud wordt opgevraagd.

Tijdens de query roept de externe SharePoint-kennisbron de Copilot Retrieval-API aan namens de gebruikersidentiteit, zodat er geen verbindingsreeksen nodig zijn in de definitie van de kennisbron. Alle inhoud waartoe een gebruiker toegang heeft, is binnen het bereik voor het ophalen van kennis. Als u sites of zoekbeperkingen wilt beperken, stelt u een filterexpressie in. Uw Azure-tenant en de Microsoft 365-tenant moeten dezelfde Microsoft Entra ID-tenant gebruiken en de identiteit van de beller moet worden herkend door beide tenants.

• U kunt filters gebruiken om te zoeken op URL's, datumbereiken, bestandstypen en andere metagegevens.

• SharePoint-machtigingen en Purview-labels worden gehonoreerd in aanvragen voor inhoud.

• Gebruik wordt gefactureerd via Microsoft 365 en een Copilot-licentie.

Net als elke andere kennisbron geeft u een externe SharePoint-kennisbron op in een knowledge base en gebruikt u de resultaten als grondgegevens wanneer een agent of chatbot een actie voor ophalen aanroept tijdens het uitvoeren van query's.

Vereiste voorwaarden

• Azure AI Search in elke regio die agentisch ophalen biedt. U moet semantische rangschikking hebben ingeschakeld.

• SharePoint in een Microsoft 365-tenant die zich onder dezelfde Microsoft Entra ID-tenant bevindt als Azure.

• Een persoonlijk toegangstoken voor lokale ontwikkeling of de identiteit van een gebruiker vanuit een clienttoepassing.

• De nieuwste preview-versie van de Azure.Search.Documents clientbibliotheek voor de .NET SDK.

• Machtiging voor het maken en gebruiken van objecten in Azure AI Search. We raden op rollen gebaseerde toegang aan, maar u kunt API-sleutels gebruiken als een roltoewijzing niet haalbaar is.

Voor lokale ontwikkeling gebruikt de agentische ophaalengine uw toegangstoken om SharePoint namens u aan te roepen. Zie Verbinding maken met Azure AI Search voor meer informatie over het gebruik van een persoonlijk toegangstoken voor aanvragen.

Beperkingen

De volgende beperkingen in de Copilot Retrieval-API zijn van toepassing op externe SharePoint-kennisbronnen.

• Er is geen ondersteuning voor Copilot-connectors of OneDrive-inhoud. Inhoud wordt alleen opgehaald van SharePoint-sites.

• Limiet van 200 aanvragen per gebruiker per uur.

• Querytekenlimiet van 1500 tekens.

• Hybride query's worden alleen ondersteund voor de volgende bestandsextensies: .doc, .docx, .pptx, .pdf, .aspx en .one.

• Multimodaal ophalen (niet-tekstuele inhoud, inclusief tabellen, afbeeldingen en grafieken) wordt niet ondersteund.

• Maximaal 25 resultaten van een query.

• Resultaten worden door de Copilot Retrieval-API in een willekeurige volgorde geretourneerd.

• Ongeldige KQL-filterexpressies (Keyword Query Language) worden genegeerd en de query wordt nog steeds uitgevoerd zonder het filter.

Controleren op bestaande kennisbronnen

Een kennisbron is een herbruikbaar object op het hoogste niveau. Kennis over bestaande kennisbronnen is handig voor het opnieuw gebruiken of benoemen van nieuwe objecten.

Voer de volgende code uit om kennisbronnen op naam en type weer te geven.

// 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}");
}

U kunt ook één kennisbron op naam retourneren om de JSON-definitie ervan te controleren.

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));

De volgende JSON is een voorbeeld van een antwoord voor een externe SharePoint-kennisbron.

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

Een kennisbron maken

Voer de volgende code uit om een externe SharePoint-kennisbron te maken.

API-sleutels worden gebruikt voor uw clientverbinding met Azure AI Search en Azure OpenAI. Uw toegangstoken wordt door Azure AI Search gebruikt om namens u verbinding te maken met SharePoint in Microsoft 365. U kunt alleen inhoud ophalen waartoe u toegang hebt. Zie Verbinding maken met Azure AI Search voor meer informatie over het ophalen van een persoonlijk toegangstoken en andere waarden.

// 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.");

Bronspecifieke eigenschappen

U kunt de volgende eigenschappen doorgeven om een externe SharePoint-kennisbron te maken.

Voorbeelden van filterexpressies

Niet alle SharePoint-eigenschappen worden ondersteund in de filterExpression. Zie de API-verwijzing voor een lijst met ondersteunde eigenschappen. Hier vindt u meer informatie over doorzoekbare eigenschappen die u kunt gebruiken in het filter: doorzoekbare eigenschappen.

Meer informatie over KQL-filters in de syntaxisverwijzing.

Toewijzen aan een kennisbank

Als u tevreden bent met de kennisbron, gaat u verder met de volgende stap: geef de kennisbron op in een knowledge base.

Nadat de knowledge base is geconfigureerd, gebruikt u de actie ophalen om een query uit te voeren op de kennisbron.

Een query uitvoeren op een Knowledge Base

De actie ophalen in de Knowledge Base biedt de gebruikersidentiteit die toegang tot inhoud in Microsoft 365 autoriseert.

Azure AI Search gebruikt het toegangstoken om de Copilot Retrieval-API aan te roepen namens de gebruikersidentiteit. Het toegangstoken wordt in het eindpunt verstrekt als een xMsQuerySourceAuthorization HTTP-header.

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);

Het antwoord kan er als volgt uitzien:

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

De ophaalaanvraag maakt ook gebruik van een KQL-filter (filterExpressionAddOn) als u beperkingen wilt toepassen tijdens de query. Als u filterExpressionAddOn opgeeft voor zowel de kennisbron als de Knowledge Base-ophaalmethode, worden de filters gecombineerd met een AND-bewerking.

Query's die vragen stellen over de inhoud zelf zijn effectiever dan vragen over waar een bestand zich bevindt of wanneer het voor het laatst is bijgewerkt. Als u bijvoorbeeld 'Waar is het keynote-document voor Ignite 2024' wordt gevraagd, krijgt u mogelijk 'Er is geen relevante inhoud gevonden voor uw query', omdat de inhoud zelf de locatie niet openbaar maakt. Een filter op metagegevens is een betere oplossing voor bestandslocatie of datumspecifieke query's.

Een betere vraag is: 'Wat is het keynote-document voor Ignite 2024'. Het antwoord bevat het gesynthetiseerde antwoord, het aantal queryactiviteit en token, plus de URL en andere metagegevens.

{
    "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
    }

Een kennisbron verwijderen

Voordat u een kennisbron kunt verwijderen, moet u een knowledge base verwijderen die ernaar verwijst of de knowledge base-definitie bijwerken om de verwijzing te verwijderen. Voor kennisbronnen die een index- en indexeerpijplijn genereren, worden ook alle gegenereerde objecten verwijderd. Als u echter een bestaande index hebt gebruikt om een kennisbron te maken, wordt uw index niet verwijderd.

Als u probeert een kennisbron te verwijderen die in gebruik is, mislukt de actie en wordt een lijst met betrokken knowledge bases geretourneerd.

Een kennisbron verwijderen:

1. Haal een lijst op met alle knowledge bases op uw zoekservice.

   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}");
   }
   

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

   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);
   

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

3. Verwijder de knowledge base of werk de knowledge base bij om de kennisbron te verwijderen als u meerdere bronnen hebt. In dit voorbeeld ziet u de verwijdering.

   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. Verwijder de kennisbron.

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

Een externe SharePoint-kennisbron maakt gebruik van de Copilot Retrieval-API om tekstuele inhoud rechtstreeks vanuit SharePoint in Microsoft 365 op te vragen, en resultaten te retourneren naar de agentische ophaalengine voor het samenvoegen, rangschikten en formuleren van antwoorden. Er is geen zoekindex die door deze kennisbron wordt gebruikt en alleen tekstuele inhoud wordt opgevraagd.

Tijdens de query roept de externe SharePoint-kennisbron de Copilot Retrieval-API aan namens de gebruikersidentiteit, zodat er geen verbindingsreeksen nodig zijn in de definitie van de kennisbron. Alle inhoud waartoe een gebruiker toegang heeft, is binnen het bereik voor het ophalen van kennis. Als u sites of zoekbeperkingen wilt beperken, stelt u een filterexpressie in. Uw Azure-tenant en de Microsoft 365-tenant moeten dezelfde Microsoft Entra ID-tenant gebruiken en de identiteit van de beller moet worden herkend door beide tenants.

• U kunt filters gebruiken om te zoeken op URL's, datumbereiken, bestandstypen en andere metagegevens.

• SharePoint-machtigingen en Purview-labels worden gehonoreerd in aanvragen voor inhoud.

• Gebruik wordt gefactureerd via Microsoft 365 en een Copilot-licentie.

Net als elke andere kennisbron geeft u een externe SharePoint-kennisbron op in een knowledge base en gebruikt u de resultaten als grondgegevens wanneer een agent of chatbot een actie voor ophalen aanroept tijdens het uitvoeren van query's.

Vereiste voorwaarden

• Azure AI Search in elke regio die agentisch ophalen biedt. U moet semantische rangschikking hebben ingeschakeld.

• SharePoint in een Microsoft 365-tenant die zich onder dezelfde Microsoft Entra ID-tenant bevindt als Azure.

• Een persoonlijk toegangstoken voor lokale ontwikkeling of de identiteit van een gebruiker vanuit een clienttoepassing.

• De nieuwste preview-versie van de azure-search-documents clientbibliotheek voor Python.

• Machtiging voor het maken en gebruiken van objecten in Azure AI Search. We raden op rollen gebaseerde toegang aan, maar u kunt API-sleutels gebruiken als een roltoewijzing niet haalbaar is.

Voor lokale ontwikkeling gebruikt de agentische ophaalengine uw toegangstoken om SharePoint namens u aan te roepen. Zie Verbinding maken met Azure AI Search voor meer informatie over het gebruik van een persoonlijk toegangstoken voor aanvragen.

Beperkingen

De volgende beperkingen in de Copilot Retrieval-API zijn van toepassing op externe SharePoint-kennisbronnen.

• Er is geen ondersteuning voor Copilot-connectors of OneDrive-inhoud. Inhoud wordt alleen opgehaald van SharePoint-sites.

• Limiet van 200 aanvragen per gebruiker per uur.

• Querytekenlimiet van 1500 tekens.

• Hybride query's worden alleen ondersteund voor de volgende bestandsextensies: .doc, .docx, .pptx, .pdf, .aspx en .one.

• Multimodaal ophalen (niet-tekstuele inhoud, inclusief tabellen, afbeeldingen en grafieken) wordt niet ondersteund.

• Maximaal 25 resultaten van een query.

• Resultaten worden door de Copilot Retrieval-API in een willekeurige volgorde geretourneerd.

• Ongeldige KQL-filterexpressies (Keyword Query Language) worden genegeerd en de query wordt nog steeds uitgevoerd zonder het filter.

Controleren op bestaande kennisbronnen

Een kennisbron is een herbruikbaar object op het hoogste niveau. Kennis over bestaande kennisbronnen is handig voor het opnieuw gebruiken of benoemen van nieuwe objecten.

Voer de volgende code uit om kennisbronnen op naam en type weer te geven.

# 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))

U kunt ook één kennisbron op naam retourneren om de JSON-definitie ervan te controleren.

# 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))

De volgende JSON is een voorbeeld van een antwoord voor een externe SharePoint-kennisbron.

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

Een kennisbron maken

Voer de volgende code uit om een externe SharePoint-kennisbron te maken.

API-sleutels worden gebruikt voor uw clientverbinding met Azure AI Search en Azure OpenAI. Uw toegangstoken wordt door Azure AI Search gebruikt om namens u verbinding te maken met SharePoint in Microsoft 365. U kunt alleen inhoud ophalen waartoe u toegang hebt. Zie Verbinding maken met Azure AI Search voor meer informatie over het ophalen van een persoonlijk toegangstoken en andere waarden.

# 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.")

Bronspecifieke eigenschappen

U kunt de volgende eigenschappen doorgeven om een externe SharePoint-kennisbron te maken.

Voorbeelden van filterexpressies

Niet alle SharePoint-eigenschappen worden ondersteund in de filterExpression. Zie de API-verwijzing voor een lijst met ondersteunde eigenschappen. Hier vindt u meer informatie over doorzoekbare eigenschappen die u kunt gebruiken in het filter: doorzoekbare eigenschappen.

Meer informatie over KQL-filters in de syntaxisverwijzing.

Toewijzen aan een kennisbank

Als u tevreden bent met de kennisbron, gaat u verder met de volgende stap: geef de kennisbron op in een knowledge base.

Nadat de knowledge base is geconfigureerd, gebruikt u de actie ophalen om een query uit te voeren op de kennisbron.

Een query uitvoeren op een Knowledge Base

De actie ophalen in de Knowledge Base biedt de gebruikersidentiteit die toegang tot inhoud in Microsoft 365 autoriseert.

Azure AI Search gebruikt het toegangstoken om de Copilot Retrieval-API aan te roepen namens de gebruikersidentiteit. Het toegangstoken wordt in het eindpunt verstrekt als een x-ms-query-source-authorization HTTP-header.

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)

De ophaalaanvraag maakt ook gebruik van een KQL-filter (filter_expression_add_on) als u beperkingen wilt toepassen tijdens de query. Als u filter_expression_add_on opgeeft voor zowel de kennisbron als de Knowledge Base-ophaalmethode, worden de filters gecombineerd met een AND-bewerking.

Query's die vragen stellen over de inhoud zelf zijn effectiever dan vragen over waar een bestand zich bevindt of wanneer het voor het laatst is bijgewerkt. Als u bijvoorbeeld 'Waar is het keynote-document voor Ignite 2024' wordt gevraagd, krijgt u mogelijk 'Er is geen relevante inhoud gevonden voor uw query', omdat de inhoud zelf de locatie niet openbaar maakt. Een filter op metagegevens is een betere oplossing voor bestandslocatie of datumspecifieke query's.

Een betere vraag is: 'Wat is het keynote-document voor Ignite 2024'. Het antwoord bevat het gesynthetiseerde antwoord, het aantal queryactiviteit en token, plus de URL en andere metagegevens.

{
    "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
    }

Een kennisbron verwijderen

Voordat u een kennisbron kunt verwijderen, moet u een knowledge base verwijderen die ernaar verwijst of de knowledge base-definitie bijwerken om de verwijzing te verwijderen. Voor kennisbronnen die een index- en indexeerpijplijn genereren, worden ook alle gegenereerde objecten verwijderd. Als u echter een bestaande index hebt gebruikt om een kennisbron te maken, wordt uw index niet verwijderd.

Als u probeert een kennisbron te verwijderen die in gebruik is, mislukt de actie en wordt een lijst met betrokken knowledge bases geretourneerd.

Een kennisbron verwijderen:

1. Haal een lijst op met alle knowledge bases op uw zoekservice.

   # 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))
   

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

   # 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))
   

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

3. Verwijder de knowledge base of werk de knowledge base bij om de kennisbron te verwijderen als u meerdere bronnen hebt. In dit voorbeeld ziet u de verwijdering.

   # 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. Verwijder de kennisbron.

   # 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.")
   

Een externe SharePoint-kennisbron maakt gebruik van de Copilot Retrieval-API om tekstuele inhoud rechtstreeks vanuit SharePoint in Microsoft 365 op te vragen, en resultaten te retourneren naar de agentische ophaalengine voor het samenvoegen, rangschikten en formuleren van antwoorden. Er is geen zoekindex die door deze kennisbron wordt gebruikt en alleen tekstuele inhoud wordt opgevraagd.

Tijdens de query roept de externe SharePoint-kennisbron de Copilot Retrieval-API aan namens de gebruikersidentiteit, zodat er geen verbindingsreeksen nodig zijn in de definitie van de kennisbron. Alle inhoud waartoe een gebruiker toegang heeft, is binnen het bereik voor het ophalen van kennis. Als u sites of zoekbeperkingen wilt beperken, stelt u een filterexpressie in. Uw Azure-tenant en de Microsoft 365-tenant moeten dezelfde Microsoft Entra ID-tenant gebruiken en de identiteit van de beller moet worden herkend door beide tenants.

• U kunt filters gebruiken om te zoeken op URL's, datumbereiken, bestandstypen en andere metagegevens.

• SharePoint-machtigingen en Purview-labels worden gehonoreerd in aanvragen voor inhoud.

• Gebruik wordt gefactureerd via Microsoft 365 en een Copilot-licentie.

Net als elke andere kennisbron geeft u een externe SharePoint-kennisbron op in een knowledge base en gebruikt u de resultaten als grondgegevens wanneer een agent of chatbot een actie voor ophalen aanroept tijdens het uitvoeren van query's.

Vereiste voorwaarden

• Azure AI Search in elke regio die agentisch ophalen biedt. U moet semantische rangschikking hebben ingeschakeld.

• SharePoint in een Microsoft 365-tenant die zich onder dezelfde Microsoft Entra ID-tenant bevindt als Azure.

• Een persoonlijk toegangstoken voor lokale ontwikkeling of de identiteit van een gebruiker vanuit een clienttoepassing.

• De 2025-11-01-preview versie van de REST API's van de Search Service.

• Machtiging voor het maken en gebruiken van objecten in Azure AI Search. We raden op rollen gebaseerde toegang aan, maar u kunt API-sleutels gebruiken als een roltoewijzing niet haalbaar is.

Voor lokale ontwikkeling gebruikt de agentische ophaalengine uw toegangstoken om SharePoint namens u aan te roepen. Zie Verbinding maken met Azure AI Search voor meer informatie over het gebruik van een persoonlijk toegangstoken voor aanvragen.

Beperkingen

De volgende beperkingen in de Copilot Retrieval-API zijn van toepassing op externe SharePoint-kennisbronnen.

• Er is geen ondersteuning voor Copilot-connectors of OneDrive-inhoud. Inhoud wordt alleen opgehaald van SharePoint-sites.

• Limiet van 200 aanvragen per gebruiker per uur.

• Querytekenlimiet van 1500 tekens.

• Hybride query's worden alleen ondersteund voor de volgende bestandsextensies: .doc, .docx, .pptx, .pdf, .aspx en .one.

• Multimodaal ophalen (niet-tekstuele inhoud, inclusief tabellen, afbeeldingen en grafieken) wordt niet ondersteund.

• Maximaal 25 resultaten van een query.

• Resultaten worden door de Copilot Retrieval-API in een willekeurige volgorde geretourneerd.

• Ongeldige KQL-filterexpressies (Keyword Query Language) worden genegeerd en de query wordt nog steeds uitgevoerd zonder het filter.

Controleren op bestaande kennisbronnen

Een kennisbron is een herbruikbaar object op het hoogste niveau. Kennis over bestaande kennisbronnen is handig voor het opnieuw gebruiken of benoemen van nieuwe objecten.

Gebruik Knowledge Sources - Get (REST API) om kennisbronnen op naam en type weer te geven.

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

U kunt ook één kennisbron op naam retourneren om de JSON-definitie ervan te controleren.

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

De volgende JSON is een voorbeeld van een antwoord voor een externe SharePoint-kennisbron.

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

Een kennisbron maken

Kennisbronnen gebruiken: een externe SharePoint-kennisbron maken of bijwerken (REST API ).

API-sleutels worden gebruikt voor uw clientverbinding met Azure AI Search en Azure OpenAI. Uw toegangstoken wordt door Azure AI Search gebruikt om namens u verbinding te maken met SharePoint in Microsoft 365. U kunt alleen inhoud ophalen waartoe u toegang hebt. Zie Verbinding maken met Azure AI Search voor meer informatie over het ophalen van een persoonlijk toegangstoken en andere waarden.

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
    }
}

Bronspecifieke eigenschappen

U kunt de volgende eigenschappen doorgeven om een externe SharePoint-kennisbron te maken.

Voorbeelden van filterexpressies

Niet alle SharePoint-eigenschappen worden ondersteund in de filterExpression. Zie de API-verwijzing voor een lijst met ondersteunde eigenschappen. Hier vindt u meer informatie over doorzoekbare eigenschappen die u kunt gebruiken in het filter: doorzoekbare eigenschappen.

Meer informatie over KQL-filters in de syntaxisverwijzing.

Toewijzen aan een kennisbank

Als u tevreden bent met de kennisbron, gaat u verder met de volgende stap: geef de kennisbron op in een knowledge base.

Nadat de knowledge base is geconfigureerd, gebruikt u de actie ophalen om een query uit te voeren op de kennisbron.

Een query uitvoeren op een Knowledge Base

De actie ophalen in de Knowledge Base biedt de gebruikersidentiteit die toegang tot inhoud in Microsoft 365 autoriseert.

Azure AI Search gebruikt het toegangstoken om de Copilot Retrieval-API aan te roepen namens de gebruikersidentiteit. Het toegangstoken wordt in het eindpunt verstrekt als een x-ms-query-source-authorization HTTP-header.

Zorg ervoor dat u een toegangstoken genereert voor de tenant met uw zoekservice.

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
        }
    ]
}

De ophaalaanvraag maakt ook gebruik van een KQL-filter (filterExpressionAddOn) als u beperkingen wilt toepassen tijdens de query. Als u filterExpressionAddOn opgeeft voor zowel de kennisbron als de Knowledge Base-ophaalmethode, worden de filters gecombineerd met een AND-bewerking.

Query's die vragen stellen over de inhoud zelf zijn effectiever dan vragen over waar een bestand zich bevindt of wanneer het voor het laatst is bijgewerkt. Als u bijvoorbeeld 'Waar is het keynote-document voor Ignite 2024' wordt gevraagd, krijgt u mogelijk 'Er is geen relevante inhoud gevonden voor uw query', omdat de inhoud zelf de locatie niet openbaar maakt. Een filter op metagegevens is een betere oplossing voor bestandslocatie of datumspecifieke query's.

Een betere vraag is: 'Wat is het keynote-document voor Ignite 2024'. Het antwoord bevat het gesynthetiseerde antwoord, het aantal queryactiviteit en token, plus de URL en andere metagegevens.

{
    "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
    }

Een kennisbron verwijderen

Voordat u een kennisbron kunt verwijderen, moet u een knowledge base verwijderen die ernaar verwijst of de knowledge base-definitie bijwerken om de verwijzing te verwijderen. Voor kennisbronnen die een index- en indexeerpijplijn genereren, worden ook alle gegenereerde objecten verwijderd. Als u echter een bestaande index hebt gebruikt om een kennisbron te maken, wordt uw index niet verwijderd.

Als u probeert een kennisbron te verwijderen die in gebruik is, mislukt de actie en wordt een lijst met betrokken knowledge bases geretourneerd.

Een kennisbron verwijderen:

1. Haal een lijst op met alle knowledge bases op uw zoekservice.

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

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

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

   Een voorbeeld van een antwoord kan er als volgt uitzien:

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

3. Verwijder de knowledge base of werk de knowledge base bij door de kennisbron te verwijderen als u meerdere bronnen hebt. In dit voorbeeld ziet u de verwijdering.

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

4. Verwijder de kennisbron.

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