Créer une source de connaissances SharePoint distante

Une source de connaissances SharePoint distante utilise l’API De récupération Copilot pour interroger du contenu textuel directement à partir de SharePoint dans Microsoft 365, renvoyant les résultats au moteur de récupération agentique pour la fusion, le classement et la formulation de réponse. Il n’existe aucun index de recherche utilisé par cette source de connaissances, et seul le contenu textuel est interrogé.

Au moment de la requête, la source de connaissances distante SharePoint appelle l’API de Récupération Copilot au nom de l’identité de l’utilisateur. Par conséquent, aucune chaîne de connexion n’est nécessaire dans la définition de la source de connaissances. ** Tout le contenu auquel un utilisateur a accès est disponible pour la récupération des connaissances. Pour limiter les sites ou limiter la recherche, définissez une expression de filtre. Votre locataire Azure et le locataire Microsoft 365 doivent utiliser le même locataire Microsoft Entra ID, et l’identité de l’appelant doit être reconnue par les deux locataires.

• Vous pouvez utiliser des filtres pour étendre la recherche par URL, plages de dates, types de fichiers et autres métadonnées.

• Les autorisations SharePoint et les étiquettes Purview sont respectées dans les demandes de contenu.

• L’utilisation est facturée via Microsoft 365 et une licence Copilot.

Comme n’importe quelle autre source de connaissances, vous spécifiez une source de connaissances SharePoint distante dans une base de connaissances et utilisez les résultats comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique.

• SharePoint dans un locataire Microsoft 365 qui est sous le même locataire Microsoft Entra ID qu’Azure.

• Jeton d’accès personnel pour le développement local ou l’identité d’un utilisateur à partir d’une application cliente.

• Dernière version préliminaire de la Azure.Search.Documents bibliothèque cliente pour le Kit de développement logiciel (SDK) .NET.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle, mais vous pouvez utiliser des clés API si une attribution de rôle n’est pas réalisable.

Pour le développement local, le moteur de récupération agentique utilise votre jeton d’accès pour appeler SharePoint en votre nom. Pour plus d’informations sur l’utilisation d’un jeton d’accès personnel sur les demandes, consultez Se connecter à Recherche AZURE AI.

Limites

Les limitations suivantes de l’API de récupération Copilot s’appliquent aux sources de connaissances SharePoint distantes.

• Il n’existe aucune prise en charge des connecteurs Copilot ou du contenu OneDrive. Le contenu est récupéré à partir de sites SharePoint uniquement.

• Limite de 200 requêtes par utilisateur par heure.

• Limite des caractères de requête de 1 500 caractères.

• Les requêtes hybrides sont uniquement prises en charge pour les extensions de fichier suivantes : .doc, .docx, .pptx, .pdf, .aspx et .one.

• La récupération modale (contenu nontextuel, y compris les tables, les images et les graphiques) n’est pas prise en charge.

• Maximum de 25 résultats d’une requête.

• Les résultats sont renvoyés par l'API de récupération Copilot dans un ordre non défini.

• Les expressions de filtre KQL (Keyword Query Language) non valides sont ignorées et la requête continue à s’exécuter sans le filtre.

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Exécutez le code suivant pour répertorier les sources de connaissances par nom et par type.

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

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition 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));

Le code JSON suivant est un exemple de réponse pour une source de connaissances SharePoint distante.

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

Créer une source de connaissances

Exécutez le code suivant pour créer une source de connaissances SharePoint distante.

Les clés API sont utilisées pour votre connexion cliente à Azure AI Search et Azure OpenAI. Votre jeton d’accès est utilisé par Azure AI Search pour vous connecter à SharePoint dans Microsoft 365 en votre nom. Vous pouvez uniquement récupérer du contenu auquel vous êtes autorisé à accéder. Pour plus d’informations sur l’obtention d’un jeton d’accès personnel et d’autres valeurs, consultez Se connecter à Recherche AZURE AI.

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

Propriétés spécifiques à la source

Vous pouvez transmettre les propriétés suivantes pour créer une source de connaissances SharePoint distante.

Exemples d’expressions de filtre

Toutes les propriétés SharePoint ne sont pas prises en charge dans le filterExpression. Pour obtenir la liste des propriétés prises en charge, consultez les informations de référence sur l’API. Voici quelques informations supplémentaires sur les propriétés interrogeables que vous pouvez utiliser dans le filtre : propriétés interrogeables.

En savoir plus sur les filtres KQL dans la référence de syntaxe.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Interroger une base de connaissances

L’action de récupération sur la base de connaissances fournit l’identité de l’utilisateur qui autorise l’accès au contenu dans Microsoft 365.

Azure AI Search utilise le jeton d’accès pour appeler l’API de récupération Copilot au nom de l'utilisateur. Le jeton d’accès est fourni dans le point de terminaison de récupération en tant qu’en-tête HTTP xMsQuerySourceAuthorization.

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

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

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

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

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

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

La réponse peut ressembler à ce qui suit :

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

La demande de récupération prend également un filtre KQL (filterExpressionAddOn) si vous souhaitez appliquer des contraintes au moment de la requête. Si vous spécifiez filterExpressionAddOn à la fois pour la source de connaissances et l’action de récupération de la base de connaissances, les filtres sont combinés avec l’opérateur ET.

Les requêtes qui posent des questions sur le contenu lui-même sont plus efficaces que les questions relatives à l’emplacement d’un fichier ou à la dernière mise à jour. Par exemple, si vous demandez : « Où est la documentation principale pour Ignite 2024 », vous pouvez obtenir « Aucun contenu pertinent n’a été trouvé pour votre requête », car le contenu lui-même ne divulgue pas son emplacement. Un filtre sur les métadonnées est une meilleure solution pour l’emplacement du fichier ou les requêtes spécifiques à la date.

Une meilleure question à poser est : « Qu’est-ce que la documentation keynote pour Ignite 2024 ». La réponse inclut la réponse synthétisée, l’activité de requête et le nombre de jetons, ainsi que l’URL et d’autres métadonnées.

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

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

3. Supprimez la base de connaissances ou mettez à jour la base de connaissances pour supprimer la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

   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. Supprimer la source de connaissances.

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

Une source de connaissances SharePoint distante utilise l’API De récupération Copilot pour interroger du contenu textuel directement à partir de SharePoint dans Microsoft 365, renvoyant les résultats au moteur de récupération agentique pour la fusion, le classement et la formulation de réponse. Il n’existe aucun index de recherche utilisé par cette source de connaissances, et seul le contenu textuel est interrogé.

Au moment de la requête, la source de connaissances distante SharePoint appelle l’API de Récupération Copilot au nom de l’identité de l’utilisateur. Par conséquent, aucune chaîne de connexion n’est nécessaire dans la définition de la source de connaissances. ** Tout le contenu auquel un utilisateur a accès est disponible pour la récupération des connaissances. Pour limiter les sites ou limiter la recherche, définissez une expression de filtre. Votre locataire Azure et le locataire Microsoft 365 doivent utiliser le même locataire Microsoft Entra ID, et l’identité de l’appelant doit être reconnue par les deux locataires.

• Vous pouvez utiliser des filtres pour étendre la recherche par URL, plages de dates, types de fichiers et autres métadonnées.

• Les autorisations SharePoint et les étiquettes Purview sont respectées dans les demandes de contenu.

• L’utilisation est facturée via Microsoft 365 et une licence Copilot.

Comme n’importe quelle autre source de connaissances, vous spécifiez une source de connaissances SharePoint distante dans une base de connaissances et utilisez les résultats comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique.

• SharePoint dans un locataire Microsoft 365 qui est sous le même locataire Microsoft Entra ID qu’Azure.

• Jeton d’accès personnel pour le développement local ou l’identité d’un utilisateur à partir d’une application cliente.

• Dernière version préliminaire de la azure-search-documents bibliothèque cliente pour Python.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle, mais vous pouvez utiliser des clés API si une attribution de rôle n’est pas réalisable.

Pour le développement local, le moteur de récupération agentique utilise votre jeton d’accès pour appeler SharePoint en votre nom. Pour plus d’informations sur l’utilisation d’un jeton d’accès personnel sur les demandes, consultez Se connecter à Recherche AZURE AI.

Limites

Les limitations suivantes de l’API de récupération Copilot s’appliquent aux sources de connaissances SharePoint distantes.

• Il n’existe aucune prise en charge des connecteurs Copilot ou du contenu OneDrive. Le contenu est récupéré à partir de sites SharePoint uniquement.

• Limite de 200 requêtes par utilisateur par heure.

• Limite des caractères de requête de 1 500 caractères.

• Les requêtes hybrides sont uniquement prises en charge pour les extensions de fichier suivantes : .doc, .docx, .pptx, .pdf, .aspx et .one.

• La récupération modale (contenu nontextuel, y compris les tables, les images et les graphiques) n’est pas prise en charge.

• Maximum de 25 résultats d’une requête.

• Les résultats sont renvoyés par l'API de récupération Copilot dans un ordre non défini.

• Les expressions de filtre KQL (Keyword Query Language) non valides sont ignorées et la requête continue à s’exécuter sans le filtre.

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Exécutez le code suivant pour répertorier les sources de connaissances par nom et par type.

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

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition 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))

Le code JSON suivant est un exemple de réponse pour une source de connaissances SharePoint distante.

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

Créer une source de connaissances

Exécutez le code suivant pour créer une source de connaissances SharePoint distante.

Les clés API sont utilisées pour votre connexion cliente à Azure AI Search et Azure OpenAI. Votre jeton d’accès est utilisé par Azure AI Search pour vous connecter à SharePoint dans Microsoft 365 en votre nom. Vous pouvez uniquement récupérer du contenu auquel vous êtes autorisé à accéder. Pour plus d’informations sur l’obtention d’un jeton d’accès personnel et d’autres valeurs, consultez Se connecter à Recherche AZURE AI.

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

Propriétés spécifiques à la source

Vous pouvez transmettre les propriétés suivantes pour créer une source de connaissances SharePoint distante.

Exemples d’expressions de filtre

Toutes les propriétés SharePoint ne sont pas prises en charge dans le filterExpression. Pour obtenir la liste des propriétés prises en charge, consultez les informations de référence sur l’API. Voici quelques informations supplémentaires sur les propriétés interrogeables que vous pouvez utiliser dans le filtre : propriétés interrogeables.

En savoir plus sur les filtres KQL dans la référence de syntaxe.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Interroger une base de connaissances

L’action de récupération sur la base de connaissances fournit l’identité de l’utilisateur qui autorise l’accès au contenu dans Microsoft 365.

Azure AI Search utilise le jeton d’accès pour appeler l’API de récupération Copilot au nom de l'utilisateur. Le jeton d’accès est fourni dans le point de terminaison de récupération en tant qu’en-tête HTTP x-ms-query-source-authorization.

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

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

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

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

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

La demande de récupération prend également un filtre KQL (filter_expression_add_on) si vous souhaitez appliquer des contraintes au moment de la requête. Si vous spécifiez filter_expression_add_on à la fois pour la source de connaissances et l’action de récupération de la base de connaissances, les filtres sont combinés avec l’opérateur ET.

Les requêtes qui posent des questions sur le contenu lui-même sont plus efficaces que les questions relatives à l’emplacement d’un fichier ou à la dernière mise à jour. Par exemple, si vous demandez : « Où est la documentation principale pour Ignite 2024 », vous pouvez obtenir « Aucun contenu pertinent n’a été trouvé pour votre requête », car le contenu lui-même ne divulgue pas son emplacement. Un filtre sur les métadonnées est une meilleure solution pour l’emplacement du fichier ou les requêtes spécifiques à la date.

Une meilleure question à poser est : « Qu’est-ce que la documentation keynote pour Ignite 2024 ». La réponse inclut la réponse synthétisée, l’activité de requête et le nombre de jetons, ainsi que l’URL et d’autres métadonnées.

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

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

3. Supprimez la base de connaissances ou mettez à jour la base de connaissances pour supprimer la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

   # 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. Supprimer la source de connaissances.

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

Une source de connaissances SharePoint distante utilise l’API De récupération Copilot pour interroger du contenu textuel directement à partir de SharePoint dans Microsoft 365, renvoyant les résultats au moteur de récupération agentique pour la fusion, le classement et la formulation de réponse. Il n’existe aucun index de recherche utilisé par cette source de connaissances, et seul le contenu textuel est interrogé.

Au moment de la requête, la source de connaissances distante SharePoint appelle l’API de Récupération Copilot au nom de l’identité de l’utilisateur. Par conséquent, aucune chaîne de connexion n’est nécessaire dans la définition de la source de connaissances. ** Tout le contenu auquel un utilisateur a accès est disponible pour la récupération des connaissances. Pour limiter les sites ou limiter la recherche, définissez une expression de filtre. Votre locataire Azure et le locataire Microsoft 365 doivent utiliser le même locataire Microsoft Entra ID, et l’identité de l’appelant doit être reconnue par les deux locataires.

• Vous pouvez utiliser des filtres pour étendre la recherche par URL, plages de dates, types de fichiers et autres métadonnées.

• Les autorisations SharePoint et les étiquettes Purview sont respectées dans les demandes de contenu.

• L’utilisation est facturée via Microsoft 365 et une licence Copilot.

Comme n’importe quelle autre source de connaissances, vous spécifiez une source de connaissances SharePoint distante dans une base de connaissances et utilisez les résultats comme données de base lorsqu’un agent ou un chatbot appelle une action de récupération au moment de la requête.

Prerequisites

• Recherche Azure AI dans n’importe quelle région qui propose une récupération par agents. Vous devez activer le ranker sémantique.

• SharePoint dans un locataire Microsoft 365 qui est sous le même locataire Microsoft Entra ID qu’Azure.

• Jeton d’accès personnel pour le développement local ou l’identité d’un utilisateur à partir d’une application cliente.

• La version 2025-11-01-preview des API REST du service de recherche.

• Autorisation de créer et d’utiliser des objets sur Recherche IA Azure. Nous vous recommandons d’accéder en fonction du rôle, mais vous pouvez utiliser des clés API si une attribution de rôle n’est pas réalisable.

Pour le développement local, le moteur de récupération agentique utilise votre jeton d’accès pour appeler SharePoint en votre nom. Pour plus d’informations sur l’utilisation d’un jeton d’accès personnel sur les demandes, consultez Se connecter à Recherche AZURE AI.

Limites

Les limitations suivantes de l’API de récupération Copilot s’appliquent aux sources de connaissances SharePoint distantes.

• Il n’existe aucune prise en charge des connecteurs Copilot ou du contenu OneDrive. Le contenu est récupéré à partir de sites SharePoint uniquement.

• Limite de 200 requêtes par utilisateur par heure.

• Limite des caractères de requête de 1 500 caractères.

• Les requêtes hybrides sont uniquement prises en charge pour les extensions de fichier suivantes : .doc, .docx, .pptx, .pdf, .aspx et .one.

• La récupération modale (contenu nontextuel, y compris les tables, les images et les graphiques) n’est pas prise en charge.

• Maximum de 25 résultats d’une requête.

• Les résultats sont renvoyés par l'API de récupération Copilot dans un ordre non défini.

• Les expressions de filtre KQL (Keyword Query Language) non valides sont ignorées et la requête continue à s’exécuter sans le filtre.

Rechercher des sources de connaissances existantes

Une source de connaissances constitue un objet réutilisable de niveau supérieur. Connaître les sources de connaissances existantes est utile pour réutiliser ou nommer de nouveaux objets.

Utilisez les sources de connaissances - Obtenir (API REST) pour répertorier les sources de connaissances par nom et par type.

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

Vous pouvez également renvoyer une seule source de connaissances par nom pour passer en revue sa définition JSON.

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

Le code JSON suivant est un exemple de réponse pour une source de connaissances SharePoint distante.

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

Créer une source de connaissances

Utilisez des sources de connaissances : créer ou mettre à jour (API REST) pour créer une source de connaissances SharePoint distante.

Les clés API sont utilisées pour votre connexion cliente à Azure AI Search et Azure OpenAI. Votre jeton d’accès est utilisé par Azure AI Search pour vous connecter à SharePoint dans Microsoft 365 en votre nom. Vous pouvez uniquement récupérer du contenu auquel vous êtes autorisé à accéder. Pour plus d’informations sur l’obtention d’un jeton d’accès personnel et d’autres valeurs, consultez Se connecter à Recherche AZURE AI.

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

Propriétés spécifiques à la source

Vous pouvez transmettre les propriétés suivantes pour créer une source de connaissances SharePoint distante.

Exemples d’expressions de filtre

Toutes les propriétés SharePoint ne sont pas prises en charge dans le filterExpression. Pour obtenir la liste des propriétés prises en charge, consultez les informations de référence sur l’API. Voici quelques informations supplémentaires sur les propriétés interrogeables que vous pouvez utiliser dans le filtre : propriétés interrogeables.

En savoir plus sur les filtres KQL dans la référence de syntaxe.

Attribuer à une base de connaissances

Si vous êtes satisfait de la source de connaissances, passez à l’étape suivante : spécifiez la source de connaissances dans une base de connaissances.

Une fois la base de connaissances configurée, utilisez l’action de récupération pour interroger la source de connaissances.

Interroger une base de connaissances

L’action de récupération sur la base de connaissances fournit l’identité de l’utilisateur qui autorise l’accès au contenu dans Microsoft 365.

Azure AI Search utilise le jeton d’accès pour appeler l’API de récupération Copilot au nom de l'utilisateur. Le jeton d’accès est fourni dans le point de terminaison de récupération en tant qu’en-tête HTTP x-ms-query-source-authorization.

Assurez-vous de générer un jeton d’accès pour le locataire disposant de votre service de recherche.

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

La demande de récupération prend également un filtre KQL (filterExpressionAddOn) si vous souhaitez appliquer des contraintes au moment de la requête. Si vous spécifiez filterExpressionAddOn à la fois pour la source de connaissances et l’action de récupération de la base de connaissances, les filtres sont combinés avec l’opérateur ET.

Les requêtes qui posent des questions sur le contenu lui-même sont plus efficaces que les questions relatives à l’emplacement d’un fichier ou à la dernière mise à jour. Par exemple, si vous demandez : « Où est la documentation principale pour Ignite 2024 », vous pouvez obtenir « Aucun contenu pertinent n’a été trouvé pour votre requête », car le contenu lui-même ne divulgue pas son emplacement. Un filtre sur les métadonnées est une meilleure solution pour l’emplacement du fichier ou les requêtes spécifiques à la date.

Une meilleure question à poser est : « Qu’est-ce que la documentation keynote pour Ignite 2024 ». La réponse inclut la réponse synthétisée, l’activité de requête et le nombre de jetons, ainsi que l’URL et d’autres métadonnées.

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

Supprimer une source de connaissances

Avant de pouvoir supprimer une source de connaissances, vous devez supprimer toute base de connaissances qui la référence ou mettre à jour la définition de la base de connaissances pour supprimer la référence. Pour les sources de connaissances qui génèrent un pipeline d’index et d’indexeur, tous les objets générés sont également supprimés . Toutefois, si vous avez utilisé un index existant pour créer une source de connaissances, votre index n’est pas supprimé.

Si vous essayez de supprimer une source de connaissances en cours d’utilisation, l’action échoue et retourne une liste de bases de connaissances affectées.

Pour supprimer une source de connaissances :

1. Obtenez la liste de toutes les bases de connaissances sur votre service de recherche.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

2. Obtenez une définition de base de connaissances individuelle pour rechercher des références à la source de connaissances.

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

   Un exemple de réponse peut ressembler à ce qui suit :

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

3. Supprimez la base de connaissances ou mettez à jour la base de connaissances en supprimant la source de connaissances si vous avez plusieurs sources. Cet exemple montre la suppression.

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

4. Supprimer la source de connaissances.

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