Erstellen einer SharePoint-Remote-Wissensquelle

Eine SharePoint-Remote-Wissensquelle verwendet die Copilot-Abruf-API , um Textinhalte direkt aus SharePoint in Microsoft 365 abzufragen und Ergebnisse für die Zusammenführung, Rangfolge und Antwortformulierung an das agentische Abrufmodul zurückzugeben. Es gibt keinen Suchindex, der von dieser Wissensquelle verwendet wird, und nur textbezogene Inhalte werden abgefragt.

Zur Abfragezeit ruft die SharePoint-Remote-Wissensquelle die Copilot-Abruf-API im Namen der Benutzeridentität auf, sodass in der Wissensquelldefinition keine Verbindungszeichenfolgen benötigt werden. Alle Inhalte, auf die ein Benutzer Zugriff hat, sind im Umfang des Wissensabrufs enthalten. Wenn Sie Websites einschränken oder die Suche einschränken möchten, legen Sie einen Filterausdruck fest. Ihr Azure-Mandant und der Microsoft 365-Mandant müssen denselben Microsoft Entra ID-Mandanten verwenden, und die Identität des Anrufers muss von beiden Mandanten erkannt werden.

• Sie können Filter verwenden, um die Suche nach URLs, Datumsbereichen, Dateitypen und anderen Metadaten zu beschränken.

• SharePoint-Berechtigungen und Purview-Bezeichner werden in Anfragen für Inhalte berücksichtigt.

• Die Nutzung wird über Microsoft 365 und eine Copilot-Lizenz in Rechnung gestellt.

Wie jede andere Wissensquelle geben Sie eine SharePoint-Remote-Wissensquelle in einer Wissensbasis an und verwenden die Ergebnisse als Erdungsdaten, wenn ein Agent oder Chatbot eine Abrufaktion zur Abfragezeit aufruft.

Voraussetzungen

• Azure AI Search in jeder Region, die agentisches Abrufen ermöglicht. Sie müssen den semantischen Rangierer aktiviert haben.

• SharePoint in einem Microsoft 365-Mandanten, der sich unter demselben Microsoft Entra ID-Mandanten wie Azure befindet.

• Ein persönliches Zugriffstoken für die lokale Entwicklung oder die Identität eines Benutzers aus einer Clientanwendung.

• Die neueste Vorschauversion der Azure.Search.Documents Clientbibliothek für .NET SDK.

• Berechtigung zum Erstellen und Verwenden von Objekten in Azure AI Search. Wir empfehlen den rollenbasierten Zugriff, aber Sie können API-Schlüssel verwenden, wenn eine Rollenzuweisung nicht machbar ist.

Für die lokale Entwicklung verwendet das agentische Abrufmodul Ihr Zugriffstoken, um SharePoint in Ihrem Auftrag aufzurufen. Weitere Informationen zur Verwendung eines persönlichen Zugriffstokens für Anforderungen finden Sie unter Herstellen einer Verbindung mit Azure AI Search.

Einschränkungen

Die folgenden Einschränkungen in der Copilot-Abruf-API gelten für Remote-SharePoint-Wissensquellen.

• Es gibt keine Unterstützung für Copilot-Connectors oder OneDrive-Inhalte. Inhalte werden nur von SharePoint-Websites abgerufen.

• Grenzwert von 200 Anforderungen pro Benutzer pro Stunde.

• Abfragezeichenbeschränkung von 1.500 Zeichen.

• Hybridabfragen werden nur für die folgenden Dateierweiterungen unterstützt: .doc, .docx, .pptx, .pdf, .aspx und .one.

• Der multimodale Abruf (nichttextueller Inhalt, einschließlich Tabellen, Bildern und Diagrammen) wird nicht unterstützt.

• Maximal 25 Ergebnisse aus einer Abfrage.

• Ergebnisse werden von der Copilot-Abruf-API als ungeordnet zurückgegeben.

• Ungültige KQL-Filterausdrücke (Keyword Query Language) werden ignoriert, und die Abfrage wird ohne den Filter weiterhin ausgeführt.

Überprüfen auf vorhandene Wissensquellen

Eine Wissensquelle ist ein wiederverwendbares Objekt der obersten Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.

Führen Sie den folgenden Code aus, um Wissensquellen nach Namen und Typ auflisten.

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

Sie können auch eine einzelne Wissensquelle anhand des Namens zurück, um ihre JSON-Definition zu überprüfen.

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

Der folgende JSON-Code ist eine Beispielantwort für eine SharePoint-Remote-Wissensquelle.

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

Erstellen einer Wissensquelle

Führen Sie den folgenden Code aus, um eine SharePoint-Remote-Wissensquelle zu erstellen.

API-Schlüssel werden für Ihre Clientverbindung mit Azure AI Search und Azure OpenAI verwendet. Ihr Zugriffstoken wird von Azure AI Search verwendet, um eine Verbindung mit SharePoint in Microsoft 365 in Ihrem Auftrag herzustellen. Sie können nur Inhalte abrufen, auf die Sie zugreifen dürfen. Weitere Informationen zum Abrufen eines persönlichen Zugriffstokens und anderer Werte finden Sie unter Herstellen einer Verbindung mit 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.");

Quellspezifische Eigenschaften

Sie können die folgenden Eigenschaften übergeben, um eine SharePoint-Remote-Wissensquelle zu erstellen.

Beispiele für Filterausdrücke

Nicht alle Eigenschaften von SharePoint werden in der filterExpression unterstützt. Eine Liste der unterstützten Eigenschaften finden Sie in der API-Referenz. Hier sind einige weitere Informationen zu abfragefähigen Eigenschaften, die Sie im Filter verwenden können: abfragebare Eigenschaften.

Weitere Informationen zu KQL-Filtern finden Sie in der Syntaxreferenz.

Zuweisen zu einer Wissensbasis

Wenn Sie mit der Wissensquelle zufrieden sind, fahren Sie mit dem nächsten Schritt fort: Geben Sie die Wissensquelle in einer Wissensbasis an.

Nachdem die Knowledge Base konfiguriert wurde, verwenden Sie die Abrufaktion , um die Wissensquelle abzufragen.

Abfragen einer Knowledge Base

Die Abrufen-Aktion auf der Wissensbasis stellt die Benutzeridentität bereit, die den Zugriff auf Inhalte in Microsoft 365 autorisiert.

Azure KI-Suche verwendet das Zugriffstoken, um die Copilot Retrieval-API im Auftrag der Benutzeridentität aufzurufen. Das Zugriffstoken wird im abrufenen Endpunkt als xMsQuerySourceAuthorization HTTP-Header bereitgestellt.

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

Die Antwort könnte wie folgt aussehen:

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

Die Abrufanforderung verwendet auch einen KQL-Filter (filterExpressionAddOn), wenn Sie Einschränkungen zur Abfragezeit anwenden möchten. Wenn Sie filterExpressionAddOn für die Abrufaktion der Wissensquelle und der Wissensdatenbank angeben, werden die Filter zusammengefasst, indem sie mit „und“ verwendet werden.

Abfragen, die Fragen zum Inhalt selbst stellen, sind effektiver als Fragen dazu, wo sich eine Datei befindet oder wann sie zuletzt aktualisiert wurde. Wenn Sie beispielsweise fragen: "Wo ist das Keynote-Dokument für Ignite 2024", erhalten Sie möglicherweise "Für Ihre Abfrage wurde kein relevanter Inhalt gefunden", da der Inhalt selbst seinen Standort nicht offenlegt. Ein Filter nach Metadaten ist eine bessere Lösung für Dateispeicherort oder datumsspezifische Abfragen.

Eine bessere Frage ist: "Was ist das Keynote-Dokument für Ignite 2024". Die Antwort enthält die synthetisierte Antwort, Abfrageaktivität und Tokenanzahl sowie die URL und andere Metadaten.

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

Löschen einer Wissensquelle

Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.

Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.

So löschen Sie eine Wissensquelle:

1. Erhalten Sie eine Liste aller Wissensdatenbanken für Ihren Suchdienst.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie die Wissensbasis , um die Wissensquelle zu entfernen, wenn Sie über mehrere Quellen verfügen. In diesem Beispiel wird das Löschen gezeigt.

   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. Löschen Sie die Wissensquelle.

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

Eine SharePoint-Remote-Wissensquelle verwendet die Copilot-Abruf-API , um Textinhalte direkt aus SharePoint in Microsoft 365 abzufragen und Ergebnisse für die Zusammenführung, Rangfolge und Antwortformulierung an das agentische Abrufmodul zurückzugeben. Es gibt keinen Suchindex, der von dieser Wissensquelle verwendet wird, und nur textbezogene Inhalte werden abgefragt.

Zur Abfragezeit ruft die SharePoint-Remote-Wissensquelle die Copilot-Abruf-API im Namen der Benutzeridentität auf, sodass in der Wissensquelldefinition keine Verbindungszeichenfolgen benötigt werden. Alle Inhalte, auf die ein Benutzer Zugriff hat, sind im Umfang des Wissensabrufs enthalten. Wenn Sie Websites einschränken oder die Suche einschränken möchten, legen Sie einen Filterausdruck fest. Ihr Azure-Mandant und der Microsoft 365-Mandant müssen denselben Microsoft Entra ID-Mandanten verwenden, und die Identität des Anrufers muss von beiden Mandanten erkannt werden.

• Sie können Filter verwenden, um die Suche nach URLs, Datumsbereichen, Dateitypen und anderen Metadaten zu beschränken.

• SharePoint-Berechtigungen und Purview-Bezeichner werden in Anfragen für Inhalte berücksichtigt.

• Die Nutzung wird über Microsoft 365 und eine Copilot-Lizenz in Rechnung gestellt.

Wie jede andere Wissensquelle geben Sie eine SharePoint-Remote-Wissensquelle in einer Wissensbasis an und verwenden die Ergebnisse als Erdungsdaten, wenn ein Agent oder Chatbot eine Abrufaktion zur Abfragezeit aufruft.

Voraussetzungen

• Azure AI Search in jeder Region, die agentisches Abrufen ermöglicht. Sie müssen den semantischen Rangierer aktiviert haben.

• SharePoint in einem Microsoft 365-Mandanten, der sich unter demselben Microsoft Entra ID-Mandanten wie Azure befindet.

• Ein persönliches Zugriffstoken für die lokale Entwicklung oder die Identität eines Benutzers aus einer Clientanwendung.

• Die neueste Vorschauversion der azure-search-documents Clientbibliothek für Python.

• Berechtigung zum Erstellen und Verwenden von Objekten in Azure AI Search. Wir empfehlen den rollenbasierten Zugriff, aber Sie können API-Schlüssel verwenden, wenn eine Rollenzuweisung nicht machbar ist.

Für die lokale Entwicklung verwendet das agentische Abrufmodul Ihr Zugriffstoken, um SharePoint in Ihrem Auftrag aufzurufen. Weitere Informationen zur Verwendung eines persönlichen Zugriffstokens für Anforderungen finden Sie unter Herstellen einer Verbindung mit Azure AI Search.

Einschränkungen

Die folgenden Einschränkungen in der Copilot-Abruf-API gelten für Remote-SharePoint-Wissensquellen.

• Es gibt keine Unterstützung für Copilot-Connectors oder OneDrive-Inhalte. Inhalte werden nur von SharePoint-Websites abgerufen.

• Grenzwert von 200 Anforderungen pro Benutzer pro Stunde.

• Abfragezeichenbeschränkung von 1.500 Zeichen.

• Hybridabfragen werden nur für die folgenden Dateierweiterungen unterstützt: .doc, .docx, .pptx, .pdf, .aspx und .one.

• Der multimodale Abruf (nichttextueller Inhalt, einschließlich Tabellen, Bildern und Diagrammen) wird nicht unterstützt.

• Maximal 25 Ergebnisse aus einer Abfrage.

• Ergebnisse werden von der Copilot-Abruf-API als ungeordnet zurückgegeben.

• Ungültige KQL-Filterausdrücke (Keyword Query Language) werden ignoriert, und die Abfrage wird ohne den Filter weiterhin ausgeführt.

Überprüfen auf vorhandene Wissensquellen

Eine Wissensquelle ist ein wiederverwendbares Objekt der obersten Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.

Führen Sie den folgenden Code aus, um Wissensquellen nach Namen und Typ auflisten.

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

Sie können auch eine einzelne Wissensquelle anhand des Namens zurück, um ihre JSON-Definition zu überprüfen.

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

Der folgende JSON-Code ist eine Beispielantwort für eine SharePoint-Remote-Wissensquelle.

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

Erstellen einer Wissensquelle

Führen Sie den folgenden Code aus, um eine SharePoint-Remote-Wissensquelle zu erstellen.

API-Schlüssel werden für Ihre Clientverbindung mit Azure AI Search und Azure OpenAI verwendet. Ihr Zugriffstoken wird von Azure AI Search verwendet, um eine Verbindung mit SharePoint in Microsoft 365 in Ihrem Auftrag herzustellen. Sie können nur Inhalte abrufen, auf die Sie zugreifen dürfen. Weitere Informationen zum Abrufen eines persönlichen Zugriffstokens und anderer Werte finden Sie unter Herstellen einer Verbindung mit 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.")

Quellspezifische Eigenschaften

Sie können die folgenden Eigenschaften übergeben, um eine SharePoint-Remote-Wissensquelle zu erstellen.

Beispiele für Filterausdrücke

Nicht alle Eigenschaften von SharePoint werden in der filterExpression unterstützt. Eine Liste der unterstützten Eigenschaften finden Sie in der API-Referenz. Hier sind einige weitere Informationen zu abfragefähigen Eigenschaften, die Sie im Filter verwenden können: abfragebare Eigenschaften.

Weitere Informationen zu KQL-Filtern finden Sie in der Syntaxreferenz.

Zuweisen zu einer Wissensbasis

Wenn Sie mit der Wissensquelle zufrieden sind, fahren Sie mit dem nächsten Schritt fort: Geben Sie die Wissensquelle in einer Wissensbasis an.

Nachdem die Knowledge Base konfiguriert wurde, verwenden Sie die Abrufaktion , um die Wissensquelle abzufragen.

Abfragen einer Knowledge Base

Die Abrufen-Aktion auf der Wissensbasis stellt die Benutzeridentität bereit, die den Zugriff auf Inhalte in Microsoft 365 autorisiert.

Azure KI-Suche verwendet das Zugriffstoken, um die Copilot Retrieval-API im Auftrag der Benutzeridentität aufzurufen. Das Zugriffstoken wird im abrufenen Endpunkt als x-ms-query-source-authorization HTTP-Header bereitgestellt.

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)

Die Abrufanforderung verwendet auch einen KQL-Filter (filter_expression_add_on), wenn Sie Einschränkungen zur Abfragezeit anwenden möchten. Wenn Sie filter_expression_add_on für die Abrufaktion der Wissensquelle und der Wissensdatenbank angeben, werden die Filter zusammengefasst, indem sie mit „und“ verwendet werden.

Abfragen, die Fragen zum Inhalt selbst stellen, sind effektiver als Fragen dazu, wo sich eine Datei befindet oder wann sie zuletzt aktualisiert wurde. Wenn Sie beispielsweise fragen: "Wo ist das Keynote-Dokument für Ignite 2024", erhalten Sie möglicherweise "Für Ihre Abfrage wurde kein relevanter Inhalt gefunden", da der Inhalt selbst seinen Standort nicht offenlegt. Ein Filter nach Metadaten ist eine bessere Lösung für Dateispeicherort oder datumsspezifische Abfragen.

Eine bessere Frage ist: "Was ist das Keynote-Dokument für Ignite 2024". Die Antwort enthält die synthetisierte Antwort, Abfrageaktivität und Tokenanzahl sowie die URL und andere Metadaten.

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

Löschen einer Wissensquelle

Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.

Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.

So löschen Sie eine Wissensquelle:

1. Erhalten Sie eine Liste aller Wissensdatenbanken für Ihren Suchdienst.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie die Wissensbasis , um die Wissensquelle zu entfernen, wenn Sie über mehrere Quellen verfügen. In diesem Beispiel wird das Löschen gezeigt.

   # 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. Löschen Sie die Wissensquelle.

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

Eine SharePoint-Remote-Wissensquelle verwendet die Copilot-Abruf-API , um Textinhalte direkt aus SharePoint in Microsoft 365 abzufragen und Ergebnisse für die Zusammenführung, Rangfolge und Antwortformulierung an das agentische Abrufmodul zurückzugeben. Es gibt keinen Suchindex, der von dieser Wissensquelle verwendet wird, und nur textbezogene Inhalte werden abgefragt.

Zur Abfragezeit ruft die SharePoint-Remote-Wissensquelle die Copilot-Abruf-API im Namen der Benutzeridentität auf, sodass in der Wissensquelldefinition keine Verbindungszeichenfolgen benötigt werden. Alle Inhalte, auf die ein Benutzer Zugriff hat, sind im Umfang des Wissensabrufs enthalten. Wenn Sie Websites einschränken oder die Suche einschränken möchten, legen Sie einen Filterausdruck fest. Ihr Azure-Mandant und der Microsoft 365-Mandant müssen denselben Microsoft Entra ID-Mandanten verwenden, und die Identität des Anrufers muss von beiden Mandanten erkannt werden.

• Sie können Filter verwenden, um die Suche nach URLs, Datumsbereichen, Dateitypen und anderen Metadaten zu beschränken.

• SharePoint-Berechtigungen und Purview-Bezeichner werden in Anfragen für Inhalte berücksichtigt.

• Die Nutzung wird über Microsoft 365 und eine Copilot-Lizenz in Rechnung gestellt.

Wie jede andere Wissensquelle geben Sie eine SharePoint-Remote-Wissensquelle in einer Wissensbasis an und verwenden die Ergebnisse als Erdungsdaten, wenn ein Agent oder Chatbot eine Abrufaktion zur Abfragezeit aufruft.

Voraussetzungen

• Azure AI Search in jeder Region, die agentisches Abrufen ermöglicht. Sie müssen den semantischen Rangierer aktiviert haben.

• SharePoint in einem Microsoft 365-Mandanten, der sich unter demselben Microsoft Entra ID-Mandanten wie Azure befindet.

• Ein persönliches Zugriffstoken für die lokale Entwicklung oder die Identität eines Benutzers aus einer Clientanwendung.

• Die Version 2025-11-01-Preview der REST-API des Suchdiensts.

• Berechtigung zum Erstellen und Verwenden von Objekten in Azure AI Search. Wir empfehlen den rollenbasierten Zugriff, aber Sie können API-Schlüssel verwenden, wenn eine Rollenzuweisung nicht machbar ist.

Für die lokale Entwicklung verwendet das agentische Abrufmodul Ihr Zugriffstoken, um SharePoint in Ihrem Auftrag aufzurufen. Weitere Informationen zur Verwendung eines persönlichen Zugriffstokens für Anforderungen finden Sie unter Herstellen einer Verbindung mit Azure AI Search.

Einschränkungen

Die folgenden Einschränkungen in der Copilot-Abruf-API gelten für Remote-SharePoint-Wissensquellen.

• Es gibt keine Unterstützung für Copilot-Connectors oder OneDrive-Inhalte. Inhalte werden nur von SharePoint-Websites abgerufen.

• Grenzwert von 200 Anforderungen pro Benutzer pro Stunde.

• Abfragezeichenbeschränkung von 1.500 Zeichen.

• Hybridabfragen werden nur für die folgenden Dateierweiterungen unterstützt: .doc, .docx, .pptx, .pdf, .aspx und .one.

• Der multimodale Abruf (nichttextueller Inhalt, einschließlich Tabellen, Bildern und Diagrammen) wird nicht unterstützt.

• Maximal 25 Ergebnisse aus einer Abfrage.

• Ergebnisse werden von der Copilot-Abruf-API als ungeordnet zurückgegeben.

• Ungültige KQL-Filterausdrücke (Keyword Query Language) werden ignoriert, und die Abfrage wird ohne den Filter weiterhin ausgeführt.

Überprüfen auf vorhandene Wissensquellen

Eine Wissensquelle ist ein wiederverwendbares Objekt der obersten Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.

Verwenden Sie Wissensquellen – ABRUFEN (REST-API), um Wissensquellen nach Name und Typ auflisten.

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

Sie können auch eine einzelne Wissensquelle anhand des Namens zurück, um ihre JSON-Definition zu überprüfen.

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

Der folgende JSON-Code ist eine Beispielantwort für eine SharePoint-Remote-Wissensquelle.

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

Erstellen einer Wissensquelle

Verwenden Sie Wissensquellen – Erstellen oder Aktualisieren (REST-API), um eine SharePoint-Remote-Wissensquelle zu erstellen.

API-Schlüssel werden für Ihre Clientverbindung mit Azure AI Search und Azure OpenAI verwendet. Ihr Zugriffstoken wird von Azure AI Search verwendet, um eine Verbindung mit SharePoint in Microsoft 365 in Ihrem Auftrag herzustellen. Sie können nur Inhalte abrufen, auf die Sie zugreifen dürfen. Weitere Informationen zum Abrufen eines persönlichen Zugriffstokens und anderer Werte finden Sie unter Herstellen einer Verbindung mit 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
    }
}

Quellspezifische Eigenschaften

Sie können die folgenden Eigenschaften übergeben, um eine SharePoint-Remote-Wissensquelle zu erstellen.

Beispiele für Filterausdrücke

Nicht alle Eigenschaften von SharePoint werden in der filterExpression unterstützt. Eine Liste der unterstützten Eigenschaften finden Sie in der API-Referenz. Hier sind einige weitere Informationen zu abfragefähigen Eigenschaften, die Sie im Filter verwenden können: abfragebare Eigenschaften.

Weitere Informationen zu KQL-Filtern finden Sie in der Syntaxreferenz.

Zuweisen zu einer Wissensbasis

Wenn Sie mit der Wissensquelle zufrieden sind, fahren Sie mit dem nächsten Schritt fort: Geben Sie die Wissensquelle in einer Wissensbasis an.

Nachdem die Knowledge Base konfiguriert wurde, verwenden Sie die Abrufaktion , um die Wissensquelle abzufragen.

Abfragen einer Knowledge Base

Die Abrufen-Aktion auf der Wissensbasis stellt die Benutzeridentität bereit, die den Zugriff auf Inhalte in Microsoft 365 autorisiert.

Azure KI-Suche verwendet das Zugriffstoken, um die Copilot Retrieval-API im Auftrag der Benutzeridentität aufzurufen. Das Zugriffstoken wird im abrufenen Endpunkt als x-ms-query-source-authorization HTTP-Header bereitgestellt.

Stellen Sie sicher, dass Sie ein Zugriffstoken für den Mandanten mit Ihrem Suchdienst generieren.

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

Die Abrufanforderung verwendet auch einen KQL-Filter (filterExpressionAddOn), wenn Sie Einschränkungen zur Abfragezeit anwenden möchten. Wenn Sie filterExpressionAddOn für die Abrufaktion der Wissensquelle und der Wissensdatenbank angeben, werden die Filter zusammengefasst, indem sie mit „und“ verwendet werden.

Abfragen, die Fragen zum Inhalt selbst stellen, sind effektiver als Fragen dazu, wo sich eine Datei befindet oder wann sie zuletzt aktualisiert wurde. Wenn Sie beispielsweise fragen: "Wo ist das Keynote-Dokument für Ignite 2024", erhalten Sie möglicherweise "Für Ihre Abfrage wurde kein relevanter Inhalt gefunden", da der Inhalt selbst seinen Standort nicht offenlegt. Ein Filter nach Metadaten ist eine bessere Lösung für Dateispeicherort oder datumsspezifische Abfragen.

Eine bessere Frage ist: "Was ist das Keynote-Dokument für Ignite 2024". Die Antwort enthält die synthetisierte Antwort, Abfrageaktivität und Tokenanzahl sowie die URL und andere Metadaten.

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

Löschen einer Wissensquelle

Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.

Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.

So löschen Sie eine Wissensquelle:

1. Erhalten Sie eine Liste aller Wissensdatenbanken für Ihren Suchdienst.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

2. Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.

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

   Eine Beispielantwort könnte wie folgt aussehen:

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

3. Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie die Wissensbasis , indem Sie die Wissensquelle entfernen, wenn Sie über mehrere Quellen verfügen. In diesem Beispiel wird das Löschen gezeigt.

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

4. Löschen Sie die Wissensquelle.

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