검색에 봇 커넥트(미리 보기)

이 문서에서는 사용자 지정 페더레이션된 검색 공급자(봇의 전원)를 만들고 검색 채널에 연결하는 방법을 설명합니다. 테넌트 관리자가 테넌트에서 공급자를 사용하도록 설정하면 Office.com, SharePoint.com 및 Bing.com 엔터프라이즈 사용자 검색에 사용자 지정 검색 공급자의 결과가 포함될 수 있습니다.

Microsoft 페더레이션 검색 플랫폼을 사용하면 해당 정보를 Microsoft 365 인덱스와 병합할 필요 없이 정보가 Microsoft Search의 답변 및 수직 환경에 참여할 수 있도록 사용자 지정 페더레이션된 검색 공급자를 빌드할 수 있습니다. 자세한 내용은 Microsoft Federated Search Platform 및 Dynamics 365 페더레이션 검색(미리 보기)의 개발자 미리 보기 발표를 참조하세요.

참고 항목

검색 채널은 프라이빗 미리 보기로 제공됩니다. 액세스를 요청하려면 Microsoft Search 개발자 프라이빗 미리 보기 양식을 사용합니다. 질문 7에서 페더레이션 검색을 선택합니다.

검색 채널에 봇을 연결하려면 다음 단계가 필요합니다. 이러한 단계는 이 문서의 뒷부분에 자세히 설명되어 있습니다.

1. 검색 공급자로 작동하도록 봇을 구현합니다.
2. 봇에서 사용자가 로그인해야 하는 경우:
   1. Azure Portal에서 검색 플랫폼에 봇 API를 노출합니다.
   2. 봇 코드에서 생성된 범위 URI를 사용하여 사용자 토큰을 생성합니다.
3. Azure에 봇을 배포합니다.
4. 검색 채널을 봇에 추가합니다.
5. IT 관리자에게 봇 등록을 검토하고 테넌트에 봇을 게시하도록 요청합니다.

팁

프로덕션 환경에서 사용하도록 설정하기 전에 테스트 테넌트에서 검색 공급자를 사용하도록 설정하는 것이 좋습니다.

필수 조건

• Bot Framework 서비스의 기본 사항 및 Bot Framework SDK를 사용하여 봇을 만드는 방법에 대한 지식.
• 채널에 연결할 봇입니다.
• Azure 계정이 없는 경우 시작하기 전에 체험 계정을 만듭니다.

Bot Framework SDK에서 지원하는 언어로 봇을 구현할 수 있습니다. 이 문서에서는 C# 페더레이션 검색 봇 을 예로 사용합니다.

검색에 봇 API 노출

팁

이 단계는 봇이 보호된 사용자 리소스에 액세스해야 하는 경우에만 필요합니다.

일부 비즈니스 워크플로에서 봇은 사용자를 대신하여 작업을 수행하기 위해 사용자 자격 증명이 필요할 수 있습니다. 검색 채널에서 봇에 대한 SSO(Single Sign-On) 환경을 만들려면 검색 플랫폼이 사용자를 대신하여 Microsoft Entra ID에서 액세스 토큰을 보호하도록 허용해야 합니다.

봇에 대한 범위 URI 및 애플리케이션 ID를 생성하려면 다음을 수행합니다.

1. Azure Portal로 이동합니다.
2. 봇 리소스가 아직 없는 경우 Azure Bot 리소스를 만듭니다.
3. Microsoft Entra ID 서비스로 이동합니다.
4. 앱 등록 창으로 이동합니다.
5. 봇과 연결된 애플리케이션을 선택합니다.
6. API 노출 창으로 이동합니다.
7. 범위 추가를 선택합니다.
   1. 범위 추가 창에서 자동 생성된 애플리케이션 ID URI를 유지하는 것이 좋습니다. 저장하고 계속을 선택합니다.
   2. 범위 이름을 입력합니다.
   3. 동의할 수 있는 사용자에 대해 관리 및 사용자가 선호되지만 두 옵션 모두 작동합니다.
   4. 관리 동의 표시 이름과관리 동의 설명을 입력합니다.
   5. 필요에 따라 사용자 동의 표시 이름 및 사용자 동의 설명을 입력합니다.
   6. 상태가 사용으로 설정되어 있는지 확인합니다.
   7. 범위 추가를 선택합니다.
8. 클라이언트 애플리케이션 추가를 선택합니다.
   1. 클라이언트 애플리케이션 추가 창에서 클라이언트 ID를 81473081-50b9-469a-b9d8-303109583ecb검색 플랫폼의 클라이언트 ID로 설정합니다.
   2. 권한 있는 범위에서 이전 단계에서 만든 범위 URI를 선택합니다.
   3. 애플리케이션 추가를 선택합니다.
9. 개요 창으로 이동합니다. 애플리케이션 ID URI를 복사합니다. 검색 채널에 봇을 등록할 때 필요합니다.

봇 구현

검색 채널은 "application/search"라는 이름의 호출 활동으로 각 사용자 쿼리를 봇에 보냅니다. 봇은 호출 응답에서 쿼리 결과를 반환합니다. 검색 채널로 다시 전송된 쿼리 결과에 적응형 카드 형식을 사용합니다.

1. 프로젝트의 Bot Framework 및 적응형 카드 패키지를 최신 버전으로 업데이트합니다.
2. 필요에 따라 인증 코드를 추가하여 사용자 토큰을 생성합니다.
3. 포함할 각 데이터 원본에 대한 데이터 검색 방법을 구현합니다.
4. 결과를 표시하는 적응형 카드를 생성합니다.

검색 플랫폼 추적 ID 가져오기

검색 플랫폼은 봇에 보내는 각 쿼리에 고유한 추적 ID를 할당합니다. 플랫폼은 이를 호출 활동의 채널 데이터에 추가합니다. 요청의 추적 ID를 기록하도록 결정할 수 있습니다. 채널 데이터의 traceId 속성을 사용하여 추적 ID를 가져옵니다.

페더레이션된 검색 샘플에서 메서드는 SearchHelper.GetSearchTraceId 호출 활동에서 추적 ID를 가져오는 방법을 보여 줍니다.

인증 추가

검색에 봇 API를 노출하고 검색에 봇을 연결할 때 인증을 요청한 경우 활동의 채널 데이터에서 사용자 인증 토큰을 가져올 수 있습니다.

채널 데이터의 authorizations 속성에는 인증 토큰 목록이 포함될 수 있습니다. 검색에 봇 API를 노출하는 경우 목록에 대신 토큰이 포함됩니다. 목록의 토큰은 다음과 같은 구조를 갖습니다.

속성 이름	Type	설명
authType	정수	인증 토큰 유형: 0 알 수 없거나 기본값인 경우 또는 2 대신 토큰입니다.
token	string	인증 토큰 자체입니다.

페더레이션된 검색 샘플에서:

• 클래스와 열거형은 SearchBotAuthenticationTokenAuthenticationTypes 이 정보를 나타냅니다.
• 이 메서드는 SearchHelper.GetSearchOboToken 호출 작업에서 토큰을 가져오는 방법을 보여 줍니다.

토큰이 있으면 사용자에 대해 보호된 리소스를 요청할 때 사용할 수 있습니다. 대신 토큰을 사용하는 방법에 대한 자세한 내용은 Microsoft ID 플랫폼 및 OAuth 2.0 On-Behalf-Of 흐름을 참조하세요.

각 데이터 저장소 쿼리

검색 채널은 다음 구조의 JSON 개체를 나타내는 활동 속성의 value 쿼리 세부 정보와 함께 쿼리를 작업으로 invoke 봇에 보냅니다.

속성 이름	Type	설명
queryText	string	쿼리 텍스트입니다.
kind	string	쿼리 종류: 결과가 사용자 지정 세로 탭에 표시되는 경우 "검색"이거나, 결과가 모두 탭에 답변으로 표시될 때 "searchAnswer"입니다.
queryOptions	개체	페이지 매김에 사용되는 추가 쿼리 옵션입니다.
queryOptions.skip	정수	보낼 첫 번째 결과의 인덱스입니다.
queryOptions.top	정수	보낼 최대 결과 수입니다.

호출 응답에서 검색 결과를 반환합니다.

• 항상 호출 응답 개체의 Status 속성을 네트워크 연결이 정상임을 나타내는 속성 200으로 설정합니다. 개체의 Body 속성에는 별도의 상태 코드가 있습니다.

• 이 속성은 Body 다음 구조의 JSON 개체를 나타냅니다.

  속성 이름	Type	설명
  statusCode	정수	봇이 쿼리를 성공적으로 실행할 수 있는지 여부를 나타내는 데 사용되는 HTTP 상태 코드입니다.
  type	string	값 필드의 형식을 정의하는 호출 응답의 형식입니다. 검색 결과에는 "application/vnd.microsoft.search.searchResponse"를 사용하고 오류 메시지에는 "application/vnd.microsoft.error"를 사용합니다.
  value	개체	값에 해당하는 값 type입니다.

  오류 메시지의 경우 개체에는 value 다음이 포함됩니다.

  속성 이름	Type	설명
  코드	string	봇에서 정의한 오류 코드이거나 null 지정되지 않은 경우
  message	string	오류 메시지이거나 null 지정되지 않은 경우

  검색 결과의 경우 개체에는 value 다음이 포함됩니다.

  속성 이름	Type	설명
  results	검색 결과 개체의 배열	결과 또는 null 없는 경우.
  displayLayouts	표시 레이아웃 개체의 배열	표시 레이아웃이거나 null 없는 경우
  totalResultCount	정수	페이지 매김이 지원되는 경우 사용 가능한 총 결과입니다. 그렇지 않으면 . null
  moreResultsAvailable	부울	더 많은 결과를 사용할 수 있는지 여부를 나타냅니다.

  검색 결과 개체는 다음을 포함합니다.

  속성 이름	Type	설명
  value	string	이 검색 결과에 대한 고유 식별자 또는 값입니다.
  layoutId	string	이 결과에 사용할 표시 레이아웃의 ID입니다.
  data.searchResultText	string	이 결과의 텍스트입니다.

  표시 레이아웃 개체는 다음을 포함합니다.

  속성 이름	Type	설명
  layoutId	string	레이아웃 ID입니다.
  layoutBody	string	적응형 카드 JSON 개체로서의 레이아웃 본문입니다.

페더레이션된 검색 샘플SearchHelper.RunFederatedSearch에서 메서드는 호출 활동에서 쿼리 정보를 가져오는 방법과 호출 응답의 형식을 지정하는 방법을 보여 줍니다.

검색 결과 표시

검색 세로 및 결과 형식을 만들어 SharePoint, Office 및 Bing에서 검색할 때 표시되는 검색 결과를 사용자 지정할 수 있습니다. 수직을 사용하면 사용자가 볼 수 있는 권한이 있는 정보를 더 쉽게 찾을 수 있습니다. 자세한 내용은 지원되는 적응형 카드 요소 섹션을 참조하세요.

봇이 응답이 없는 쿼리를 수신하는 경우 응답에 빈 응답이 포함되어야 합니다.

Azure에서 봇 등록

검색 채널에 봇을 연결하려면 Azure에서 프로비전된 봇 리소스가 있어야 합니다. 자세한 내용은 Azure에 봇을 등록하는 방법 또는 Azure에서 봇을 배포하는 방법을 참조하세요.

검색에 봇 커넥트

다음 지침에서는 검색에 봇을 연결하는 방법을 보여 줍니다.

팁

프로덕션 환경에서 사용하도록 설정하기 전에 테스트 테넌트에서 검색 공급자를 사용하도록 설정하는 것이 좋습니다.

1. Azure Portal로 이동합니다.

2. 봇 리소스를 엽니다.

3. 채널(미리 보기) 창을 엽니다.

4. 검색을 선택합니다.

5. 검색 설정 탭에서 봇에 대한 정보를 입력합니다.

   

   1. 검색 공급자 메타데이터 아래에서 검색 UI에 표시할 이름을 입력합니다.

   2. 트리거 구에서 봇이 대답할 수 있는 쿼리를 나타내는 구를 정의합니다.

      참고 항목

      초기 릴리스의 경우 영어(en-US)만 사용할 수 있습니다.

      • 구가 .csv 포함된 파일을 업로드합니다. 파일에는 헤더가 없는 하나의 데이터 열이 포함되어야 합니다.
      • 언어 기본 설정 목록에서 트리거 구가 기록되는 언어를 선택합니다.

   3. 인증에서 검색 공급자에 사용자 인증이 필요한지 여부를 나타냅니다.

      • 인증이 필요한 경우 인증 URL을 입력합니다. 봇에 대한 API를 노출할 때 복사한 애플리케이션 ID URI를 사용합니다.

   4. 다음을 선택합니다.

6. [세로] 탭에서 검색 공급자의 결과가 검색 결과 페이지에서 고유한 사용자 지정 세로로 표시되도록 하려면 필드에 세로 이름을 입력하고, 그렇지 않으면 이 필드를 비워 둡니다. 그런 후에 다음을 선택합니다.
   검색 결과 페이지는 Office.com, SharePoint.com 및 Bing.com 대한 것입니다.

7. 테넌트 게시 탭에서 설정을 검토하고 게시 정보를 추가합니다.

   1. 검색 공급자 이름 및 샘플 쿼리를 검토합니다. 필요한 경우 이전 탭으로 돌아가서 이 정보를 변경합니다.
   2. 검색 공급자에 대한 설명을 입력합니다.
   3. 지원 연락처 전자 메일을 입력합니다. 검색 공급자에 대한 액세스 권한이 있는 개발자 또는 개발자 그룹의 이메일을 사용합니다.

8. 추가를 선택하여 IT 관리자의 승인을 요청합니다.

테넌트에서 검색 공급자 승인

테넌트에서 검색 공급자 승인은 Microsoft 365 관리 센터 검색 및 인텔리전스 페이지의 IT 관리자에 의해 이루어집니다.

연결 테스트

프로덕션 환경에서 사용하도록 설정하기 전에 테스트 테넌트에서 검색 공급자를 사용하도록 설정하는 것이 좋습니다.

검색 공급자 수정

IT 관리자가 검토를 위해 제출하기 전에 검색 공급자를 편집할 수 있습니다. 초기 요청이 거부되거나 서비스가 비활성화된 경우 이 작업을 수행해야 할 수 있습니다.

1. Azure Portal에서 편집하려는 검색 공급자가 포함된 봇 리소스로 이동합니다.
2. 채널(미리 보기) 창으로 이동합니다.
3. 검색 채널을 선택하고 편집을 선택합니다.
   1. Azure에서 검색 채널 창을 표시합니다. 이 창에서 설정을 편집할 수 있습니다.
   2. 트리거 구를 수정하려면 파일을 다운로드하고 로컬로 편집한 다음 파일을 업로드합니다.
   3. 편집을 마치면 추가를 다시 선택하여 IT 관리자가 검토할 검색 공급자를 제출합니다.

검색 공급자 삭제

봇 리소스에서 검색 채널을 제거하면 검색 공급자가 삭제됩니다.

봇에서 검색 채널을 제거하려면 다음을 수행합니다.

1. Azure Portal에서 봇 리소스로 이동합니다.
2. 채널(미리 보기) 창으로 이동합니다.
3. 검색 채널을 선택합니다.
4. 검색 채널 창의 맨 위에서 채널 삭제를 선택합니다.
5. 예를 선택하여 작업을 확인합니다.

봇 리소스를 삭제하려면 다음을 수행합니다.

1. Azure Portal에서 봇 리소스로 이동합니다.
2. 아직 수행하지 않은 경우 봇에서 검색 채널을 제거합니다.
3. 개요 창의 맨 위에서 삭제를 선택합니다.
4. OK를 선택하여 조작을 확정합니다.

추가 정보

검색 채널은 페더레이션 검색 및 적응형 카드 스키마를 사용합니다.

적응형 카드 스키마에 대한 자세한 내용은 봇 개발자를 위한 적응형 카드를 참조 하세요.

트리거 구 정보

트리거 구는 검색 플랫폼에서 쿼리를 봇에서 제공하는 사용자 지정 검색 공급자로 라우팅하는 데 사용하는 구입니다. 페더레이션된 검색은 발화가 트리거 구 중 하나와 거의 일치하는 경우 사용자의 발화를 검색 공급자에게 전달합니다.

팁

둘 이상의 검색 공급자를 사용할 수 있는 경우 페더레이션된 검색은 제공된 트리거 구와 사용자의 쿼리에 따라 하나만 선택합니다.

예를 들어 비행 일정 및 상태 관리하는 봇을 생각해 보세요.

1. 사용자가 봇을 참조하거나 사용하는 몇 가지 일반적인 방법을 생각해 보세요. 봇을 다른 사용자와 구분해야 합니다.

   학교 및 TV 프로그램에 적용할 수 있는 "시간표"와 같은 일반적인 용어 대신 "비행 시간 테이블" 및 "비행 일정"과 같은 보다 구체적인 구문을 사용합니다.

2. 출발 시간 및 현재 상태 같이 봇 기능의 범위를 다루는 다양한 구를 포함합니다.

   예를 들어 도착 또는 출발 시간 및 공항에 대한 쿼리를 포함합니다.

이러한 비행 일정 및 상태 봇에 대한 트리거 구에는 다음이 포함될 수 있습니다.

• 항공편 시간표
• 플라이트 상태
• 항공편 675 출발 시간
• 항공편 출발 시기
• 항공편 468 도착 시간
• 시애틀 타코마 항공편 상태
• 히드로 항공편 상태

또 다른 예로, 일기 예보 봇의 트리거 구에는 다음이 포함될 수 있습니다.

• 지역 일기 예보
• 날씨 정보
• 내일 날씨
• 10일 일기 예보
• 오늘의 최고
• 오늘의 비의 기회
• 내일 눈이 내릴 것 입니다.
• 내일 풍속
• 바깥쪽에 바람이 많이 부는가?
• 런던 날씨

지원되는 적응형 카드 요소

적응형 카드 스키마의 하위 집합은 페더레이션 검색에서 지원됩니다. 검색 결과의 서식 지정에 대한 자세한 내용은 검색 결과 사용자 지정 페이지를 참조 하세요.

지원에는 TextBlock, RichTextBlock, Image, ColumnSet, ImageSet 및 FactSet과 같은 적응형 카드 요소가 포함됩니다. 자세한 내용은 Microsoft Search의 검색 결과 레이아웃 관리 및 적응형 카드 스키마 탐색기를 참조하세요.

각 카드 JSON으로 직접 작성하거나 AdaptiveCards NuGet 패키지를 사용할 수 있습니다.

페더레이션 검색은 HTML을 지원하지 않습니다.

Important

페더레이션 검색은 HTML을 포함하는 적응형 카드 텍스트를 렌더링하지 않습니다.

Search 플랫폼에는 HTML 파서가 포함되어 있지 않습니다. 그러나 일부 태그를 제거하고 Html2Markdown NuGet 패키지를 사용하여 HTML을 Markdown 으로 변환할 수 있습니다.

1. 제거 <span> 및 <u> 요소.
2. <br> 요소를 단락(<p>) 요소로 대체 <div> 합니다.
3. 다시 기본 HTML을 Markdown으로 변환합니다.

다음 단계

• Bot 커넥트or Service의 채널 지원에 대한 자세한 내용은 봇을 채널에 커넥트 참조하세요.
• 봇 빌드에 대한 자세한 내용은 봇 작동 방식 및 Bot Framework SDK 빠른 시작을 사용하여 봇 만들기를 참조하세요.
• 봇 배포에 대한 자세한 내용은 봇 배포 및 지속적인 배포 설정을 참조하세요.