Samla in telemetridata för söktrafikanalys

Söktrafikanalys är ett mönster för att samla in telemetri om användarinteraktioner med ditt Azure Cognitive Search program, till exempel användarinitierade klickhändelser och tangentbordsinmatningar. Med den här informationen kan du fastställa effektiviteten i din söklösning, inklusive populära söktermer, klickfrekvens och vilka frågeindata som ger noll resultat.

Det här mönstret är beroende av Application Insights (en funktion i Azure Monitor) för att samla in användardata. Det kräver att du lägger till instrumentation i klientkoden, enligt beskrivningen i den här artikeln. Slutligen behöver du en rapporteringsmekanism för att analysera data. Vi rekommenderar Power BI, men du kan använda instrumentpanelen för program eller andra verktyg som ansluter till Insights.

Identifiera relevanta sökdata

Om du vill ha användbara mått för söktrafikanalys är det nödvändigt att logga några signaler från användarna av ditt sökprogram. Dessa signaler visar innehåll som användarna är intresserade av och som de anser vara relevanta. För söktrafikanalys inkluderar dessa:

• Användargenererade sökhändelser: Det är bara sökfrågor som initieras av en användare som är intressanta. Andra sökbegäranden, till exempel de som används för att fylla i fasetter eller hämta intern information, är inte viktiga. Se till att endast instrumentera användarinitierade händelser för att undvika skevhet eller bias i dina resultat.

• Användargenererade klickhändelser: På en sökresultatsida innebär en klickhändelse vanligtvis att ett dokument är ett relevant resultat för en specifik sökfråga.

Genom att länka sök- och klickhändelser med ett korrelations-ID får du en djupare förståelse för hur väl programmets sökfunktion fungerar.

Lägga till söktrafikanalys

På portalsidan för din Azure Cognitive Search tjänst öppnar du sidan Sök Trafikanalys för att få åtkomst till en lathund för att följa det här telemetrimönstret. På den här sidan kan du välja eller skapa en Application Insights-resurs, hämta instrumenteringsnyckeln, kopiera kodfragment som du kan anpassa för din lösning och ladda ned en Power BI-rapport som är byggd över det schema som återspeglas i mönstret.

1 – Konfigurera Insights

Välj en befintlig programresurs Insights eller skapa en om du inte redan har en. Om du använder sidan Sök Trafikanalys kan du kopiera instrumenteringsnyckeln som programmet behöver för att ansluta till Application Insights.

När du har en Application Insights-resurs kan du följa anvisningarna för språk och plattformar som stöds för att registrera din app. Registreringen är bara att lägga till instrumenteringsnyckeln från Application Insights till din kod, vilket uppsättningar upp associationen. Du hittar nyckeln i portalen eller på sidan Sök efter Trafikanalys du väljer en befintlig resurs.

En genväg som fungerar för vissa Visual Studio av projekttyper visas i följande steg. Den skapar en resurs och registrerar din app med bara några klickningar.

1. För Visual Studio och ASP.NET utveckling öppnar du din lösning och väljer lägg Project Lägg till > Insights Telemetri.

2. Klicka på Kom igång.

3. Registrera din app genom att ange Microsoft-konto, Azure-prenumeration och en Application Insights-resurs (en ny resurs är standard). Klicka på Registrera.

Nu har programmet ställts in för programövervakning, vilket innebär att alla sidinbelastningar spåras med standardmått. Mer information om föregående steg finns i Aktivera Insights telemetri på serversidan.

2 – Lägg till instrumentation

I det här steget instrumenterar du ditt eget sökprogram med hjälp av Insights som du skapade i steget ovan. Det finns fyra steg i den här processen som börjar med att skapa en telemetriklient.

Steg 1: Skapa en telemetriklient

Skapa ett -objekt som skickar händelser till Application Insights. Du kan lägga till instrumentation i programkoden på serversidan eller kod på klientsidan som körs i en webbläsare, uttryckt här som C# och JavaScript-varianter (för andra språk, se den fullständiga listan över plattformar och ramverk som stöds. Välj den metod som ger dig önskat djup med information.

Telemetri på serversidan samlar in mått på programnivå, till exempel i program som körs som en webbtjänst i molnet eller som en lokal app i ett företagsnätverk. Telemetri på serversidan samlar in sök- och klickhändelser, positionen för ett dokument i resultat och frågeinformation, men datainsamlingen är begränsad till den information som är tillgänglig i det lagret.

På klienten kan du ha ytterligare kod som manipulerar frågeindata, lägger till navigering eller inkluderar kontext (till exempel frågor som initieras från en startsida jämfört med en produktsida). Om detta beskriver din lösning kan du välja instrumentation på klientsidan så att din telemetri återspeglar ytterligare information. Hur den här ytterligare informationen samlas in ligger utanför omfånget för det här mönstret, men du kan granska Application Insights för webbsidor för mer riktning.

Använda C#

För C# ska InstrumentationKey definieras i din programkonfiguration, till exempel appsettings.json om projektet ASP.NET. Gå tillbaka till registreringsanvisningarna om du är osäker på nyckelplatsen.

private static TelemetryClient _telemetryClient;

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

Använda JavaScript

Det aktuella kodfragmentet (anges nedan) är version "5", versionen är kodad i kodfragmentet som sv:"#" och den aktuella versionen är också tillgänglig på GitHub.

<script type="text/javascript">
!function(T,l,y){var S=T.location,k="script",D="instrumentationKey",C="ingestionendpoint",I="disableExceptionTracking",E="ai.device.",b="toLowerCase",w="crossOrigin",N="POST",e="appInsightsSDK",t=y.name||"appInsights";(y.name||T[e])&&(T[e]=t);var n=T[t]||function(d){var g=!1,f=!1,m={initialize:!0,queue:[],sv:"5",version:2,config:d};function v(e,t){var n={},a="Browser";return n[E+"id"]=a[b](),n[E+"type"]=a,n["ai.operation.name"]=S&&S.pathname||"_unknown_",n["ai.internal.sdkVersion"]="javascript:snippet_"+(m.sv||m.version),{time:function(){var e=new Date;function t(e){var t=""+e;return 1===t.length&&(t="0"+t),t}return e.getUTCFullYear()+"-"+t(1+e.getUTCMonth())+"-"+t(e.getUTCDate())+"T"+t(e.getUTCHours())+":"+t(e.getUTCMinutes())+":"+t(e.getUTCSeconds())+"."+((e.getUTCMilliseconds()/1e3).toFixed(3)+"").slice(2,5)+"Z"}(),iKey:e,name:"Microsoft.ApplicationInsights."+e.replace(/-/g,"")+"."+t,sampleRate:100,tags:n,data:{baseData:{ver:2}}}}var h=d.url||y.src;if(h){function a(e){var t,n,a,i,r,o,s,c,u,p,l;g=!0,m.queue=[],f||(f=!0,t=h,s=function(){var e={},t=d.connectionString;if(t)for(var n=t.split(";"),a=0;a<n.length;a++){var i=n[a].split("=");2===i.length&&(e[i[0][b]()]=i[1])}if(!e[C]){var r=e.endpointsuffix,o=r?e.location:null;e[C]="https://"+(o?o+".":"")+"dc."+(r||"services.visualstudio.com")}return e}(),c=s[D]||d[D]||"",u=s[C],p=u?u+"/v2/track":d.endpointUrl,(l=[]).push((n="SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)",a=t,i=p,(o=(r=v(c,"Exception")).data).baseType="ExceptionData",o.baseData.exceptions=[{typeName:"SDKLoadFailed",message:n.replace(/\./g,"-"),hasFullStack:!1,stack:n+"\nSnippet failed to load ["+a+"] -- Telemetry is disabled\nHelp Link: https://go.microsoft.com/fwlink/?linkid=2128109\nHost: "+(S&&S.pathname||"_unknown_")+"\nEndpoint: "+i,parsedStack:[]}],r)),l.push(function(e,t,n,a){var i=v(c,"Message"),r=i.data;r.baseType="MessageData";var o=r.baseData;return o.message='AI (Internal): 99 message:"'+("SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details) ("+n+")").replace(/\"/g,"")+'"',o.properties={endpoint:a},i}(0,0,t,p)),function(e,t){if(JSON){var n=T.fetch;if(n&&!y.useXhr)n(t,{method:N,body:JSON.stringify(e),mode:"cors"});else if(XMLHttpRequest){var a=new XMLHttpRequest;a.open(N,t),a.setRequestHeader("Content-type","application/json"),a.send(JSON.stringify(e))}}}(l,p))}function i(e,t){f||setTimeout(function(){!t&&m.core||a()},500)}var e=function(){var n=l.createElement(k);n.src=h;var e=y[w];return!e&&""!==e||"undefined"==n[w]||(n[w]=e),n.onload=i,n.onerror=a,n.onreadystatechange=function(e,t){"loaded"!==n.readyState&&"complete"!==n.readyState||i(0,t)},n}();y.ld<0?l.getElementsByTagName("head")[0].appendChild(e):setTimeout(function(){l.getElementsByTagName(k)[0].parentNode.appendChild(e)},y.ld||0)}try{m.cookie=l.cookie}catch(p){}function t(e){for(;e.length;)!function(t){m[t]=function(){var e=arguments;g||m.queue.push(function(){m[t].apply(m,e)})}}(e.pop())}var n="track",r="TrackPage",o="TrackEvent";t([n+"Event",n+"PageView",n+"Exception",n+"Trace",n+"DependencyData",n+"Metric",n+"PageViewPerformance","start"+r,"stop"+r,"start"+o,"stop"+o,"addTelemetryInitializer","setAuthenticatedUserContext","clearAuthenticatedUserContext","flush"]),m.SeverityLevel={Verbose:0,Information:1,Warning:2,Error:3,Critical:4};var s=(d.extensionConfig||{}).ApplicationInsightsAnalytics||{};if(!0!==d[I]&&!0!==s[I]){var c="onerror";t(["_"+c]);var u=T[c];T[c]=function(e,t,n,a,i){var r=u&&u(e,t,n,a,i);return!0!==r&&m["_"+c]({message:e,url:t,lineNumber:n,columnNumber:a,error:i}),r},d.autoExceptionInstrumented=!0}return m}(y.cfg);function a(){y.onInit&&y.onInit(n)}(T[t]=n).queue&&0===n.queue.length?(n.queue.push(a),n.trackPageView({})):a()}(window,document,{
src: "https://js.monitor.azure.com/scripts/b/ai.2.min.js", // The SDK URL Source
// name: "appInsights", // Global SDK Instance name defaults to "appInsights" when not supplied
// ld: 0, // Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,
// useXhr: 1, // Use XHR instead of fetch to report failures (if available),
crossOrigin: "anonymous", // When supplied this will add the provided value as the cross origin attribute on the script tag
// onInit: null, // Once the application insights instance has loaded and initialized this callback function will be called with 1 argument -- the sdk instance (DO NOT ADD anything to the sdk.queue -- As they won't get called)
cfg: { // Application Insights Configuration
    instrumentationKey: "<YOUR INSTRUMENTATION KEY>"
}});
</script>

Steg 2: Begär ett sök-ID för korrelation

Om du vill korrelera sökbegäranden med klick måste du ha ett korrelations-ID som relaterar dessa två distinkta händelser. Azure Cognitive Search ger dig ett sök-ID när du begär det med ett HTTP-huvud.

Genom att ha sök-ID:t kan du korrelation av de mått som Azure Cognitive Search skicka för själva begäran, med de anpassade mått som du loggar in Insights.

Använda C# (nyare v11 SDK)

Den senaste SDK:n kräver användning av en HTTP-pipeline för att ange -huvudet enligt beskrivningen i det här exemplet.

// Create a custom policy to add the correct headers
public class SearchIdPipelinePolicy : HttpPipelineSynchronousPolicy
{
    public override void OnSendingRequest(HttpMessage message)
    {
        message.Request.Headers.SetValue("x-ms-azs-return-searchid", "true");
    }
}

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

SearchClientOptions clientOptions = new SearchClientOptions();
clientOptions.AddPolicy(new SearchIdPipelinePolicy(), HttpPipelinePosition.PerCall);

var client = new SearchClient("<SearchServiceName>", "<IndexName>", new AzureKeyCredential("<QueryKey>"), options: clientOptions);

Response<SearchResults<SearchDocument>> response = await client.SearchAsync<SearchDocument>(searchText: searchText, searchOptions: options);
string searchId = string.Empty;
if (response.GetRawResponse().Headers.TryGetValues("x-ms-azs-searchid", out IEnumerable<string> headerValues))
{
    searchId = headerValues.FirstOrDefault();
}

Använda C# (äldre v10 SDK)

// 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();
}

Använda JavaScript (anropa REST API:er)

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');

Steg 3: Loggsökningshändelser

Varje gång en sökbegäran utfärdas av en användare bör du logga den som en sökhändelse med följande schema i ett program Insights anpassad händelse. Kom ihåg att endast logga användargenererade sökfrågor.

• SearchServiceName:(sträng) söktjänstnamn
• SearchId:(guid) unik identifierare för sökfrågan (kommer i söksvaret)
• IndexName: söktjänstindex (sträng) som ska efterfrågas
• QueryTerms:(sträng) söktermer som anges av användaren
• ResultCount:(int) antal dokument som returnerades (kommer i söksvaret)
• ScoringProfile:(sträng) namnet på bedömningsprofilen som används, om det finns

Använda 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);

Använda JavaScript

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

Steg 4: Logga klickhändelser

Varje gång en användare klickar på ett dokument är det en signal som måste loggas i sökanalyssyfte. Använd Program Insights anpassade händelser för att logga dessa händelser med följande schema:

• ServiceName:(sträng) söktjänstnamn
• SearchId:(guid) unik identifierare för den relaterade sökfrågan
• DocId:(sträng) dokumentidentifierare
• Position: (int) rangordningen för dokumentet på sökresultatsidan

Använda 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);

Använda JavaScript

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

3 – Analysera i Power BI

När du har instrumenterat appen och kontrollerat att programmet är korrekt anslutet till Application Insights laddar du ned en fördefinierad rapportmall för att analysera data i Power BI desktop. Rapporten innehåller fördefinierade diagram och tabeller som är användbara för att analysera ytterligare data som samlas in för söktrafikanalys.

1. I det Azure Cognitive Search vänstra navigeringsfönstret i instrumentpanelen, under Inställningar , klickar du på Sök trafikanalys.

2. På sidan Sök trafikanalys i steg 3 klickar du på Hämta Power BI Desktop installera Power BI.

   

3. På samma sida klickar du på Ladda Power BI rapport.

4. Rapporten öppnas i Power BI Desktop och du uppmanas att ansluta till Application Insights och ange autentiseringsuppgifter. Du hittar anslutningsinformation på de Azure Portal sidorna för din Application Insights resurs. För autentiseringsuppgifter anger du samma användarnamn och lösenord som du använder för inloggning på portalen.

   

5. Klicka på Läs in.

Rapporten innehåller diagram och tabeller som hjälper dig att fatta mer välgrundade beslut för att förbättra sökresultatens prestanda och relevans.

Måtten innehöll följande objekt:

• Sökvolym och de populäraste termdokumentparen: termer som resulterar i samma dokumentklickade, sorterade efter klick.
• Sökningar utan klick: villkor för de viktigaste frågorna som inte registrerar några klick

Följande skärmbild visar hur en inbyggd rapport kan se ut om du har använt alla schemaelement.

Nästa steg

Instrumentera sökprogrammet för att få kraftfulla och insiktsfulla data om din söktjänst.

Du hittar mer information om program Insights på prissättningssidan för att lära dig mer om deras olika tjänstnivåer.

Läs mer om att skapa fantastiska rapporter. Se Komma igång med Power BI Desktop för mer information.