Windows 검색 웹 검색 공급자

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

타사 검색 공급자 통합을 사용하는 Windows 검색 UI의 스크린샷

검색 공급자는 OS에서 검색 공급자를 등록하는 데 필요한 정보를 제공하는 패키지 매니페스트 파일을 사용하여 MSIX 패키지를 만들어 검색 환경과 통합합니다. 설치 후 검색 공급자는 기본적으로 Windows Search 환경에서 사용하도록 설정됩니다. Windows 설정에서 사용자는 설치된 검색 공급자를 사용하거나 사용하지 않도록 설정하고 검색 결과에서 공급자의 순서를 관리할 수 있습니다. 사용자는 Windows 설정에서 settings > Apps > 설치된 앱 페이지를 통해 검색 공급자를 제거할 수 있습니다.

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

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

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

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

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

검색 공급자 앱 확장

앱 패키지 매니페스트 파일은 Windows 앱에 대한 다양한 확장 및 기능을 지원합니다. 앱 패키지 매니페스트 형식은 패키지 매니페스트 스키마 참조에 설명된 스키마 집합에 의해 정의됩니다. 검색 공급자는 uap3:AppExtension 내에서 등록 정보를 선언합니다. 확장의 Name 특성은 "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:속성

  엔드포인트

  프로토콜

엔드포인트

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

프로토콜

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

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

다음은 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>
		  </uap3:Properties>
	  </uap3:AppExtension>
  </uap3:Extension>
  <uap:Extension Category="windows.protocol">
	  <uap:Protocol Name="customsearch"/>
  </uap:Extension>

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

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

제안 HTTPS 요청 형식

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

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

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

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

제안 HTTPS 응답 헤더

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

  • Access-Control-Allow-Origin: https://www.bing.com
  • Access-Control-Allow-Credentials: true (인증 정보를 허용하는 접근 제어)
  • Access-Control-Allow-Methods: GET
  • Content-Type: application/json; charset=utf-8
  • 콘텐츠 길이: [응답의 정확한 길이여야 합니다.]

제안 응답 JSON 형식

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

열쇠 설명
제안 사용자 쿼리와 연결된 제안을 나타내는 키가 Attributes 있는 JSON 개체 목록을 포함합니다.
특성 제안의 특성을 포함합니다.
유알엘 (URL) 공급자 웹 사이트의 검색 제안에 대한 URL입니다.
문의 검색 제안과 연결된 사용자 쿼리입니다.
미리보기창URL 제안의 HTML 미리 보기를 검색할 수 있는 미리 보기 엔드포인트의 URL입니다.
문자 메시지 제안에 대한 텍스트 설명입니다. 
{"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 검색 공급자 미리 보기 엔드포인트 구현

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

HTTPS 요청 형식 미리 보기

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

https://contoso.com?Darkschemeovr=1

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

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

HTTPS 응답 헤더 미리 보기

  • Access-Control-Allow-Origin: https://www.bing.com
  • Access-Control-Allow-Credentials: true (인증 정보를 허용하는 접근 제어)
  • Access-Control-Allow-Methods: GET
  • Content-Type: text/html; charset=utf-8
  • 콘텐츠 길이: [미리 보기 html의 정확한 길이여야 합니다.]

OPTIONS 요청 및 교차 출처 리소스 공유 (CORS)

Windows Search 클라이언트는 각 GET 요청 전에 HTTP 옵션(CORS 실행 전) 요청을 보냅니다. 검색 공급자는 OPTIONS 요청 메서드를 지원하고 HTTP 200 OK로 응답해야 합니다.

  • Last updated on