원격 SharePoint 기술 원본 만들기

원격 SharePoint 지식 원본은 Copilot 검색 API를 사용하여 Microsoft 365의 SharePoint에서 직접 텍스트 콘텐츠를 쿼리하여 병합, 순위 및 응답 공식을 위해 에이전트 검색 엔진에 결과를 반환합니다. 이 지식 원본에서 사용하는 검색 인덱스는 없으며 텍스트 콘텐츠만 쿼리됩니다.

쿼리 시 원격 SharePoint 기술 원본은 사용자 ID를 대신하여 Copilot 검색 API를 호출하므로 기술 자료 정의에 연결 문자열이 필요하지 않습니다. 사용자가 액세스할 수 있는 모든 콘텐츠는 지식 검색에 대한 범위 내입니다. 사이트를 제한하거나 검색을 제한하려면 필터 식을 설정합니다. Azure 테넌트와 Microsoft 365 테넌트는 동일한 Microsoft Entra ID 테넌트만 사용해야 하며 두 테넌트에서 호출자의 ID를 인식해야 합니다.

• 필터를 사용하여 URL, 날짜 범위, 파일 형식 및 기타 메타데이터별로 검색 범위를 지정할 수 있습니다.

• SharePoint 권한 및 Purview 레이블은 콘텐츠 요청에서 적용됩니다.

• 사용량은 Microsoft 365 및 코필로트 라이선스를 통해 청구됩니다.

다른 기술 원본과 마찬가지로 기술 자료에서 원격 SharePoint 기술 원본을 지정하고 에이전트 또는 챗봇이 쿼리 시 검색 작업을 호출할 때 결과를 접지 데이터로 사용합니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다.

• Azure와 동일한 Microsoft Entra ID 테넌트에 속한 Microsoft 365 테넌트의 SharePoint.

• 로컬 개발을 위한 개인 액세스 토큰 또는 클라이언트 애플리케이션의 사용자 ID입니다.

• .NET SDK용 Azure.Search.Documents 클라이언트 라이브러리 의 최신 미리 보기 버전입니다.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장하지만 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다.

로컬 개발의 경우 에이전트 검색 엔진은 액세스 토큰을 사용하여 SharePoint를 대신 호출합니다. 요청에 개인 액세스 토큰을 사용하는 방법에 대한 자세한 내용은 Azure AI Search에 연결을 참조하세요.

제한점

Copilot 검색 API의 다음 제한 사항은 원격 SharePoint 기술 자료에 적용됩니다.

• 코필로트 커넥터 또는 OneDrive 콘텐츠는 지원되지 않습니다. 콘텐츠는 SharePoint 사이트에서만 검색됩니다.

• 시간당 사용자당 200개 요청으로 제한됩니다.

• 1,500자의 쿼리 문자 제한입니다.

• 하이브리드 쿼리는 .doc, .docx, .pptx, .pdf, .aspx 및 .one 파일 확장명에서만 지원됩니다.

• 다중 모드 검색(테이블, 이미지 및 차트를 포함한 텍스트가 아닌 콘텐츠)은 지원되지 않습니다.

• 쿼리의 최대 결과는 25개입니다.

• 결과는 코필로트 검색 API에서 순서가 지정되지 않은 것으로 반환됩니다.

• 잘못된 KQL(키워드 쿼리 언어) 필터 식이 무시되고 필터 없이 쿼리가 계속 실행됩니다.

기존 지식 원본 확인

지식 원본은 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.

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

이름으로 단일 지식 원본을 반환하여 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));

다음 JSON은 원격 SharePoint 지식 원본에 대한 예제 응답입니다.

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

지식 원본 만들기

다음 코드를 실행하여 원격 SharePoint 기술 원본을 만듭니다.

API 키 는 Azure AI Search 및 Azure OpenAI에 대한 클라이언트 연결에 사용됩니다. 액세스 토큰은 Azure AI Search에서 사용자 대신 Microsoft 365의 SharePoint에 연결하는 데 사용됩니다. 액세스가 허용된 콘텐츠만 검색할 수 있습니다. 개인 액세스 토큰 및 기타 값을 가져오는 방법에 대한 자세한 내용은 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.");

원본별 속성

다음 속성을 전달하여 원격 SharePoint 기술 원본을 만들 수 있습니다.

필터 식 예제

모든 SharePoint 속성이 filterExpression에서 지원되는 것은 아닙니다. 지원되는 속성 목록은 API 참조를 참조하세요. 다음은 필터에서 사용할 수 있는 쿼리 가능한 속성에 대한 몇 가지 자세한 정보입니다. 쿼리 가능한 속성입니다.

구문 참조에서 KQL 필터 에 대해 자세히 알아봅니다.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에서 기술 원본을 지정하는 다음 단계를 계속 진행 합니다.

기술 자료가 구성되면 검색 작업을 사용하여 기술 원본을 쿼리합니다.

기술 자료 쿼리

기술 자료에 대한 검색 작업은 Microsoft 365의 콘텐츠에 대한 액세스 권한을 부여하는 사용자 ID를 제공합니다.

Azure AI Search는 액세스 토큰을 사용하여 사용자 ID를 대신하여 Copilot 검색 API를 호출합니다. 액세스 토큰은 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);

응답은 다음과 같을 수 있습니다.

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

쿼리 시 제약 조건을 적용하려는 경우에도 검색 요청은 KQL 필터 (filterExpressionAddOn)를 사용합니다. 지식 소스와 지식 베이스 검색 작업 모두에 filterExpressionAddOn를 지정하는 경우, 필터가 함께 AND 연산으로 사용됩니다.

콘텐츠 자체에 대한 질문을 하는 쿼리는 파일이 있는 위치 또는 마지막으로 업데이트된 시기에 대한 질문보다 더 효과적입니다. 예를 들어 "Ignite 2024의 기조 문서 위치"를 묻는 경우 콘텐츠 자체가 해당 위치를 공개하지 않으므로 "쿼리에 대한 관련 콘텐츠를 찾을 수 없습니다"가 표시될 수 있습니다. 메타데이터에 대한 필터는 파일 위치 또는 날짜별 쿼리에 대한 더 나은 솔루션입니다.

더 좋은 질문은 "Ignite 2024의 기조 문서란?"입니다. 응답에는 합성된 답변, 쿼리 활동 및 토큰 수와 URL 및 기타 메타데이터가 포함됩니다.

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

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

1. 검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

3. 기술 자료를 삭제하거나 기술 자료를 업데이트 하여 여러 원본이 있는 경우 기술 자료를 제거합니다. 이 예제에서는 삭제를 보여줍니다.

   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. 지식 원본을 삭제합니다.

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

원격 SharePoint 지식 원본은 Copilot 검색 API를 사용하여 Microsoft 365의 SharePoint에서 직접 텍스트 콘텐츠를 쿼리하여 병합, 순위 및 응답 공식을 위해 에이전트 검색 엔진에 결과를 반환합니다. 이 지식 원본에서 사용하는 검색 인덱스는 없으며 텍스트 콘텐츠만 쿼리됩니다.

쿼리 시 원격 SharePoint 기술 원본은 사용자 ID를 대신하여 Copilot 검색 API를 호출하므로 기술 자료 정의에 연결 문자열이 필요하지 않습니다. 사용자가 액세스할 수 있는 모든 콘텐츠는 지식 검색에 대한 범위 내입니다. 사이트를 제한하거나 검색을 제한하려면 필터 식을 설정합니다. Azure 테넌트와 Microsoft 365 테넌트는 동일한 Microsoft Entra ID 테넌트만 사용해야 하며 두 테넌트에서 호출자의 ID를 인식해야 합니다.

• 필터를 사용하여 URL, 날짜 범위, 파일 형식 및 기타 메타데이터별로 검색 범위를 지정할 수 있습니다.

• SharePoint 권한 및 Purview 레이블은 콘텐츠 요청에서 적용됩니다.

• 사용량은 Microsoft 365 및 코필로트 라이선스를 통해 청구됩니다.

다른 기술 원본과 마찬가지로 기술 자료에서 원격 SharePoint 기술 원본을 지정하고 에이전트 또는 챗봇이 쿼리 시 검색 작업을 호출할 때 결과를 접지 데이터로 사용합니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다.

• Azure와 동일한 Microsoft Entra ID 테넌트에 속한 Microsoft 365 테넌트의 SharePoint.

• 로컬 개발을 위한 개인 액세스 토큰 또는 클라이언트 애플리케이션의 사용자 ID입니다.

• Python용 클라이언트 라이브러리의azure-search-documents 최신 미리 보기 버전입니다.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장하지만 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다.

로컬 개발의 경우 에이전트 검색 엔진은 액세스 토큰을 사용하여 SharePoint를 대신 호출합니다. 요청에 개인 액세스 토큰을 사용하는 방법에 대한 자세한 내용은 Azure AI Search에 연결을 참조하세요.

제한점

Copilot 검색 API의 다음 제한 사항은 원격 SharePoint 기술 자료에 적용됩니다.

• 코필로트 커넥터 또는 OneDrive 콘텐츠는 지원되지 않습니다. 콘텐츠는 SharePoint 사이트에서만 검색됩니다.

• 시간당 사용자당 200개 요청으로 제한됩니다.

• 1,500자의 쿼리 문자 제한입니다.

• 하이브리드 쿼리는 .doc, .docx, .pptx, .pdf, .aspx 및 .one 파일 확장명에서만 지원됩니다.

• 다중 모드 검색(테이블, 이미지 및 차트를 포함한 텍스트가 아닌 콘텐츠)은 지원되지 않습니다.

• 쿼리의 최대 결과는 25개입니다.

• 결과는 코필로트 검색 API에서 순서가 지정되지 않은 것으로 반환됩니다.

• 잘못된 KQL(키워드 쿼리 언어) 필터 식이 무시되고 필터 없이 쿼리가 계속 실행됩니다.

기존 지식 원본 확인

지식 원본은 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.

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

이름으로 단일 지식 원본을 반환하여 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))

다음 JSON은 원격 SharePoint 지식 원본에 대한 예제 응답입니다.

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

지식 원본 만들기

다음 코드를 실행하여 원격 SharePoint 기술 원본을 만듭니다.

API 키 는 Azure AI Search 및 Azure OpenAI에 대한 클라이언트 연결에 사용됩니다. 액세스 토큰은 Azure AI Search에서 사용자 대신 Microsoft 365의 SharePoint에 연결하는 데 사용됩니다. 액세스가 허용된 콘텐츠만 검색할 수 있습니다. 개인 액세스 토큰 및 기타 값을 가져오는 방법에 대한 자세한 내용은 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.")

원본별 속성

다음 속성을 전달하여 원격 SharePoint 기술 원본을 만들 수 있습니다.

필터 식 예제

모든 SharePoint 속성이 filterExpression에서 지원되는 것은 아닙니다. 지원되는 속성 목록은 API 참조를 참조하세요. 다음은 필터에서 사용할 수 있는 쿼리 가능한 속성에 대한 몇 가지 자세한 정보입니다. 쿼리 가능한 속성입니다.

구문 참조에서 KQL 필터 에 대해 자세히 알아봅니다.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에서 기술 원본을 지정하는 다음 단계를 계속 진행 합니다.

기술 자료가 구성되면 검색 작업을 사용하여 기술 원본을 쿼리합니다.

기술 자료 쿼리

기술 자료에 대한 검색 작업은 Microsoft 365의 콘텐츠에 대한 액세스 권한을 부여하는 사용자 ID를 제공합니다.

Azure AI Search는 액세스 토큰을 사용하여 사용자 ID를 대신하여 Copilot 검색 API를 호출합니다. 액세스 토큰은 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)

쿼리 시 제약 조건을 적용하려는 경우에도 검색 요청은 KQL 필터 (filter_expression_add_on)를 사용합니다. 지식 소스와 지식 베이스 검색 작업 모두에 filter_expression_add_on를 지정하는 경우, 필터가 함께 AND 연산으로 사용됩니다.

콘텐츠 자체에 대한 질문을 하는 쿼리는 파일이 있는 위치 또는 마지막으로 업데이트된 시기에 대한 질문보다 더 효과적입니다. 예를 들어 "Ignite 2024의 기조 문서 위치"를 묻는 경우 콘텐츠 자체가 해당 위치를 공개하지 않으므로 "쿼리에 대한 관련 콘텐츠를 찾을 수 없습니다"가 표시될 수 있습니다. 메타데이터에 대한 필터는 파일 위치 또는 날짜별 쿼리에 대한 더 나은 솔루션입니다.

더 좋은 질문은 "Ignite 2024의 기조 문서란?"입니다. 응답에는 합성된 답변, 쿼리 활동 및 토큰 수와 URL 및 기타 메타데이터가 포함됩니다.

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

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

1. 검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

3. 기술 자료를 삭제하거나 기술 자료를 업데이트 하여 여러 원본이 있는 경우 기술 자료를 제거합니다. 이 예제에서는 삭제를 보여줍니다.

   # 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. 지식 원본을 삭제합니다.

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

원격 SharePoint 지식 원본은 Copilot 검색 API를 사용하여 Microsoft 365의 SharePoint에서 직접 텍스트 콘텐츠를 쿼리하여 병합, 순위 및 응답 공식을 위해 에이전트 검색 엔진에 결과를 반환합니다. 이 지식 원본에서 사용하는 검색 인덱스는 없으며 텍스트 콘텐츠만 쿼리됩니다.

쿼리 시 원격 SharePoint 기술 원본은 사용자 ID를 대신하여 Copilot 검색 API를 호출하므로 기술 자료 정의에 연결 문자열이 필요하지 않습니다. 사용자가 액세스할 수 있는 모든 콘텐츠는 지식 검색에 대한 범위 내입니다. 사이트를 제한하거나 검색을 제한하려면 필터 식을 설정합니다. Azure 테넌트와 Microsoft 365 테넌트는 동일한 Microsoft Entra ID 테넌트만 사용해야 하며 두 테넌트에서 호출자의 ID를 인식해야 합니다.

• 필터를 사용하여 URL, 날짜 범위, 파일 형식 및 기타 메타데이터별로 검색 범위를 지정할 수 있습니다.

• SharePoint 권한 및 Purview 레이블은 콘텐츠 요청에서 적용됩니다.

• 사용량은 Microsoft 365 및 코필로트 라이선스를 통해 청구됩니다.

다른 기술 원본과 마찬가지로 기술 자료에서 원격 SharePoint 기술 원본을 지정하고 에이전트 또는 챗봇이 쿼리 시 검색 작업을 호출할 때 결과를 접지 데이터로 사용합니다.

필수 조건

• 에이전트 검색을 제공하는 모든 지역의 Azure AI 검색. 의미 체계 순위가 활성화되어 있어야 합니다.

• Azure와 동일한 Microsoft Entra ID 테넌트에 속한 Microsoft 365 테넌트의 SharePoint.

• 로컬 개발을 위한 개인 액세스 토큰 또는 클라이언트 애플리케이션의 사용자 ID입니다.

• Search Service REST API의 2025-11-01-preview 버전입니다.

• Azure AI Search에서 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장하지만 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다.

로컬 개발의 경우 에이전트 검색 엔진은 액세스 토큰을 사용하여 SharePoint를 대신 호출합니다. 요청에 개인 액세스 토큰을 사용하는 방법에 대한 자세한 내용은 Azure AI Search에 연결을 참조하세요.

제한점

Copilot 검색 API의 다음 제한 사항은 원격 SharePoint 기술 자료에 적용됩니다.

• 코필로트 커넥터 또는 OneDrive 콘텐츠는 지원되지 않습니다. 콘텐츠는 SharePoint 사이트에서만 검색됩니다.

• 시간당 사용자당 200개 요청으로 제한됩니다.

• 1,500자의 쿼리 문자 제한입니다.

• 하이브리드 쿼리는 .doc, .docx, .pptx, .pdf, .aspx 및 .one 파일 확장명에서만 지원됩니다.

• 다중 모드 검색(테이블, 이미지 및 차트를 포함한 텍스트가 아닌 콘텐츠)은 지원되지 않습니다.

• 쿼리의 최대 결과는 25개입니다.

• 결과는 코필로트 검색 API에서 순서가 지정되지 않은 것으로 반환됩니다.

• 잘못된 KQL(키워드 쿼리 언어) 필터 식이 무시되고 필터 없이 쿼리가 계속 실행됩니다.

기존 지식 원본 확인

지식 원본은 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

기술 자료 사용 - GET(REST API)을 사용하여 이름 및 형식별로 기술 자료를 나열합니다.

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

이름으로 단일 지식 원본을 반환하여 JSON 정의를 검토할 수도 있습니다.

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

다음 JSON은 원격 SharePoint 지식 원본에 대한 예제 응답입니다.

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

지식 원본 만들기

기술 자료 사용 - REST API(만들기 또는 업데이트)를 사용하여 원격 SharePoint 기술 자료를 만듭니다.

API 키 는 Azure AI Search 및 Azure OpenAI에 대한 클라이언트 연결에 사용됩니다. 액세스 토큰은 Azure AI Search에서 사용자 대신 Microsoft 365의 SharePoint에 연결하는 데 사용됩니다. 액세스가 허용된 콘텐츠만 검색할 수 있습니다. 개인 액세스 토큰 및 기타 값을 가져오는 방법에 대한 자세한 내용은 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
    }
}

원본별 속성

다음 속성을 전달하여 원격 SharePoint 기술 원본을 만들 수 있습니다.

필터 식 예제

모든 SharePoint 속성이 filterExpression에서 지원되는 것은 아닙니다. 지원되는 속성 목록은 API 참조를 참조하세요. 다음은 필터에서 사용할 수 있는 쿼리 가능한 속성에 대한 몇 가지 자세한 정보입니다. 쿼리 가능한 속성입니다.

구문 참조에서 KQL 필터 에 대해 자세히 알아봅니다.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에서 기술 원본을 지정하는 다음 단계를 계속 진행 합니다.

기술 자료가 구성되면 검색 작업을 사용하여 기술 원본을 쿼리합니다.

기술 자료 쿼리

기술 자료에 대한 검색 작업은 Microsoft 365의 콘텐츠에 대한 액세스 권한을 부여하는 사용자 ID를 제공합니다.

Azure AI Search는 액세스 토큰을 사용하여 사용자 ID를 대신하여 Copilot 검색 API를 호출합니다. 액세스 토큰은 HTTP 헤더로 검색 엔드포인트에 x-ms-query-source-authorization 제공됩니다.

검색 서비스가 있는 테넌트에 대한 액세스 토큰을 반드시 생성해야 합니다.

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

쿼리 시 제약 조건을 적용하려는 경우에도 검색 요청은 KQL 필터 (filterExpressionAddOn)를 사용합니다. 지식 소스와 지식 베이스 검색 작업 모두에 filterExpressionAddOn를 지정하는 경우, 필터가 함께 AND 연산으로 사용됩니다.

콘텐츠 자체에 대한 질문을 하는 쿼리는 파일이 있는 위치 또는 마지막으로 업데이트된 시기에 대한 질문보다 더 효과적입니다. 예를 들어 "Ignite 2024의 기조 문서 위치"를 묻는 경우 콘텐츠 자체가 해당 위치를 공개하지 않으므로 "쿼리에 대한 관련 콘텐츠를 찾을 수 없습니다"가 표시될 수 있습니다. 메타데이터에 대한 필터는 파일 위치 또는 날짜별 쿼리에 대한 더 나은 솔루션입니다.

더 좋은 질문은 "Ignite 2024의 기조 문서란?"입니다. 응답에는 합성된 답변, 쿼리 활동 및 토큰 수와 URL 및 기타 메타데이터가 포함됩니다.

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

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

1. 검색 서비스의 모든 기술 자료 목록을 가져옵니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

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

   예제 응답은 다음과 같을 수 있습니다.

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

3. 여러 원본이 있는 경우 기술 자료를 삭제하거나 기술 자료를 제거 하여 기술 자료를 업데이트합니다. 이 예제에서는 삭제를 보여줍니다.

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

4. 지식 원본을 삭제합니다.

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