Сбор данных телеметрии для аналитики трафика поискаCollect telemetry data for search traffic analytics

Аналитика трафика поиска — это шаблон для сбора данных телеметрии о взаимодействии пользователей с приложением Когнитивного поиска Azure, таких как инициированные пользователем события щелчка мышью и ввода с клавиатуры.Search traffic analytics is a pattern for collecting telemetry about user interactions with your Azure Cognitive Search application, such as user-initiated click events and keyboard inputs. С помощью этих сведений можно определить эффективность решения для поиска, включая популярные условия поиска, частоту переходов, а также то, какие запросы выдают нулевые результаты.Using this information, you can determine the effectiveness of your search solution, including popular search terms, clickthrough rate, and which query inputs yield zero results.

Этот шаблон зависит от Application Insights (функция Azure Monitor) для сбора данных пользователей.This pattern takes a dependency on Application Insights (a feature of Azure Monitor) to collect user data. Для этого необходимо добавить инструментирование в код клиента, как описано в этой статье.It requires that you add instrumentation to your client code, as described in this article. Наконец, для анализа данных потребуется механизм создания отчетов.Finally, you will need a reporting mechanism to analyze the data. Рекомендуем использовать Power BI, однако можно использовать панель мониторинга приложения или любое средство, которое подключается к Application Insights.We recommend Power BI but you can use the Application Dashboard or any tool that connects to Application Insights.

Примечание

Шаблон, описанный в этой статье, предназначен для расширенных сценариев и навигации данных, создаваемых кодом, который добавляется в клиент.The pattern described in this article is for advanced scenarios and clickstream data generated by code you add to your client. Журналы служб, напротив, просты в настройке, предоставляют ряд метрик и могут выполняться на портале без кода.In contrast, service logs are easy to set up, provide a range of metrics, and can be done in the portal with no code required. Для всех сценариев рекомендуется включить ведение журнала.Enabling logging is recommended for all scenarios. Дополнительные сведения см. в разделе Сбор и анализ данных журналов.For more information, see Collect and analyze log data.

Определение соответствующих данных поискаIdentify relevant search data

Для получения полезных метрик трафика поиска необходимо организовать регистрацию некоторых пользовательских событий в приложении поиска.To have useful metrics for search traffic analytics, it's necessary to log some signals from the users of your search application. Эти события обозначают интересующее пользователей содержимое, которое является соответствующим для них.These signals signify content that users are interested in and that they consider relevant. Для аналитики трафика поиска такие события включают следующее.For search traffic analytics, these include:

  • События поиска, инициированные пользователями. Представляют интерес только поисковые запросы, инициируемые пользователем.User-generated search events: Only search queries initiated by a user are interesting. Поисковые запросы, используемые для заполнения аспектов, дополнительного содержимого или каких-либо внутренних сведений, не являются важными и ведут к искажению результатов поиска.Search requests used to populate facets, additional content or any internal information, are not important and they skew and bias your results.

  • Пользовательские события щелчка мышью. На странице результатов поиска щелчок мышью обычно означает, что документ является релевантным для конкретного поискового запроса.User-generated click events: On a search results page, a click event generally means that a document is a relevant result for a specific search query.

Связав события поиска и щелчка мышью с идентификатором корреляции, вы получите более глубокое представление о том, насколько хорошо работает функция поиска приложения.By linking search and click events with a correlation ID, you'll gain a deeper understanding of how well your application's search functionality is performing.

Добавление аналитики поискового трафикаAdd search traffic analytics

На странице портала службы Когнитивного поиска Azure в разделе "Поиск аналитики трафика" содержится памятка по следующему шаблону телеметрии.In the portal page for your Azure Cognitive Search service, the Search Traffic Analytics page contains a cheat sheet for following this telemetry pattern. На этой странице можно выбрать или создать ресурс Application Insights, получить ключ инструментирования, скопировать фрагменты кода, которые можно адаптировать для решения, и загрузить отчет Power BI, созданный на основе схемы, которая отражена в шаблоне.From this page, you can select or create an Application Insights resource, get the instrumentation key, copy snippets that you can adapt for your solution, and download a Power BI report that's built over the schema reflected in the pattern.

![Страница "Поиск аналитики трафика" на портале](media/search-traffic-analytics/azuresearch-trafficanalytics.png "Страница "Поиск аналитики трафика" на портале")Search Traffic Analytics page in the portal

1. Настройка Application Insights1 - Set up Application Insights

Выберите или создайте ресурс Application Insights (если у вас его нет).Select an existing Application Insights resource or create one if you don't have one already. При использовании страницы "Поиск аналитики трафика" можно скопировать ключ инструментирования, который требуется приложению для подключения к Application Insights.If you use the Search Traffic Analytics page, you can copy the instrumentation key your application needs to connect to Application Insights.

Получив ресурс Application Insights, можно выполнить инструкции для поддерживаемых языков и платформ, чтобы зарегистрировать приложение.Once you have an Application Insights resource, you can follow instructions for supported languages and platforms to register your app. Регистрация — это просто добавление ключа инструментирования из Application Insights в код, который настраивает связь.Registration is simply adding the instrumentation key from Application Insights to your code, which sets up the association. Ключ находится на портале или на странице "Поиск аналитики трафика" при выборе существующего ресурса.You can find the key in the portal, or from the Search Traffic Analytics page when you select an existing resource.

Ярлык, который подходит для некоторых типов проектов Visual Studio, представлен на следующих шагах.A shortcut that works for some Visual Studio project types is reflected in the following steps. Он служит для создания ресурса и регистрации приложения всего несколькими щелчками мышью.It creates a resource and registers your app in just a few clicks.

  1. Для разработки с помощью Visual Studio и ASP.NET откройте решение и выберите Проект > Добавить телеметрию Application Insights.For Visual Studio and ASP.NET development, open your solution and select Project > Add Application Insights Telemetry.

  2. Щелкните Начать работу.Click Get Started.

  3. Зарегистрируйте приложение, предоставив учетную запись Майкрософт, подписку Azure и ресурс Application Insights (по умолчанию используется новый ресурс).Register your app by providing a Microsoft account, Azure subscription, and an Application Insights resource (a new resource is the default). Щелкните Зарегистрировать.Click Register.

На этом этапе приложение настроено для мониторинга приложений, что означает, что все загрузки страниц отслеживаются с помощью метрик по умолчанию.At this point, your application is set up for application monitoring, which means all page loads are tracked with default metrics. Дополнительные сведения о предыдущих шагах см. в разделе Включение телеметрии Enable Application Insights на стороне сервера.For more information about the previous steps, see Enable Application Insights server-side telemetry.

2. Добавление инструментирования2 - Add instrumentation

На этом шаге выполняется инструментирование собственного приложения поиска с помощью ресурса Application Insights, созданного на предыдущем шаге.This step is where you instrument your own search application, using the Application Insights resource your created in the step above. Этот процесс состоит из четырех этапов, начиная с создания клиента телеметрии.There are four steps to this process, starting with creating a telemetry client.

Шаг 1. Создание клиента телеметрииStep 1: Create a telemetry client

Создайте объект, отправляющий события в Application Insights.Create an object that sends events to Application Insights. Можно добавить инструментирование в код приложения на стороне сервера или клиентский код, выполняемый в браузере, который представлен здесь как варианты C# и JavaScript (для других языков см. полный список поддерживаемых платформ и инфраструктур).You can add instrumentation to your server-side application code or client-side code running in a browser, expressed here as C# and JavaScript variants (for other languages, see the complete list of supported platforms and frameworks. Выберите подход, который обеспечивает нужную глубину информации.Choose the approach that gives you the desired depth of information.

Данные телеметрии на стороне сервера захватывают метрики на уровне приложения, например в приложениях, выполняющихся в качестве веб-службы в облаке или в качестве локального приложения в корпоративной сети.Server-side telemetry captures metrics at the application layer, for example in applications running as a web service in the cloud, or as an on-premises app on a corporate network. Данные телеметрии на стороне сервера захватывают события поиска и щелчка мышью, расположение документа в результатах и сведения о запросах, однако сбор данных будет ограничен любой информацией, доступной на этом уровне.Server-side telemetry captures search and click events, the position of a document in results, and query information, but your data collection will be scoped to whatever information is available at that layer.

В клиенте может иметься дополнительный код, который управляет вводом запросов, добавляет навигацию или включает контекст (например, запросы, инициированные с домашней страницы и страницы продукта).On the client, you might have additional code that manipulates query inputs, adds navigation, or includes context (for example, queries initiated from a home page versus a product page). Если это описание подходит для вашего решения, вы можете выбрать инструментирование на стороне клиента, чтобы в данных телеметрии отражались дополнительные сведения.If this describes your solution, you might opt for client-side instrumentation so that your telemetry reflects the additional detail. Сбор этой дополнительной информации выходит за рамки этого шаблона, однако вы можете ознакомиться со статьей Application Insights для веб-страниц, чтобы узнать подробнее.How this additional detail is collected goes beyond the scope of this pattern, but you can review Application Insights for web pages for more direction.

Использование C#Use C#

Для C# InstrumentationKey находится в конфигурации приложения, например в файле appsettings.json, если проект ASP.NET.For C#, the InstrumentationKey is found in your application configuration, such as appsettings.json if your project is ASP.NET. Если вы точно не знаете, где расположен ключ, обратитесь к инструкциям по регистрации.Refer back to the registration instructions if you are unsure of the key location.

private static TelemetryClient _telemetryClient;

// Add a constructor that accepts a telemetry client:
public HomeController(TelemetryClient telemetry)
{
    _telemetryClient = telemetry;
}

Использование JavaScriptUse JavaScript

<script type="text/javascript">var appInsights=window.appInsights||function(config){function r(config){t[config]=function(){var i=arguments;t.queue.push(function(){t[config].apply(t,i)})}}var t={config:config},u=document,e=window,o="script",s=u.createElement(o),i,f;s.src=config.url||"//az416426.vo.msecnd.net/scripts/a/ai.0.js";u.getElementsByTagName(o)[0].parentNode.appendChild(s);try{t.cookie=u.cookie}catch(h){}for(t.queue=[],i=["Event","Exception","Metric","PageView","Trace","Dependency"];i.length;)r("track"+i.pop());return r("setAuthenticatedUserContext"),r("clearAuthenticatedUserContext"),config.disableExceptionTracking||(i="onerror",r("_"+i),f=e[i],e[i]=function(config,r,u,e,o){var s=f&&f(config,r,u,e,o);return s!==!0&&t["_"+i](config,r,u,e,o),s}),t}
({
instrumentationKey: "<YOUR INSTRUMENTATION KEY>"
});
window.appInsights=appInsights;
</script>

Шаг 2. Запрос идентификатора поиска для корреляцииStep 2: Request a Search ID for correlation

Для корреляции поисковых запросов с щелчками необходим идентификатор корреляции, связывающий эти два различных события.To correlate search requests with clicks, it's necessary to have a correlation ID that relates these two distinct events. Служба Когнитивного поиска Azure предоставляет идентификатор поиска, когда он запрашивается с заголовком HTTP.Azure Cognitive Search provides you with a search ID when you request it with an HTTP header.

Наличие идентификатора поиска обеспечивает корреляцию метрик, созданных Когнитивным поиском Azure для самого запроса, с настраиваемыми метриками, которые вы регистрируете в Application Insights.Having the search ID allows correlation of the metrics emitted by Azure Cognitive Search for the request itself, with the custom metrics you are logging in Application Insights.

Использование C#Use C#

// This sample uses the .NET SDK https://www.nuget.org/packages/Microsoft.Azure.Search

var client = new SearchIndexClient(<SearchServiceName>, <IndexName>, new SearchCredentials(<QueryKey>)

// Use HTTP headers so that you can get the search ID from the response
var headers = new Dictionary<string, List<string>>() { { "x-ms-azs-return-searchid", new List<string>() { "true" } } };
var response = await client.Documents.SearchWithHttpMessagesAsync(searchText: searchText, searchParameters: parameters, customHeaders: headers);
string searchId = string.Empty;
if (response.Response.Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
    searchId = headerValues.FirstOrDefault();
}

Использование JavaScript (вызов REST API)Use JavaScript (calling REST APIs)

request.setRequestHeader("x-ms-azs-return-searchid", "true");
request.setRequestHeader("Access-Control-Expose-Headers", "x-ms-azs-searchid");
var searchId = request.getResponseHeader('x-ms-azs-searchid');

Шаг 3. Регистрация событий поискаStep 3: Log Search events

Каждый отправляемый поисковой запрос необходимо регистрировать в качестве события поиска, используя следующую схему настраиваемого события Application Insights.Every time that a search request is issued by a user, you should log that as a search event with the following schema on an Application Insights custom event. Не забывайте регистрировать только те поисковые запросы, которые созданы пользователем.Remember to log only user-generated search queries.

  • SearchServiceName: (строка) имя службы поискаSearchServiceName: (string) search service name
  • SearchId: (GUID) уникальный идентификатор поискового запроса (входит в ответ поиска)SearchId: (guid) unique identifier of the search query (comes in the search response)
  • IndexName: (строка) индекс службы поиска для запросаIndexName: (string) search service index to be queried
  • QueryTerms: (строка) слова для поиска, вводимые пользователемQueryTerms: (string) search terms entered by the user
  • ResultCount: (целое число) число возвращенных документов (входит в ответ поиска)ResultCount: (int) number of documents that were returned (comes in the search response)
  • ScoringProfile: (строка) имя используемого профиля оценки, если имеетсяScoringProfile: (string) name of the scoring profile used, if any

Примечание

Получите число запросов, создаваемых пользователем, добавив $count=true в поисковый запрос.Request the count of user generated queries by adding $count=true to your search query. Дополнительные сведения см. в статье Поиск документов (REST).For more information, see Search Documents (REST).

Использование C#Use C#

var properties = new Dictionary <string, string> 
{
    {"SearchServiceName", <service name>},
    {"SearchId", <search Id>},
    {"IndexName", <index name>},
    {"QueryTerms", <search terms>},
    {"ResultCount", <results count>},
    {"ScoringProfile", <scoring profile used>}
};
_telemetryClient.TrackEvent("Search", properties);

Использование JavaScriptUse JavaScript

appInsights.trackEvent("Search", {
  SearchServiceName: <service name>,
  SearchId: <search id>,
  IndexName: <index name>,
  QueryTerms: <search terms>,
  ResultCount: <results count>,
  ScoringProfile: <scoring profile used>
});

Шаг 4. Регистрация событий щелчка мышьюStep 4: Log Click events

Каждый щелчок документа — это событие, которое необходимо зарегистрировать для анализа поиска.Every time that a user clicks on a document, that's a signal that must be logged for search analysis purposes. Используйте пользовательские события Application Insights для регистрации этих событий по следующей схеме:Use Application Insights custom events to log these events with the following schema:

  • ServiceName: (строка) имя службы поискаServiceName: (string) search service name
  • SearchId: (GUID) уникальный идентификатор связанного поискового запросаSearchId: (guid) unique identifier of the related search query
  • DocId: (строка) идентификатор документаDocId: (string) document identifier
  • Position: (целое число) положение документа на странице результатов поискаPosition: (int) rank of the document in the search results page

Примечание

Позиция ссылается на количественный порядок в приложении.Position refers to the cardinal order in your application. Вы можете задать этот номер для сравнения, при условии, что он всегда один и тот же.You are free to set this number, as long as it's always the same, to allow for comparison.

Использование C#Use C#

var properties = new Dictionary <string, string> 
{
    {"SearchServiceName", <service name>},
    {"SearchId", <search id>},
    {"ClickedDocId", <clicked document id>},
    {"Rank", <clicked document position>}
};
_telemetryClient.TrackEvent("Click", properties);

Использование JavaScriptUse JavaScript

appInsights.trackEvent("Click", {
    SearchServiceName: <service name>,
    SearchId: <search id>,
    ClickedDocId: <clicked document id>,
    Rank: <clicked document position>
});

3. Анализ в Power BI3 - Analyze in Power BI

После инструментирования приложения и проверки правильности его подключения к Application Insights можно загрузить предварительно заданный шаблон отчета, чтобы проанализировать данные в Power BI Desktop.After you have instrumented your app and verified your application is correctly connected to Application Insights, you download a predefined report template to analyze data in Power BI desktop. В отчете содержатся предварительно заданные диаграммы и таблицы, которые можно использовать при анализе дополнительных данных, полученных для аналитики поискового трафика.The report contains predefined charts and tables useful for analyzing the additional data captured for search traffic analytics.

  1. В области навигации слева на панели мониторинга Когнитивного поиска Azure в разделе Параметры щелкните Поиск аналитики трафика.In the Azure Cognitive Search dashboard left-navigation pane, under Settings, click Search traffic analytics.

  2. На странице Поиск аналитики трафика на шаге 3 щелкните Получить Power BI Desktop, чтобы установить Power BI.On the Search traffic analytics page, in step 3, click Get Power BI Desktop to install Power BI.

    Получение отчетов Power BIGet Power BI reports

  3. На этой же странице щелкните Скачать отчет Power BI.On the same page, click Download Power BI report.

  4. В Power BI Desktop откроется отчет, и вам будет предложено подключиться к Application Insights и указать учетные данные.The report opens in Power BI Desktop, and you are prompted to connect to Application Insights and provide credentials. Сведения о подключении представлены на страницах портала Azure для вашего ресурса Application Insights.You can find connection information in the Azure portal pages for your Application Insights resource. Для учетных данных укажите те же имя пользователя и пароль, которые используются для входа на портал.For credentials, provide the same user name and password that you use for portal sign-in.

    Подключение к Application InsightsConnect to Application Insights

  5. Нажмите кнопку Загрузить.Click Load.

Этот отчет содержит диаграммы и таблицы, которые помогут вам принимать более взвешенные решения для улучшения производительности и релевантности поиска.The report contains charts and tables that help you make more informed decisions to improve your search performance and relevance.

Метрики содержат следующие элементы.Metrics included the following items:

  • Объем поиска и распространенные пары "условие —документ". Условия, в результате которых щелкают тот же документ, c упорядочиванием по щелчкам.Search volume and most popular term-document pairs: terms that result in the same document clicked, ordered by clicks.
  • Поисковые запросы без щелчков. Условия основных запросов, для которых не выполнялись щелчки.Searches without clicks: terms for top queries that register no clicks

На следующем снимке экрана показано, как может выглядеть встроенный отчет, если вы использовали все элементы схемы.The following screenshot shows what a built-in report might look like if you have used all of the schema elements.

Панель мониторинга Power BI для Когнитивного поиска AzurePower BI dashboard for Azure Cognitive Search

Дальнейшие действияNext steps

Выполните инструментирование приложения поиска для получения детальных и полезных сведений о службе поиска.Instrument your search application to get powerful and insightful data about your search service.

Вы можете узнать больше об Application Insights и перейти на страницу цен, чтобы получить дополнительные сведения о соответствующих уровнях служб.You can find more information on Application Insights and visit the pricing page to learn more about their different service tiers.

Узнайте больше о создании удивительных отчетов.Learn more about creating amazing reports. См. статью Начало работы с Power BI Desktop.See Getting started with Power BI Desktop for details.