Skapa en fjärransluten SharePoint kunskapskälla

• Det senaste Azure.Search.Documents förhandsversionspaketet: dotnet add package Azure.Search.Documents --prerelease

• Det senaste azure-search-documents förhandsversionspaketet: pip install --pre azure-search-documents

• 2025-11-01-preview-versionen av Sökningstjänstens REST API:er.

En kunskapskälla är ett återanvändbart objekt på toppnivå. Att känna till befintliga kunskapskällor är användbart för återanvändning eller namngivning av nya objekt.

Kör följande kod för att lista kunskapskällor efter namn och typ.

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

Du kan också returnera en enda kunskapskälla efter namn för att granska dess JSON-definition.

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

En kunskapskälla är ett återanvändbart objekt på toppnivå. Att känna till befintliga kunskapskällor är användbart för återanvändning eller namngivning av nya objekt.

Kör följande kod för att lista kunskapskällor efter namn och typ.

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

Du kan också returnera en enda kunskapskälla efter namn för att granska dess JSON-definition.

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

En kunskapskälla är ett återanvändbart objekt på toppnivå. Att känna till befintliga kunskapskällor är användbart för återanvändning eller namngivning av nya objekt.

Använd Kunskapskällor – Hämta (REST API) för att lista kunskapskällor efter namn och typ.

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

Du kan också returnera en enda kunskapskälla efter namn för att granska dess JSON-definition.

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

Kör följande kod för att skapa en fjärransluten SharePoint kunskapskälla.

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

Kör följande kod för att skapa en fjärransluten SharePoint kunskapskälla.

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

Använd Knowledge Sources – Skapa eller uppdatera (REST API) för att skapa en fjärransluten SharePoint kunskapskälla.

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

Du kan skicka en FilterExpressionAddOn i KnowledgeSourceParams i hämtningsbegäran för att tillämpa ett KQL-filter vid frågetillfället. Om du anger FilterExpressionAddOn i hämtningsbegäran och en FilterExpression i kunskapskällans definition kombineras filtren med ett OCH.

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

Du kan skicka en filter_expression_add_on i knowledge_source_params i hämtningsbegäran för att tillämpa ett KQL-filter vid frågetillfället. Om du anger filter_expression_add_on i hämtningsbegäran och en filter_expression i kunskapskällans definition kombineras filtren med ett OCH.

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

Du kan skicka en filterExpressionAddOn i knowledgeSourceParams i hämtningsbegäran för att tillämpa ett KQL-filter vid frågetillfället. Om du anger filterExpressionAddOn i hämtningsbegäran och en filterExpression i kunskapskällans definition kombineras filtren med ett OCH.

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

Frågor som frågar om själva innehållet är effektivare än frågor om var en fil finns eller när den senast uppdaterades. Till exempel kanske "Where is the keynote doc for Ignite 2024" inte returnerar några resultat eftersom själva innehållet inte avslöjar dess plats. En FilterExpression på metadata är en bättre metod för filplats eller datumspecifika frågor.

Frågor som frågar om själva innehållet är effektivare än frågor om var en fil finns eller när den senast uppdaterades. Till exempel kanske "Where is the keynote doc for Ignite 2024" inte returnerar några resultat eftersom själva innehållet inte avslöjar dess plats. En filter_expression på metadata är en bättre metod för filplats eller datumspecifika frågor.

Frågor som frågar om själva innehållet är effektivare än frågor om var en fil finns eller när den senast uppdaterades. Till exempel kanske "Where is the keynote doc for Ignite 2024" inte returnerar några resultat eftersom själva innehållet inte avslöjar dess plats. En filterExpression på metadata är en bättre metod för filplats eller datumspecifika frågor.

Innan du kan ta bort en kunskapskälla måste du ta bort alla kunskapsbaser som refererar till den eller uppdatera kunskapsbasdefinitionen för att ta bort referensen. För kunskapskällor som genererar en index- och indexeringspipeline tas även alla genererade objekt bort. Men om du använde ett befintligt index för att skapa en kunskapskälla tas inte ditt index bort.

Om du försöker ta bort en kunskapskälla som används misslyckas åtgärden och returnerar en lista över berörda kunskapsbaser.

Så här tar du bort en kunskapskälla:

1. Hämta en lista över alla kunskapsbaser i söktjänsten.

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

   Ett exempelsvar kan se ut så här:

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

2. Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.

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

   Ett exempelsvar kan se ut så här:

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

3. Ta antingen bort kunskapsbasen eller uppdatera kunskapsbasen för att ta bort kunskapskällan om du har flera källor. Det här exemplet visar borttagning.

   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. Ta bort kunskapskällan.

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

Innan du kan ta bort en kunskapskälla måste du ta bort alla kunskapsbaser som refererar till den eller uppdatera kunskapsbasdefinitionen för att ta bort referensen. För kunskapskällor som genererar en index- och indexeringspipeline tas även alla genererade objekt bort. Men om du använde ett befintligt index för att skapa en kunskapskälla tas inte ditt index bort.

Om du försöker ta bort en kunskapskälla som används misslyckas åtgärden och returnerar en lista över berörda kunskapsbaser.

Så här tar du bort en kunskapskälla:

1. Hämta en lista över alla kunskapsbaser i söktjänsten.

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

   Ett exempelsvar kan se ut så här:

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

2. Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.

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

   Ett exempelsvar kan se ut så här:

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

3. Ta antingen bort kunskapsbasen eller uppdatera kunskapsbasen för att ta bort kunskapskällan om du har flera källor. Det här exemplet visar borttagning.

   # 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. Ta bort kunskapskällan.

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

Innan du kan ta bort en kunskapskälla måste du ta bort alla kunskapsbaser som refererar till den eller uppdatera kunskapsbasdefinitionen för att ta bort referensen. För kunskapskällor som genererar en index- och indexeringspipeline tas även alla genererade objekt bort. Men om du använde ett befintligt index för att skapa en kunskapskälla tas inte ditt index bort.

Om du försöker ta bort en kunskapskälla som används misslyckas åtgärden och returnerar en lista över berörda kunskapsbaser.

Så här tar du bort en kunskapskälla:

1. Hämta en lista över alla kunskapsbaser i söktjänsten.

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

   Ett exempelsvar kan se ut så här:

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

2. Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.

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

   Ett exempelsvar kan se ut så här:

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

3. Ta antingen bort kunskapsbasen eller uppdatera kunskapsbasen genom att ta bort kunskapskällan om du har flera källor. Det här exemplet visar borttagning.

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

4. Ta bort kunskapskällan.

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