Importazione di dati in AnalyticsImport data into Analytics

Importare i dati tabulari in Analytics, ad esempio per creare un join con Application Insights Telemetry dall'app o altro in modo che sia possibile eseguire l'analisi come flusso separato.Import any tabular data into Analytics, either to join it with Application Insights telemetry from your app, or so that you can analyze it as a separate stream. Analytics è un linguaggio di query avanzato ideale per l'analisi dei flussi di timestamp a volume elevato di telemetria.Analytics is a powerful query language well-suited to analyzing high-volume timestamped streams of telemetry.

È possibile importare dati in Analytics usando uno schema personalizzato.You can import data into Analytics using your own schema. Non è necessario usare gli schemi di Application Insights standard, come la richiesta o la traccia.It doesn't have to use the standard Application Insights schemas such as request or trace.

È possibile importare i file JSON o DSV (Delimiter-Separated Values: virgola, punto e virgola o tabulazione).You can import JSON or DSV (delimiter-separated values - comma, semicolon or tab) files.

L'importazione in Analytics è utile in tre situazioni:There are three situations where importing to Analytics is useful:

  • Creare un join con la telemetria dell'app.Join with app telemetry. Ad esempio, è possibile importare una tabella che associa gli URL dal sito Web a titoli di pagine più leggibili.For example, you could import a table that maps URLs from your website to more readable page titles. In Analytics è possibile creare un report grafico del dashboard che mostra le dieci pagine più visitate nel sito Web.In Analytics, you can create a dashboard chart report that shows the ten most popular pages in your website. Consente ora di visualizzare i titoli delle pagine anziché gli URL.Now it can show the page titles instead of the URLs.
  • Correlare la telemetria dell'applicazione con altre origini, ad esempio il traffico di rete, i dati del server o i file di log della rete CDN.Correlate your application telemetry with other sources such as network traffic, server data, or CDN log files.
  • Applicare Analytics a un flusso di dati separato.Apply Analytics to a separate data stream. Application Insights Analytics è uno strumento potente, che funziona bene con flussi di timestamp frammentati, spesso in modo più efficace di SQL.Application Insights Analytics is a powerful tool, that works well with sparse, timestamped streams - much better than SQL in many cases. Se si dispone di tale flusso da un'altra origine, è possibile analizzarlo con Analytics.If you have such a stream from some other source, you can analyze it with Analytics.

L'invio di dati all'origine dati è semplice.Sending data to your data source is easy.

  1. (Una volta) Definire lo schema dei dati in un'origine dati.(One time) Define the schema of your data in a 'data source'.
  2. (Periodicamente) Caricare i dati nell'Archiviazione di Azure e chiamare l'API REST per segnalare che nuovi dati sono in attesa per l'inserimento.(Periodically) Upload your data to Azure storage, and call the REST API to notify us that new data is waiting for ingestion. Entro pochi minuti i dati sono disponibili per le query di Analytics.Within a few minutes, the data is available for query in Analytics.

La frequenza del processo di caricamento viene definita dall'utente e dalla velocità con cui si vuole rendere disponibili i dati per le query.The frequency of the upload is defined by you and how fast would you like your data to be available for queries. È più efficiente caricare i dati in blocchi più grandi, ma non maggiori di 1 GB.It is more efficient to upload data in larger chunks, but not larger than 1GB.

Prima di iniziareBefore you start

Sono necessari:You need:

  1. Una risorsa di Application Insights in Microsoft Azure.An Application Insights resource in Microsoft Azure.

    • Se si vuole analizzare i dati separatamente da altra telemetria, creare una nuova risorsa di Application Insights.If you want to analyze your data separately from any other telemetry, create a new Application Insights resource.
    • Se si sta eseguendo il join o il confronto dei dati con la telemetria di un'app già configurata con Application Insights, è possibile usare la risorsa per questa app.If you're joining or comparing your data with telemetry from an app that is already set up with Application Insights, then you can use the resource for that app.
    • Accesso del collaboratore o del proprietario a questa risorsa.Contributor or owner access to that resource.
  2. nell'archiviazione di Azure.Azure storage. Si caricano i dati in Archiviazione di Azure e Analytics recupera i dati da questa posizione.You upload to Azure storage, and Analytics gets your data from there.

    • È consigliabile creare un account di archiviazione dedicato per i BLOB.We recommend you create a dedicated storage account for your blobs. Se i BLOB sono condivisi con altri processi, la lettura dei BLOB da parte dei processi richiede più tempo.If your blobs are shared with other processes, it takes longer for our processes to read your blobs.

Definire lo schemaDefine your schema

Prima di poter importare dati, è necessario definire un'origine dati che specifica lo schema dei dati.Before you can import data, you must define a data source, which specifies the schema of your data. È possibile avere fino a 50 origini dati in una singola risorsa di Application InsightsYou can have up to 50 data sources in a single Application Insights resource

  1. Avviare la Creazione guidata origine dati.Start the data source wizard. Usare il pulsante "Aggiungi nuova origine dati".Use "Add new data source" button. In alternativa, fare clic sul pulsante Impostazioni nell'angolo in alto a destra e scegliere "Origini dati" nel menu a discesa.Alternatively - click on settings button in right upper corner and choose "Data Sources" in dropdown menu.

    Aggiungere la nuova origine dati

    Immettere un nome per la nuova origine dati.Provide a name for your new data source.

  2. Definire il formato dei file da caricare.Define format of the files that you will upload.

    È possibile definire il formato manualmente o caricare un file di esempio.You can either define the format manually, or upload a sample file.

    Se i dati sono in formato CSV, la prima riga dell'esempio può essere costituita da intestazioni di colonna.If the data is in CSV format, the first row of the sample can be column headers. Nel passaggio successivo è possibile modificare i nomi dei campi.You can change the field names in the next step.

    L'esempio deve includere almeno 10 righe o record di dati.The sample should include at least 10 rows or records of data.

    I nomi di colonna o di campo devono essere alfanumerici (senza spazi o punteggiatura).Column or field names should have alphanumeric names (without spaces or punctuation).

    Caricare un file di esempio

  3. Esaminare lo schema della procedura guidata.Review the schema that the wizard has got. Se i tipi sono stati dedotti da un campione, è possibile che si debbano modificare i tipi dedotti delle colonne.If it inferred the types from a sample, you might need to adjust the inferred types of the columns.

    Esaminare lo schema dedotto

    • Facoltativo. Caricare una definizione dello schema.(Optional.) Upload a schema definition. Vedere il formato riportato di seguito.See the format below.

    • Selezionare un timestamp.Select a Timestamp. Tutti i dati in Analytics devono avere un campo di timestamp.All data in Analytics must have a timestamp field. Il tipo deve essere datetime, ma non deve essere denominato "timestamp".It must have type datetime, but it doesn't have to be named 'timestamp'. Se i dati includono una colonna contenente una data e ora in formato ISO, scegliere questa opzione come colonna di timestamp.If your data has a column containing a date and time in ISO format, choose this as the timestamp column. In caso contrario, scegliere "as data arrived" e il processo di importazione aggiungerà un campo di timestamp.Otherwise, choose "as data arrived", and the import process will add a timestamp field.

  4. Creare l'origine dati.Create the data source.

Formato del file di definizione dello schemaSchema definition file format

Invece di modificare lo schema nell'interfaccia utente, è possibile caricare la definizione dello schema da un file.Instead of editing the schema in UI, you can load the schema definition from a file. Il formato della definizione dello schema è il seguente:The schema definition format is as follows:

Formato delimitatoDelimited format

[ 
    {"location": "0", "name": "RequestName", "type": "string"}, 
    {"location": "1", "name": "timestamp", "type": "datetime"}, 
    {"location": "2", "name": "IPAddress", "type": "string"} 
] 

Formato JSONJSON format

[ 
    {"location": "$.name", "name": "name", "type": "string"}, 
    {"location": "$.alias", "name": "alias", "type": "string"}, 
    {"location": "$.room", "name": "room", "type": "long"} 
]

Ogni colonna viene identificata da posizione, nome e tipo.Each column is identified by the location, name and type.

  • Location: per un formato file delimitato, indica la posizione del valore di cui è stato eseguito il mapping.Location – For delimited file format it is the position of the mapped value. Per il formato JSON, è il jpath della chiave di cui è stato eseguito il mapping.For JSON format, it is the jpath of the mapped key.
  • Name: nome visualizzato della colonna.Name – the displayed name of the column.
  • Type: tipo di dati della colonna.Type – the data type of that column.

Se sono stati usati dati di esempio e se il formato file è delimitato, la definizione dello schema deve eseguire il mapping di tutte le colonne e aggiungere nuove colonne alla fine.In case a sample data was used and file format is delimited, the schema definition must map all columns and add new columns at the end.

JSON consente il mapping parziale dei dati, pertanto la definizione dello schema del formato JSON non deve necessariamente eseguire il mapping di ogni chiave individuata nei dati di esempio.JSON allows partial mapping of the data, therefore the schema definition of JSON format doesn’t have to map every key which is found in a sample data. Può inoltre eseguire il mapping di colonne non appartenenti ai dati di esempio.It can also map columns which are not part of the sample data.

Importa datiImport data

Per importare i dati, caricarli in Archiviazione di Azure, creare una chiave di accesso corrispondente ed eseguire una chiamata API REST.To import data, you upload it to Azure storage, create an access key for it, and then make a REST API call.

Aggiungere la nuova origine dati

È possibile eseguire manualmente il processo seguente o configurare un sistema automatizzato per eseguire questa operazione a intervalli regolari.You can perform the following process manually, or set up an automated system to do it at regular intervals. È necessario seguire questi passaggi per ogni blocco di dati da importare.You need to follow these steps for each block of data you want to import.

  1. Caricare dati nell'Archiviazione BLOB di Azure.Upload the data to Azure blob storage.

    • I BLOB possono essere di qualsiasi dimensione, fino a 1 GB non compressi.Blobs can be any size up to 1GB uncompressed. I BLOB di centinaia di MB sono ideali dal punto di vista delle prestazioni.Large blobs of hundreds of MB are ideal from a performance perspective.
    • È possibile comprimerli con Gzip per migliorare i tempi di caricamento e la latenza per i dati che devono essere disponibili per la query.You can compress it with Gzip to improve upload time and latency for the data to be available for query. Usare l'estensione del nome file .gz.Use the .gz filename extension.
    • È consigliabile usare un account di archiviazione separato per questo scopo, per evitare che le chiamate da altri servizi riducano le prestazioni.It's best to use a separate storage account for this purpose, to avoid calls from different services slowing performance.
    • Quando si inviano dati a frequenza elevata, a intervalli di pochi secondi, è consigliabile usare più account di archiviazione per non incidere sulle prestazioni.When sending data in high frequency, every few seconds, it is recommended to use more than one storage account, for performance reasons.
  2. Creare una chiave di firma di accesso condiviso per il BLOB.Create a Shared Access Signature key for the blob. La chiave deve avere un periodo di scadenza di un giorno e fornire l'accesso in lettura.The key should have an expiration period of one day and provide read access.

  3. Eseguire una chiamata REST per notificare ad Application Insights che i dati sono in attesa.Make a REST call to notify Application Insights that data is waiting.

    • Endpoint: https://dc.services.visualstudio.com/v2/trackEndpoint: https://dc.services.visualstudio.com/v2/track
    • Metodo HTTP: POSTHTTP method: POST
    • Payload:Payload:

    {
       "data": {
            "baseType":"OpenSchemaData",
            "baseData":{
               "ver":"2",
               "blobSasUri":"<Blob URI with Shared Access Key>",
               "sourceName":"<Schema ID>",
               "sourceVersion":"1.0"
             }
       },
       "ver":1,
       "name":"Microsoft.ApplicationInsights.OpenSchema",
       "time":"<DateTime>",
       "iKey":"<instrumentation key>"
    }

I segnaposto sono:The placeholders are:

  • Blob URI with Shared Access Key: valore ottenuto dalla procedura per la creazione di una chiave.Blob URI with Shared Access Key: You get this from the procedure for creating a key. È specifico per il BLOB.It is specific to the blob.
  • Schema ID: l'ID di schema generato per lo schema definito.Schema ID: The schema ID generated for your defined schema. I dati in questo BLOB devono essere conformi allo schema.The data in this blob should conform to the schema.
  • DateTime: ora in cui viene inviata la richiesta, UTC.DateTime: The time at which the request is submitted, UTC. Vengono accettati i seguenti formati: ISO8601 (ad esempio "2016-01-01 13:45:01"); RFC822 ("mer, 14 dic 16 14:57:01 +0000"); RFC850 ("mercoledì, 14-dic-16 14:57:00 UTC"); RFC1123 ("mer, 14 dic 2016 14:57:00 +0000").We accept these formats: ISO8601 (like "2016-01-01 13:45:01"); RFC822 ("Wed, 14 Dec 16 14:57:01 +0000"); RFC850 ("Wednesday, 14-Dec-16 14:57:00 UTC"); RFC1123 ("Wed, 14 Dec 2016 14:57:00 +0000").
  • Instrumentation key della risorsa di Application Insights.Instrumentation key of your Application Insights resource.

I dati sono disponibili in Analytics dopo alcuni minuti.The data is available in Analytics after a few minutes.

Risposte agli erroriError responses

  • 400 richiesta non valida: indica che il payload della richiesta non è valido.400 bad request: indicates that the request payload is invalid. Controllare:Check:
    • Chiave di strumentazione corretta.Correct instrumentation key.
    • Valore dell'ora valido.Valid time value. L'ora dovrebbe essere in formato UTC.It should be the time now in UTC.
    • Il codice JSON dell'evento è conforme allo schema.JSON of the event conforms to the schema.
  • 403 - Accesso negato: non è possibile accedere al BLOB inviato.403 Forbidden: The blob you've sent is not accessible. Assicurarsi che la chiave di accesso condiviso sia valida e non scaduta.Make sure that the shared access key is valid and has not expired.
  • 404 - Pagina non trovata:404 Not Found:
    • Il BLOB non esiste.The blob doesn't exist.
    • Il valore sourceId non è valido.The sourceId is wrong.

Informazioni più dettagliate sono disponibili nel messaggio di errore della risposta.More detailed information is available in the response error message.

Codice di esempioSample code

Questo codice usa il pacchetto NuGet Newtonsoft.Json.This code uses the Newtonsoft.Json NuGet package.

ClassiClasses

namespace IngestionClient 
{ 
    using System; 
    using Newtonsoft.Json; 

    public class AnalyticsDataSourceIngestionRequest 
    { 
        #region Members 
        private const string BaseDataRequiredVersion = "2"; 
        private const string RequestName = "Microsoft.ApplicationInsights.OpenSchema"; 
        #endregion Members 

        public AnalyticsDataSourceIngestionRequest(string ikey, string schemaId, string blobSasUri, int version = 1) 
        { 
            Ver = version; 
            IKey = ikey; 
            Data = new Data 
            { 
                BaseData = new BaseData 
                { 
                    Ver = BaseDataRequiredVersion, 
                    BlobSasUri = blobSasUri, 
                    SourceName = schemaId, 
                    SourceVersion = version.ToString() 
                } 
            }; 
        } 


        [JsonProperty("data")] 
        public Data Data { get; set; } 

        [JsonProperty("ver")] 
        public int Ver { get; set; } 

        [JsonProperty("name")] 
        public string Name { get { return RequestName; } } 

        [JsonProperty("time")] 
        public DateTime Time { get { return DateTime.UtcNow; } } 

        [JsonProperty("iKey")] 
        public string IKey { get; set; } 
    } 

    #region Internal Classes 

    public class Data 
    { 
        private const string DataBaseType = "OpenSchemaData"; 

        [JsonProperty("baseType")] 
        public string BaseType 
        { 
            get { return DataBaseType; } 
        } 

        [JsonProperty("baseData")] 
        public BaseData BaseData { get; set; } 
    } 


    public class BaseData 
    { 
        [JsonProperty("ver")] 
        public string Ver { get; set; } 

        [JsonProperty("blobSasUri")] 
        public string BlobSasUri { get; set; } 

        [JsonProperty("sourceName")] 
        public string SourceName { get; set; } 

        [JsonProperty("sourceVersion")] 
        public string SourceVersion { get; set; } 
    } 

    #endregion Internal Classes 
} 


namespace IngestionClient 
{ 
    using System; 
    using System.IO; 
    using System.Net; 
    using System.Text; 
    using System.Threading.Tasks; 
    using Newtonsoft.Json; 

    public class AnalyticsDataSourceClient 
    { 
        #region Members 
        private readonly Uri endpoint = new Uri("https://dc.services.visualstudio.com/v2/track"); 
        private const string RequestContentType = "application/json; charset=UTF-8"; 
        private const string RequestAccess = "application/json"; 
        #endregion Members 

        #region Public 

        public async Task<bool> RequestBlobIngestion(AnalyticsDataSourceIngestionRequest ingestionRequest) 
        { 
            HttpWebRequest request = WebRequest.CreateHttp(endpoint); 
            request.Method = WebRequestMethods.Http.Post; 
            request.ContentType = RequestContentType; 
            request.Accept = RequestAccess; 

            string notificationJson = Serialize(ingestionRequest); 
            byte[] notificationBytes = GetContentBytes(notificationJson); 
            request.ContentLength = notificationBytes.Length; 

            Stream requestStream = request.GetRequestStream(); 
            requestStream.Write(notificationBytes, 0, notificationBytes.Length); 
            requestStream.Close(); 

            try 
            { 
                using (var response = (HttpWebResponse)await request.GetResponseAsync())
                {
                    return response.StatusCode == HttpStatusCode.OK;
                }
            } 
            catch (WebException e) 
            { 
                HttpWebResponse httpResponse = e.Response as HttpWebResponse; 
                if (httpResponse != null) 
                { 
                    Console.WriteLine( 
                        "Ingestion request failed with status code: {0}. Error: {1}", 
                        httpResponse.StatusCode, 
                        httpResponse.StatusDescription); 
                    return false; 
                }
                throw; 
            } 
        } 
        #endregion Public 

        #region Private 
        private byte[] GetContentBytes(string content) 
        { 
            return Encoding.UTF8.GetBytes(content);
        } 


        private string Serialize(AnalyticsDataSourceIngestionRequest ingestionRequest) 
        { 
            return JsonConvert.SerializeObject(ingestionRequest); 
        } 
        #endregion Private 
    } 
} 

Inserire datiIngest data

Usare questo codice per ogni BLOB.Use this code for each blob.

   AnalyticsDataSourceClient client = new AnalyticsDataSourceClient(); 

   var ingestionRequest = new AnalyticsDataSourceIngestionRequest("iKey", "sourceId", "blobUrlWithSas"); 

   bool success = await client.RequestBlobIngestion(ingestionRequest);

Passaggi successiviNext steps