Creare un'origine di conoscenza SharePoint remota

• Pacchetto di anteprima Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

• Pacchetto di anteprima azure-search-documents più recente: pip install --pre azure-search-documents

• Versione 2025-11-01-preview delle API REST del servizio di ricerca.

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Eseguire il codice seguente per elencare le origini delle informazioni in base al nome e al tipo.

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

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

Console.WriteLine("Knowledge Sources:");

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione 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));

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Eseguire il codice seguente per elencare le origini delle informazioni in base al nome e al tipo.

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

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

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione 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))

Una fonte di informazioni è un oggetto riutilizzabile di livello superiore. Conoscere le origini conoscenze esistenti è utile per riutilizzare o denominare nuovi oggetti.

Usare Le origini delle informazioni - Ottenere (API REST) per elencare le origini delle informazioni in base al nome e al tipo.

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

È anche possibile restituire una singola fonte di informazioni in base al nome per esaminarne la definizione JSON.

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

Eseguire il seguente codice per creare un'origine di conoscenza remota di SharePoint.

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

Esegui il codice seguente per creare una fonte di conoscenza SharePoint remota.

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

Usare Knowledge Sources - Creare o Aggiornare (API REST) per creare un'origine remota di conoscenza SharePoint.

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

È possibile passare un oggetto FilterExpressionAddOn nella richiesta di recupero dati KnowledgeSourceParams per applicare un filtro KQL in fase di query. Se si specifica nella richiesta di recupero e nella definizione dell'origine della knowledge base, i filtri sono AND.If you specify FilterExpressionAddOn on the retrieve request and a FilterExpression on the knowledge source definition, the filters are AND'd together.

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
retrievalRequest.Messages.Add(
    new KnowledgeBaseMessage(
        content: new[] {
            new KnowledgeBaseMessageTextContent("contoso product planning")
        }
    ) { Role = "user" }
);
retrievalRequest.KnowledgeSourceParams.Add(
    new RemoteSharePointKnowledgeSourceParams("my-remote-sharepoint-ks")
    {
        FilterExpressionAddOn = "filetype:docx"
    }
);

var result = await kbClient.RetrieveAsync(
    retrievalRequest, xMsQuerySourceAuthorization: token
);

È possibile passare un oggetto filter_expression_add_on nella richiesta di recupero dati knowledge_source_params per applicare un filtro KQL in fase di query. Se si specifica nella richiesta di recupero e nella definizione dell'origine della knowledge base, i filtri sono AND.If you specify filter_expression_add_on on the retrieve request and a filter_expression on the knowledge source definition, the filters are AND'd together.

from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent,
    KnowledgeBaseRetrievalRequest,
    RemoteSharePointKnowledgeSourceParams,
)

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role="user",
            content=[
                KnowledgeBaseMessageTextContent(
                    text="contoso product planning"
                )
            ],
        )
    ],
    knowledge_source_params=[
        RemoteSharePointKnowledgeSourceParams(
            knowledge_source_name="my-remote-sharepoint-ks",
            filter_expression_add_on="filetype:docx",
        )
    ],
)

result = kb_client.retrieve(
    retrieval_request=request,
    x_ms_query_source_authorization=token,
)

È possibile passare un oggetto filterExpressionAddOn nella richiesta di recupero dati knowledgeSourceParams per applicare un filtro KQL in fase di query. Se si specifica nella richiesta di recupero e nella definizione dell'origine della knowledge base, i filtri sono AND.If you specify filterExpressionAddOn on the retrieve request and a filterExpression on the knowledge source definition, the filters are AND'd together.

POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{accessToken}}
Content-Type: application/json
x-ms-query-source-authorization: {{user-access-token}}

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "contoso product planning" }
            ]
        }
    ],
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "my-remote-sharepoint-ks",
            "kind": "remoteSharePoint",
            "filterExpressionAddOn": "filetype:docx"
        }
    ]
}

Le query che chiedono informazioni sul contenuto stesso sono più efficaci rispetto alle domande relative alla posizione di un file o all'ultimo aggiornamento. Ad esempio, "Where is the keynote doc for Ignite 2024" potrebbe non restituire risultati perché il contenuto stesso non divulga la sua posizione. Un FilterExpression oggetto sui metadati è un approccio migliore per la posizione del file o le query specifiche della data.

Le query che chiedono informazioni sul contenuto stesso sono più efficaci rispetto alle domande relative alla posizione di un file o all'ultimo aggiornamento. Ad esempio, "Where is the keynote doc for Ignite 2024" potrebbe non restituire risultati perché il contenuto stesso non divulga la sua posizione. Un filter_expression oggetto sui metadati è un approccio migliore per la posizione del file o le query specifiche della data.

Le query che chiedono informazioni sul contenuto stesso sono più efficaci rispetto alle domande relative alla posizione di un file o all'ultimo aggiornamento. Ad esempio, "Where is the keynote doc for Ignite 2024" potrebbe non restituire risultati perché il contenuto stesso non divulga la sua posizione. Un filterExpression oggetto sui metadati è un approccio migliore per la posizione del file o le query specifiche della data.

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte delle informazioni:

1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

3. Eliminare la base di conoscenza o aggiornare la base di conoscenza per rimuovere la fonte di conoscenza se sono presenti più fonti. In questo esempio viene mostrata la procedura di eliminazione.

   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. Eliminare la fonte di informazioni.

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

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte delle informazioni:

1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

3. Eliminare la base di conoscenza o aggiornare la base di conoscenza per rimuovere la fonte di conoscenza se sono presenti più fonti. In questo esempio viene mostrata la procedura di eliminazione.

   # 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. Eliminare la fonte di informazioni.

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

Prima di poter eliminare una fonte di conoscenza, devi eliminare qualsiasi knowledge base che vi faccia riferimento o aggiornare la definizione della knowledge base per rimuovere il riferimento. Per le fonti di conoscenza che generano una pipeline di generazione dell'indice e dell'indicizzatore, vengono eliminati anche tutti gli oggetti generati. Tuttavia, se è stato usato un indice esistente per creare un'origine conoscenze, l'indice non viene eliminato.

Se si tenta di eliminare una fonte di conoscenza in uso, l'azione fallisce e restituisce un elenco delle basi di conoscenza interessate.

Per eliminare una fonte delle informazioni:

1. Ottenere un elenco di tutte le knowledge base nel servizio di ricerca.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

2. Ottenere una singola definizione della Knowledge Base per verificare la presenza di riferimenti all'origine della knowledge base.

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

   Una risposta di esempio potrebbe essere simile alla seguente:

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

3. Eliminare la knowledge base o aggiornare la knowledge base rimuovendo la fonte delle informazioni se sono presenti più origini. In questo esempio viene mostrata la procedura di eliminazione.

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

4. Eliminare la fonte di informazioni.

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