Windows Search 공급자

아티클
05/10/2024

참고 항목

일부 정보는 상업용으로 출시되기 전에 상당 부분 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

Important

이 토픽에 설명된 기능은 Windows 11용 빌드 22631.2787 및 Windows 10용 빌드 19045.3758부터 Windows의 미리 보기 빌드에서 사용할 수 있지만, 안정성 개선 사항이 포함되어 있는 최신 빌드를 권장합니다. Windows 프리뷰 빌드에 대한 자세한 내용은 Windows 10 Insider Preview를 참조하세요.

Windows Search는 현재 Microsoft Bing의 Web Search를 사용하여 웹 콘텐츠 및 검색 결과를 반환합니다. EEA(유럽 경제 지역)에서는 설정을 통해 웹 검색 공급자를 구현하는 설치된 앱이 Windows 검색에서 웹 콘텐츠 및 검색 결과를 반환하도록 설정할 수 있습니다.

검색 공급자는 OS에서 검색 공급자를 등록하는 데 필요한 정보를 제공하는 패키지 매니페스트 파일을 사용하여 MSIX 패키지를 만들어 검색 환경과 통합합니다. 사용자는 연결된 앱 패키지를 설치하여 Windows에 검색 공급자를 추가할 수 있으며 Windows 설정 앱의 프로그램 추가 또는 제거 페이지를 통해 검색 공급자를 제거할 수 있습니다.

개발 및 테스트의 경우 개발자 모드가 활성화되고 디바이스에서 검색 공급자 앱이 테스트용으로 로드되면 사용 가능한 검색 공급자 목록에 표시됩니다. 자세한 내용은 개발자 모드 기능 및 디버깅을 참조하세요.

검색 공급자가 OS에 등록되면 사용자 쿼리는 표준화된 쿼리 문자열을 사용하여 패키지 매니페스트에서 공급자가 지정한 HTTP 엔드포인트로 전달됩니다. 엔드포인트는 JSON 문서에서 제안된 결과를 반환합니다. 응답 문서에 제안된 각 URL을 사용하여 검색 공급자는 검색 결과 UI의 미리 보기 창에 표시되는 HTML 문서를 반환하는 미리 보기 엔드포인트 URL을 포함합니다.

이 문서에서는 검색 공급자 앱 패키지를 만들기 위한 지침과 검색 공급자 HTTP 엔드포인트를 구현하기 위한 프로토콜에 대한 세부 정보를 제공합니다.

검색 확장성 앱 패키지 만들기

검색 공급자는 제안 및 미리 보기에 대한 검색 공급자 이름 및 HTTP 엔드포인트와 같은 공급자에 대한 필수 정보가 포함된 MSIX 패키지를 제공하여 OS에 등록합니다.

검색 공급자 앱 확장

앱 패키지 매니페스트 파일은 Windows 앱에 대한 다양한 확장 및 기능을 지원합니다. 앱 패키지 매니페스트 형식은 패키지 매니페스트 스키마 참조에 설명된 스키마 집합에 의해 정의됩니다. 검색 공급자는 uap3:AppExtension 내에서 등록 정보를 선언합니다. 확장의 이름 속성은 "com.microsoft.windows.websearchprovider"로 설정해야 합니다.

검색 공급자는 uap3:AppExtension의 자식으로 uap3:Properties를 포함해야 합니다. 패키지 매니페스트 스키마는 올바른 형식의 XML을 요구하는 것 외에는 uap3:Properties 요소의 구조를 적용하지 않습니다. 이 섹션의 나머지 부분에서는 검색 공급자를 성공적으로 등록하기 위해 OS에서 기대하는 XML 형식에 대해 설명합니다.

<uap3:Extension Category="windows.appExtension">
  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="SearchExampleApp" Id="ContosoSearchApp" PublicFolder="Public">
    <uap3:Properties>
    <!-- Search provider registration content goes here -->
    </uap3:Properties>
  </uap3:AppExtension>
</uap3:Extension>

요소 계층 구조

uap3:Properties

EndPoint

프로토콜

엔드포인트

OS에서 검색 쿼리 요청을 보낼 HTTPS 엔드포인트의 URL입니다.

프로토콜

제공된 웹 검색 결과를 시작할 때 사용할 프로토콜 스키마입니다. 지정된 프로토콜이 OS의 앱에 의해 등록되지 않은 경우 검색 결과에 대한 기본 브라우저가 시작됩니다. 프로토콜 스키마 등록에 대한 자세한 내용은 uap:Protocol을 참조하세요.

DynamicContentEndpoint

OS가 검색 상자에 나타날 반짝임 아이콘에 대한 요청을 보낼 HTTPS 엔드포인트의 URL입니다. 자세한 내용은 반짝임 아이콘 엔드포인트 구현을 참조하세요. 이 기능은 Windows 10 빌드 19045.4233 및 Windows 11 빌드 22621.3371부터 지원됩니다.

예제 패키지 매니페스트 파일

다음은 Windows Search 공급자를 등록하기 위한 예제 appmanifest.xml 패키지 매니페스트 파일입니다.

<!-- appxmanifest.xml -->

  <uap3:Extension Category="windows.appExtension">
	  <uap3:AppExtension Name="com.microsoft.windows.websearchprovider" DisplayName="CustomSearch" Id="CustomSearchApp" PublicFolder="Public">
		  <uap3:Properties>
			  <Endpoint>https://customsearchendpoint</Endpoint>
			  <Protocol>customsearch</Protocol>
        <DynamicContentEndpoint>https://sub.contoso.com/dynamic</DynamicContentEndpoint>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

Windows Search 공급자 제안 엔드포인트 구현

검색 공급자는 사용자가 Windows 검색 상자에 입력할 때 OS에서 호출하는 HTTPS 엔드포인트를 노출하고 등록해야 합니다. 이 엔드포인트는 제공된 사용자 쿼리에 대한 검색 제안을 포함하는 JSON 형식 문자열을 반환해야 합니다. 콘텐츠는 HTTPS를 통해 전달되어야 합니다. 검색 통합은 HTTP를 통해 전달되는 콘텐츠를 지원하지 않습니다.

제안 HTTPS 요청 형식

제안 엔드포인트에 대한 HTTPS 요청은 다음 형식을 사용합니다.

https://contoso.com?setlang=en-US&cc=US&qry=

제안 엔드포인트에 전달된 쿼리 문자열 매개 변수는 다음과 같습니다.

매개 변수	설명
setlang	쿼리와 연결된 로캘
cc	쿼리와 연결된 국가 코드입니다.
qry	사용자가 제공한 쿼리입니다. 매개 변수에 값이 없으면(예: 쿼리 문자열에 다음과 같이 `qry=`) 사용자 쿼리가 비어 있습니다. 검색 공급자는 여전히 빈 쿼리에 대한 응답으로 제안 및 미리 보기 페이지를 제공할 수 있습니다. 참고:OS는 쿼리 문자열의 삭제를 수행하지 않습니다. 검색 공급자는 쿼리를 받을 때 자체 삭제를 구현할 수 있습니다.

제안 HTTPS 응답 헤더

검색 공급자는 제안 HTTPS 엔드포인트의 응답에 다음 헤더를 포함해야 합니다.

HTTP/액세스-제어-허용-기원: https://www.bing.com
액세스-제어-허용-자격 증명: 참
액세스-제어-허용-방법: GET
Content-Type: application/json; charset=utf-8
콘텐츠 길이: [응답의 정확한 길이여야 합니다.]

제안 응답 JSON 형식

제안에 대한 검색 공급자 HTTPS 엔드포인트는 다음 형식의 JSON 문서를 반환해야 합니다. 키 이름은 형식과 정확히 일치해야 합니다.

키	설명
제안	사용자 쿼리와 연결된 제안을 나타내는 키`Attributes`가 있는 JSON 개체 목록을 포함합니다.
특성	제안의 특성을 포함합니다.
URL	공급자 웹 사이트의 검색 제안에 대한 URL입니다.
query	검색 제안과 연결된 사용자 쿼리입니다.
previewPaneUrl	제안의 HTML 미리 보기를 검색할 수 있는 미리 보기 엔드포인트의 URL입니다.
Text	제안에 대한 텍스트 설명입니다.

{"Suggestions": 
   [{"Attributes": 
     {"url":"https://www.contoso.com/search?q=projection+matrix","query":"projection matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"projection matrix"}, 
    {"Attributes": 
     {"url":"https://www.contoso.com/search?q=rotation+matrix","query":"rotation matrix","previewPaneUrl":"http://www.contoso.com/preview"} ,"Text":"rotation matrix"}
    ] 
}

Windows Search 공급자 미리보기 엔드포인트 구현

검색 공급자는 검색 결과의 각 제안과 연결된 페이지의 HTML 미리 보기를 제공하는 HTTPS 엔드포인트의 URL을 반환합니다. 미리 보기 엔드포인트 응답은 작동하는 페이지에 대한 HTML 코드를 반환해야 합니다.

HTTPS 요청 형식 미리 보기

미리 보기 엔드포인트에 대한 HTTPS 요청은 다음 형식을 사용합니다.

https://contoso.com?Darkschemeovr=1

제안 엔드포인트에 전달된 쿼리 문자열 매개 변수는 다음과 같습니다.

매개 변수	설명
Darkschemeovr	호출하는 Windows 시스템에서 어두운 테마를 사용할 수 있는지를 지정합니다. 어두운 테마를 사용하는 경우 값은 1이고 어두운 테마를 사용하지 않도록 설정하면 0입니다.

HTTPS 응답 헤더 미리 보기

HTTP/액세스-제어-허용-기원: https://www.bing.com
액세스-제어-허용-자격 증명: 참
액세스-제어-허용-방법: GET
콘텐츠-형식: text/html; charset=utf-8
콘텐츠 길이: [미리 보기 html의 정확한 길이여야 합니다.]

검색 공급자는 OPTIONS 요청 메서드를 지원하고 HTTP OK를 사용하여 이 요청에 응답해야 합니다. 검색 공급자 엔드포인트가 CORS를 사용하는 경우 Windows 검색 클라이언트는 각 GET 요청 전에 HTTP OPTIONS 요청을 보냅니다.

반짝임 아이콘 엔드포인트 구현

검색 공급자를 사용하도록 설정된 경우 검색 공급자는 검색 창에 표시되는 라이트 모드와 다크 모드의 반짝임 아이콘을 선택적으로 제공할 수 있습니다. 앱 매니페스트에 DynamicContentEndpoint 요소가 제공되면 요청이 지정된 URL로 전송되고 검색 공급자는 아이콘 이미지 파일 및 기타 메타데이터의 URL을 포함하는 json 파일을 아래에 정의된 형식으로 응답합니다. 검색 공급자가 Windows Search에서 활성 상태인 가장 최근 공급자인 동안에는 반짝임 아이콘 요청이 주기적으로 전송됩니다. 이 요청의 주기는 6시간마다입니다. 또한 각 검색 시작 시 및 디바이스 잠금 해제 시 요청이 전송됩니다.

반짝임 아이콘 HTTPS 요청 형식

반짝임 아이콘 엔드포인트에 대한 HTTPS 요청은 다음 형식을 사용합니다.

https://www.contoso.com/Gleam?cc=FR&setlang=en-us&dateTime=3%2F29%2F2024%2C%208%3A33%3A56%20PM&deviceOs=windows10&schemaversion=1.0.0

제안 엔드포인트에 전달된 쿼리 문자열 매개 변수는 다음과 같습니다.

매개 변수	설명
setlang	쿼리와 연결된 로캘
cc	쿼리와 연결된 국가 코드입니다.
dateTime	URL로 인코딩된, 클라이언트 디바이스의 현재 날짜 및 시간입니다.
deviceOs	클라이언트 디바이스의 OS입니다. 이 매개 변수의 값은 "Windows10" 또는 "Windows11"일 수 있습니다. Windows 10에서 반짝임 아이콘 크기는 30x60입니다. Windows 11에서 반짝임 아이콘 크기는 20x36입니다.
schemaversion	반짝임 스키마 버전입니다.

반짝임 아이콘 응답 JSON 형식

반짝임 아이콘에 대한 검색 공급자 HTTPS 엔드포인트는 다음 형식의 JSON 문서를 반환해야 합니다. 키 이름은 형식과 정확히 일치해야 합니다. 현재 스키마 버전은 1.0.0입니다.

키	설명
schemaVersion	반짝임 스키마 버전입니다. 요청의 schemaVersion 쿼리 문자열 매개 변수와 일치해야 합니다.
telemetryId	반짝임 아이콘의 고유 식별자입니다. 응답의 값이 현재 반짝임 아이콘의 값과 같으면 OS는 아이콘을 업데이트하지 않습니다.
expirationTime	반짝임 아이콘의 만료 시간입니다. 미래의 시간이어야 합니다.
content	응답의 내용 섹션입니다.
taskbarSearchBox	검색 상자에 대한 설정을 포함합니다.
반짝임	반짝임 아이콘에 대한 설정을 포함합니다.
altText	반짝임 아이콘의 대체 텍스트입니다.
dimensionEnum	Windows 10 디바이스에서 요청을 보낸 경우 값은 "30x60"입니다. Windows 11 디바이스에서 요청을 보낸 경우 값은 "20x36"입니다.
iconUrl	라이트 모드 및 다크 모드의 반짝임 아이콘 이미지 파일 URL을 포함합니다.
light	라이트 모드의 반짝임 아이콘 이미지 파일 URL입니다.
dark	다크 모드의 반짝임 아이콘 이미지 파일 URL입니다.

{
  "schemaVersion":"1.0.0",
  "telemetryId":"<unique gleam Id>",
  "expirationTime":"2025-12-09T20:37:13Z",
  "content": {
    "taskbarSearchBox": {
      "gleam":{
        "altText": "<alt text of the gleam>",
        "dimensionEnum": "(30x60 for Windows 10, 20x36 for Windows 11)",
        "iconUrl": {
          "light":"<3p's light gleam url>",
          "dark": "<3p's dark gleam url>"
        }
      }
    }
  }
}

반짝임 아이콘 응답 유효성 검사

응답은 라이트 모드 자산 URL과 다크 모드 자산 URL을 모두 지정해야 합니다. 아이콘 이미지 URL에 대한 도메인은 HTTPS를 사용해야 하며 하위 도메인은 앱 매니페스트 파일의 DynamicContentEndpoint 요소에 지정된 하위 도메인과 일치해야 합니다.

이미지 파일은 SVG 형식이어야 하며 최대 파일 크기는 300kB입니다. 반짝임 아이콘은 SVG 파일 내 240x120px 프레임을 넘지 않아야 합니다.

빈 페이로드가 수신되면 활성 반짝임 아이콘이 지워져 반짝임 아이콘이 표시되지 않습니다.

다음을 통해 공유

Windows Search 공급자

검색 확장성 앱 패키지 만들기

검색 공급자 앱 확장

요소 계층 구조

엔드포인트

프로토콜

DynamicContentEndpoint

예제 패키지 매니페스트 파일

Windows Search 공급자 제안 엔드포인트 구현

제안 HTTPS 요청 형식

제안 HTTPS 응답 헤더

제안 응답 JSON 형식

Windows Search 공급자 미리보기 엔드포인트 구현

HTTPS 요청 형식 미리 보기

HTTPS 응답 헤더 미리 보기

반짝임 아이콘 엔드포인트 구현

반짝임 아이콘 HTTPS 요청 형식

반짝임 아이콘 응답 JSON 형식

반짝임 아이콘 응답 유효성 검사

추가 리소스

다음을 통해 공유

Windows Search 공급자

검색 확장성 앱 패키지 만들기

검색 공급자 앱 확장

요소 계층 구조

엔드포인트

프로토콜

DynamicContentEndpoint

예제 패키지 매니페스트 파일

Windows Search 공급자 제안 엔드포인트 구현

제안 HTTPS 요청 형식

제안 HTTPS 응답 헤더

제안 응답 JSON 형식

Windows Search 공급자 미리보기 엔드포인트 구현

HTTPS 요청 형식 미리 보기

HTTPS 응답 헤더 미리 보기

OPTIONS 요청 및 CORS(원본 간 리소스 공유)

반짝임 아이콘 엔드포인트 구현

반짝임 아이콘 HTTPS 요청 형식

반짝임 아이콘 응답 JSON 형식

반짝임 아이콘 응답 유효성 검사

관련된 문서

추가 리소스