Telemetriegegevens verzamelen voor analyse van zoekverkeer

Analyse van zoekverkeer is een patroon voor het verzamelen van telemetrie over gebruikersinteracties met uw Azure Cognitive Search-toepassing, zoals door de gebruiker geïnitieerde klikgebeurtenissen en toetsenbordinvoer. Aan de hand van deze informatie kunt u de effectiviteit van uw zoekoplossing bepalen, waaronder populaire zoektermen, klikfrequentie en welke query-invoer geen resultaten oplevert.

Dit patroon is afhankelijk van Application Insights (een functie van Azure Monitor )om gebruikersgegevens te verzamelen. Hiervoor moet u instrumentatie toevoegen aan uw clientcode, zoals beschreven in dit artikel. Ten slotte hebt u een rapportagemechanisme nodig om de gegevens te analyseren. We raden Power BI aan, maar u kunt het toepassingsdashboard gebruiken of een hulpprogramma dat verbinding maakt met Application Insights.

Relevante zoekgegevens identificeren

Als u nuttige metrische gegevens wilt hebben voor analyse van zoekverkeer, is het nodig om enkele signalen van de gebruikers van uw zoektoepassing te kunnen inloggen. Deze signalen geven aan dat gebruikers geïnteresseerd zijn in inhoud en dat ze relevant achten. Dit zijn onder andere de volgende voor analyse van zoekverkeer:

• Door de gebruiker gegenereerde zoekgebeurtenissen: Alleen zoekquery's die door een gebruiker zijn geïnitieerd, zijn interessant. Andere zoekaanvragen, zoals aanvragen die worden gebruikt om facetten te vullen of interne informatie op te halen, zijn niet belangrijk. Zorg ervoor dat u alleen door de gebruiker geïnitieerde gebeurtenissen instrumenteert om scheefheid of bias in uw resultaten te voorkomen.

• Door de gebruiker gegenereerde klikgebeurtenissen: Op een pagina met zoekresultaten betekent een klikgebeurtenis in het algemeen dat een document een relevant resultaat is voor een specifieke zoekquery.

Door zoek- en klikgebeurtenissen te koppelen aan een correlatie-id, krijgt u meer inzicht in hoe goed de zoekfunctionaliteit van uw toepassing presteert.

Analyse van zoekverkeer toevoegen

Open op de portalpagina van Azure Cognitive Search service de pagina Traffic Analytics zoeken voor toegang tot een cheatsheet voor het volgen van dit telemetriepatroon. Op deze pagina kunt u een Application Insights-resource selecteren of maken, de instrumentatiesleutel op halen, fragmenten kopiëren die u voor uw oplossing kunt aanpassen en een Power BI-rapport downloaden dat is gebouwd op basis van het schema dat in het patroon wordt weergegeven.

1 - Application Insights

Selecteer een bestaande Application Insights resource of maak er een als u er nog geen hebt. Als u de pagina Search Traffic Analytics gebruikt, kunt u de instrumentatiesleutel kopiëren die uw toepassing nodig heeft om verbinding te maken met Application Insights.

Zodra u een Application Insights resource hebt, kunt u instructies voor ondersteunde talen en platforms volgen om uw app te registreren. Registratie is gewoon het toevoegen van de instrumentatiesleutel uit Application Insights aan uw code, waarmee de associatie wordt gemaakt. U vindt de sleutel in de portal of op de pagina Traffic Analytics zoeken wanneer u een bestaande resource selecteert.

Een snelkoppeling die voor sommige Visual Studio projecttypen werkt, wordt in de volgende stappen weergegeven. Er wordt een resource gemaakt en uw app wordt in slechts enkele klikken geregistreerd.

1. Voor Visual Studio en ASP.NET-ontwikkeling opent u uw oplossing en selecteert u Project > Toepassing toevoegen Insights Telemetrie.

2. Klik op Aan de slag.

3. Registreer uw app door een Microsoft-account, een Azure-abonnement en een Application Insights-resource op te geven (een nieuwe resource is de standaardinstelling). Klik op Registreren.

Op dit moment is uw toepassing ingesteld voor toepassingsbewaking, wat betekent dat alle paginaladingen worden bij gehouden met standaard metrische gegevens. Zie Enable Application Insights server side telemetry (Telemetrieaan de serverzijde inschakelen) voor meer informatie over de vorige stappen.

2 - Instrumentatie toevoegen

In deze stap instrumenteren we uw eigen zoektoepassing met behulp van de Application Insights resource die u in de bovenstaande stap hebt gemaakt. Dit proces bestaat uit vier stappen, te beginnen met het maken van een telemetrieclient.

Stap 1: een telemetrieclient maken

Maak een -object dat gebeurtenissen naar Application Insights. U kunt instrumentatie toevoegen aan uw toepassingscode aan de serverzijde of code aan de clientzijde die wordt uitgevoerd in een browser, hier uitgedrukt als C#- en JavaScript-varianten (zie de volledige lijst met ondersteunde platforms en frameworksvoor andere talen. Kies de aanpak die u de gewenste diepte van informatie biedt.

Telemetrie aan de serverzijde legt metrische gegevens vast op de toepassingslaag, bijvoorbeeld in toepassingen die worden uitgevoerd als een webservice in de cloud of als een on-premises app in een bedrijfsnetwerk. Telemetrie aan de serverzijde legt zoek- en klikgebeurtenissen vast, de positie van een document in de resultaten en het opvragen van gegevens, maar uw gegevensverzameling wordt beperkt tot alle informatie die beschikbaar is op die laag.

Op de client hebt u mogelijk aanvullende code die query-invoer bewerkt, navigatie toevoegt of context bevat (bijvoorbeeld query's die zijn gestart vanaf een startpagina versus een productpagina). Als dit uw oplossing beschrijft, kunt u kiezen voor instrumentatie aan de clientzijde, zodat uw telemetrie de aanvullende details weerspiegelt. Hoe deze aanvullende details worden verzameld, gaat verder dan het bereik van dit patroon, maar u kunt Application Insights voor webpagina's bekijken voor meer richting.

C# gebruiken

Voor C# moet de InstrumentationKey worden gedefinieerd in uw toepassingsconfiguratie, zoals appsettings.json als uw project ASP.NET. Raadpleeg de registratie-instructies als u niet zeker weet wat de sleutellocatie is.

private static TelemetryClient _telemetryClient;

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

JavaScript gebruiken

Het huidige fragment (hieronder vermeld) is versie 5, de versie wordt in het fragment gecodeerd als sv:"#" en de huidige versie is ook beschikbaar op 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>

Stap 2: een zoek-id voor correlatie aanvragen

Als u zoekaanvragen wilt correleren met klikken, moet u een correlatie-id hebben die deze twee verschillende gebeurtenissen relateren. Azure Cognitive Search geeft u een zoek-id wanneer u deze aanvraagt met een HTTP-header.

Als u de zoek-id hebt, is correlatie mogelijk van de metrische gegevens die door Azure Cognitive Search worden uitgezonden voor de aanvraag zelf, met de aangepaste metrische gegevens die u in Application Insights.

C# gebruiken (nieuwere v11 SDK)

Voor de nieuwste SDK is het gebruik van een HTTP-pijplijn vereist om de header in te stellen zoals beschreven in dit voorbeeld.

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

C# gebruiken (oudere 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();
}

JavaScript gebruiken (REST API's aanroepen)

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

Stap 3: Zoekgebeurtenissen in logboeken

Telkens wanneer een zoekaanvraag wordt uitgegeven door een gebruiker, moet u dat als een zoekgebeurtenis met het volgende schema op een aangepaste toepassingsgebeurtenis Insights logboeken. Vergeet niet om alleen door gebruikers gegenereerde zoekquery's te logboeken.

• SearchServiceName: zoekservicenaam (tekenreeks)
• SearchId:(guid) unieke id van de zoekquery (wordt geleverd in het zoekreactie)
• IndexName:(tekenreeks) zoekservice-index die moet worden opgevraagd
• QueryTerms: zoektermen (tekenreeks) die door de gebruiker zijn ingevoerd
• ResultCount:(int) aantal documenten dat is geretourneerd (komt in het zoekresultaat)
• ScoringProfile:(tekenreeks)-naam van het gebruikte scoreprofiel, indien van toepassing

C# gebruiken

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

JavaScript gebruiken

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

Stap 4: Op gebeurtenissen in logboek klikken

Telkens als een gebruiker op een document klikt, is dat een signaal dat moet worden geregistreerd voor zoekanalysedoeleinden. Gebruik Toepassingsgebeurtenissen Insights om deze gebeurtenissen met het volgende schema te logboeken:

• ServiceName: zoekservicenaam (tekenreeks)
• SearchId:(guid) unieke id van de gerelateerde zoekquery
• DocId: document-id (tekenreeks)
• Positie:(int) positie van het document op de pagina met zoekresultaten

C# gebruiken

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

JavaScript gebruiken

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

3 - Analyseren in Power BI

Nadat u uw app hebt instrumenteerd en hebt gecontroleerd of uw toepassing correct is verbonden met Application Insights, downloadt u een vooraf gedefinieerde rapportsjabloon om gegevens te analyseren in Power BI Desktop. Het rapport bevat vooraf gedefinieerde grafieken en tabellen die nuttig zijn voor het analyseren van de aanvullende gegevens die zijn vastgelegd voor analyse van zoekverkeer.

1. Klik in Azure Cognitive Search linkernavigatievenster van het dashboard onder Instellingen op Verkeersanalyse doorzoeken.

2. Klik op de pagina Verkeersanalyses doorzoeken in stap 3 op Power BI Desktop om de Power BI.

   

3. Klik op dezelfde pagina op Power BI downloaden.

4. Het rapport wordt geopend in Power BI Desktop en u wordt gevraagd verbinding te maken met Application Insights referenties op te geven. U vindt de verbindingsgegevens op Azure Portal pagina's voor uw Application Insights resource. Geef voor referenties dezelfde gebruikersnaam en hetzelfde wachtwoord op die u gebruikt voor het aanmelden bij de portal.

   

5. Klik op Laden.

Het rapport bevat grafieken en tabellen die u helpen beter geïnformeerde beslissingen te nemen om uw zoekprestaties en relevantie te verbeteren.

Metrische gegevens omvatten de volgende items:

• Zoekvolume en populairste termenparen: termen die resulteren in hetzelfde document, geklikt, geordend op klikken.
• Zoekopdrachten zonder klikken: termen voor de belangrijkste query's die geen klikken registreren

In de volgende schermopname ziet u hoe een ingebouwd rapport eruit kan zien als u alle schema-elementen hebt gebruikt.

Volgende stappen

Instrumenteren van uw zoektoepassing om krachtige en inzichtelijke gegevens over uw zoekservice op te halen.

U vindt meer informatie over Application Insights en gaat naar de pagina met prijzen voor meer informatie over de verschillende servicelagen.

Meer informatie over het maken van geweldige rapporten. Zie Aan de slag met Power BI Desktop voor meer informatie.