MSSharePointRetriever

Microsoft Search(Graph) API를 통해 SharePoint·OneDrive에서 콘텐츠를 검색해 오는 Retriever예요.

출처: 문서

본문

MSSharePointRetriever는 Microsoft Search(Graph) API를 통해 사용자의 SharePoint·OneDrive 콘텐츠를 검색해요. 검색어가 주어지면 POST /search/query를 호출하고, 각 검색 결과를 content가 검색 스니펫이고 meta에 리소스 메타데이터(file_name, web_url, entity_type, created_date_time, last_modified_date_time, created_by, last_modified_by, mime_type, file_extension)가 담긴 Haystack Document로 매핑해요. 다운스트림 Fetcher가 목록 항목·페이지를 ID로 읽는 데 필요한 SharePoint 식별자(site_id, list_id, list_item_id, list_item_unique_id)도 저장해요.

이 Retriever는 실제 파일을 내려받거나 변환하지 않아요. 검색 스니펫과 메타데이터만 돌려주죠. 검색된 항목의 전체 내용을 내려받으려면 MSSharePointFetcher와 변환기를 함께 구성하면 돼요.

인증

Retriever는 실행 입력으로 사용자별 access_token을 받아요. 토큰은 위임된(delegated) Microsoft Graph 권한을 지녀야 해요(예: Files.Read.All + 사이트·목록 범위 지정용 Sites.Read.All). Search API는 위임 권한만 지원하죠. 보통 상위 OAuthTokenResolver에서 토큰을 연결하는데, 이 컴포넌트가 평문 문자열을 만들어내요. Secret도 받아서 내부에서 해석해요.

검색 범위 지정과 필터링

검색 범위를 좁히는 방법은 여러 가지예요.

entity_types: 조회할 Microsoft Search 엔티티 유형이에요. 기본값은 ["driveItem", "listItem"]으로 파일·폴더·SharePoint 페이지·뉴스·목록 항목을 포함해요. 그 외 유효한 값은 "list", "site"예요.
검색어에 직접 넣는 KQL 연산자. 예: filetype:docx, author:"Jane Doe", path:"https://contoso.sharepoint.com/sites/Team". Keyword Query Language(KQL) 구문 참조를 확인하세요.
query_template: '{searchTerms} path:"https://contoso.sharepoint.com/sites/Team"' 같은 재사용 템플릿이에요. 여기서 {searchTerms} 자리는 실행 시점의 검색어로 치환돼요.

설치

Microsoft SharePoint 통합을 설치해요.

pip install microsoft-sharepoint-haystack

더 알아보기 (Learn more)

단독으로 쓰기

아래 access_token은 사용자별 위임된 Microsoft Graph bearer 토큰이에요. 실제 운영 환경에서는 직접 붙여 넣지 말고 OAuthTokenResolver에서 얻어요.

from haystack_integrations.components.retrievers.microsoft_sharepoint import (
    MSSharePointRetriever,
)


retriever = MSSharePointRetriever(top_k=5)

result = retriever.run(
    query="quarterly roadmap",
    access_token="my-delegated-graph-token",
)

for doc in result["documents"]:
    print(doc.meta["file_name"], "-", doc.meta["web_url"])

파이프라인에서 쓰기

다음 파이프라인은 OAuthTokenResolver에서 토큰을 얻어 Retriever로 넣어서, 파이프라인 실행에는 검색어만 필요하도록 만들어요.

from haystack import Pipeline
from haystack.utils import Secret
from haystack_integrations.components.connectors.oauth import OAuthTokenResolver
from haystack_integrations.utils.oauth import OAuthRefreshTokenSource
from haystack_integrations.components.retrievers.microsoft_sharepoint import (
    MSSharePointRetriever,
)


pipeline = Pipeline()
pipeline.add_component(
    "resolver",
    OAuthTokenResolver(
        token_source=OAuthRefreshTokenSource(
            token_url="https://login.microsoftonline.com/common/oauth2/v2.0/token",
            client_id="aaa-bbb-ccc",
            refresh_token=Secret.from_env_var("MS_REFRESH_TOKEN"),
            scopes=[
                "https://graph.microsoft.com/Files.Read.All",
                "https://graph.microsoft.com/Sites.Read.All",
                "offline_access",
            ],
        ),
    ),
)

pipeline.add_component("retriever", MSSharePointRetriever(top_k=5))
pipeline.connect("resolver.access_token", "retriever.access_token")

result = pipeline.run({"retriever": {"query": "quarterly roadmap"}})
documents = result["retriever"]["documents"]

검색된 항목의 전체 내용을 내려받고 변환하려면 Retriever의 documents 출력을 MSSharePointFetcher에 연결하세요. 검색-가져오기-변환 전체 예제는 해당 페이지를 참고해요.