API REST di Log Analytics per la ricerca nei logLog Analytics log search REST API

Questa guida fornisce un'esercitazione di base, inclusi alcuni esempi, per l'uso dell'API REST di Log Analytics per la ricerca.This guide provides a basic tutorial, including examples, of how you can use the Log Analytics Search REST API. Log Analytics fa parte di Operations Management Suite (OMS).Log Analytics is part of the Operations Management Suite (OMS).

Nota

Se l'area di lavoro è stata aggiornata al nuovo linguaggio di query di Log Analytics, è consigliabile vedere la documentazione relativa per la nuova versione dell'API di ricerca log.If your workspace has been upgraded to the new Log Analytics query language, then you should refer to the documentation for the new version of the log search API.

Nota

In precedenza Log Analytics era chiamato Operational Insights e questo è il motivo per cui questo nome viene usato nel provider di risorse.Log Analytics was previously called Operational Insights, which is why it is the name used in the resource provider.

Panoramica dell'API REST di ricerca di logOverview of the Log Search REST API

L'API REST di ricerca di Log Analytics è RESTful e accessibile tramite l'API Azure Resource Manager.The Log Analytics Search REST API is RESTful and can be accessed via the Azure Resource Manager API. Questo articolo presenta alcuni esempi di accesso all'API tramite ARMClient, uno strumento da riga di comando open source che semplifica la chiamata dell'API di Azure Resource Manager.This article provides examples of accessing the API through ARMClient, an open source command-line tool that simplifies invoking the Azure Resource Manager API. L'uso di ARMClient è una delle numerose opzioni disponibili per accedere all'API di ricerca di Log Analytics.The use of ARMClient is one of many options to access the Log Analytics Search API. Un'altra possibilità è quella di usare il modulo Azure PowerShell per OperationalInsights che include cmdlet per l'accesso alla ricerca.Another option is to use the Azure PowerShell module for OperationalInsights, which includes cmdlets for accessing search. Con questi strumenti è possibile usare l'API di Azure Resource Manager per effettuare chiamate alle aree di lavoro di OMS ed eseguire i comandi di ricerca al loro interno.With these tools, you can utilize the Azure Resource Manager API to make calls to OMS workspaces and perform search commands within them. L'API restituisce i risultati della ricerca in formato JSON, consentendo di usare i risultati della ricerca in molti modi diversi a livello di codice.The API outputs search results in JSON format, allowing you to use the search results in many different ways programmatically.

È possibile usare Azure Resource Manager tramite una libreria per NET e l'API REST.The Azure Resource Manager can be used via a Library for .NET and the REST API. Per altre informazioni, vedere le pagine Web collegate.To learn more, review the linked web pages.

Nota

Se si usa un comando di aggregazione, ad esempio |measure count() o distinct, ogni chiamata per la ricerca può restituire fino a 500.000 record.If you use an aggregation command such as |measure count() or distinct, each call to search can return upto 500,000 records. Le ricerche che non includono un comando di aggregazione restituiscono fino a 5.000 record.Searches that do not include an aggregation command return upto 5,000 records.

Esercitazione di base sull'API REST di ricerca di Log AnalyticsBasic Log Analytics Search REST API tutorial

Per usare ARMClientTo use ARMClient

  1. Installare Chocolatey, un gestore di pacchetti open source per Windows.Install Chocolatey, which is an Open Source Package Manager for Windows. Aprire una finestra di prompt di comandi come amministratore ed eseguire il comando seguente:Open a command prompt window as administrator and then run the following command:

    @powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
    
  2. Installare ARMClient eseguendo il comando seguente:Install ARMClient by running the following command:

    choco install armclient
    

Per eseguire una ricerca usando ARMClientTo perform a search using ARMClient

  1. Effettuare l'accesso usando il proprio account Microsoft oppure l'account aziendale o dell'istituto di istruzione:Log in using your Microsoft account or your work or school account:

    armclient login
    

    Se l’accesso viene effettuato correttamente, vengono elencate tutte le sottoscrizioni associate all'account specificato.A successful login lists all subscriptions tied to the given account:

    PS C:\Users\SampleUserName> armclient login
    Welcome YourEmail@ORG.com (Tenant: zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz)
    User: YourEmail@ORG.com, Tenant: zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz (Example org)
    There are 3 subscriptions
    Subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (Example Name 1)
    Subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (Example Name 2)
    Subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (Example Name 3)
    
  2. Ottenere le aree di lavoro di Operations Management Suite.Get the Operations Management Suite workspaces:

    armclient get /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces?api-version=2015-03-20
    

    Una chiamata Get riuscita genera tutte le aree di lavoro associate alla sottoscrizione.A successful Get call would output all workspaces tied to the subscription:

    {
    "value": [
    {
      "properties": {
    "source": "External",
    "customerId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "portalUrl": "https://eus.login.mms.microsoft.com/SignIn.aspx?returnUrl=https%3a%2f%2feus.mms.microsoft.com%2fMain.aspx%3fcid%xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      },
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/oi-default-east-us/providers/microsoft.operationalinsights/workspaces/{WORKSPACE NAME}",
      "name": "{WORKSPACE NAME}",
      "type": "Microsoft.OperationalInsights/workspaces",
      "location": "East US"
       ]
    }
    
  3. Creare la variabile di ricerca.Create your search variable:

    $mySearch = "{ 'top':150, 'query':'Error'}";
    
  4. Eseguire la ricerca usando la nuova variabile di ricerca.Search using your new search variable:

    armclient post /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{WORKSPACE NAME}/search?api-version=2015-03-20 $mySearch
    

Esempi di riferimento per l'API REST di ricerca di Log AnalyticsLog Analytics Search REST API reference examples

I codici di esempio seguenti mostrano come usare l’API di ricerca.The following examples show you how you can use the Search API.

Ricerca - Azione/LetturaSearch - Action/Read

Url di esempio:Sample Url:

    /subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupId}/providers/Microsoft.OperationalInsights/workspaces/{WorkspaceName}/search?api-version=2015-03-20

Richiesta:Request:

    $savedSearchParametersJson =
    {
      "top":150,
      "highlight":{
        "pre":"{[hl]}",
        "post":"{[/hl]}"
      },
      "query":"*",
      "start":"2015-02-04T21:03:29.231Z",
      "end":"2015-02-11T21:03:29.231Z"
    }
    armclient post /subscriptions/{Subscription ID}/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{Workspace ID}/search?api-version=2015-03-20 $searchParametersJson

La tabella seguente descrive le proprietà disponibili.The following table describes the properties that are available.

ProprietàProperty DescrizioneDescription
toptop Il numero massimo di risultati da restituire.The maximum number of results to return.
highlighthighlight Contiene i parametri pre e post, in genere usati per evidenziare i campi corrispondentiContains pre and post parameters, used usually for highlighting matching fields
prepre Antepone la stringa specificata ai campi corrispondenti.Prefixes the given string to your matched fields.
postpost Appone la stringa specificata ai campi corrispondenti.Appends the given string to your matched fields.
queryquery La query di ricerca usata per raccogliere e restituire i risultati.The search query used to collect and return results.
startstart L’inizio dell'intervallo di tempo da cui si desidera trovare risultati.The beginning of the time window you want results to be found from.
endend La fine dell'intervallo di tempo da cui si desidera trovare risultati.The end of the time window you want results to be found from.

Risposta:Response:

    {
      "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "__metadata" : {
        "resultType" : "raw",
        "total" : 1455,
        "top" : 150,
        "StartTime" : "2015-02-11T21:09:07.0345815Z",
        "Status" : "Successful",
        "LastUpdated" : "2015-02-11T21:09:07.331463Z",
        "CoreResponses" : [],
        "sort" : [{
          "name" : "TimeGenerated",
          "order" : "desc"
        }],
        "requestTime" : 450
      },
      "value": [{
        "SourceSystem" : "OpsManager",
        "TimeGenerated" : "2015-02-07T14:07:33Z",
        "Source" : "SideBySide",
        "EventLog" : "Application",
        "Computer" : "BAMBAM",
        "EventCategory" : 0,
        "EventLevel" : 1,
        "EventLevelName" : "Error",
        "UserName" : "N/A",
        "EventID" : 78,
        "MG" : "00000000-0000-0000-0000-000000000001",
        "TimeCollected" : "2015-02-07T14:10:04.69Z",
        "ManagementGroupName" : "AOI-5bf9a37f-e841-462b-80d2-1d19cd97dc40",
        "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "Type" : "Event",
        "__metadata" : {
          "Type" : "Event",
          "TimeGenerated" : "2015-02-07T14:07:33Z",
          "highlighting" : {
          "EventLevelName" : ["{[hl]}Error{[/hl]}"]
        }
      }]
    ],
            "start" : "2015-02-04T21:03:29.231Z",
            "end" : "2015-02-11T21:03:29.231Z"
          }
        }
      }]
    }

Ricerca/{ID} - Azione/LetturaSearch/{ID} - Action/Read

Richiedere il contenuto di una ricerca salvata:Request the contents of a Saved Search:

    armclient post /subscriptions/{SubId}/resourceGroups/{ResourceGroupId}/providers/Microsoft.OperationalInsights/workspaces/{WorkspaceName}/search/{SearchId}?api-version=2015-03-20

Nota

Se la ricerca restituisce lo stato 'Sospeso', il polling dei risultati aggiornati può essere effettuato tramite questa API.If the search returns with a ‘Pending’ status, then polling the updated results can be done through this API. Dopo 6 min il risultato della ricerca verrà rimosso dalla cache e sarà restituito Http Gone.After 6 min, the result of the search will be dropped from the cache and HTTP Gone will be returned. Se la richiesta di ricerca iniziale restituisce immediatamente lo stato di operazione riuscita, i risultati non vengono aggiunti alla cache e l'API restituisce HTTP Gone in caso di query.If the initial search request returns a ‘Successful’ status immediately, the results are not added to the cache causing this API to return HTTP Gone if queried. Il contenuto di un risultato HTTP 200 è nello stesso formato della richiesta di ricerca iniziale, ma con i valori aggiornati.The contents of an HTTP 200 result are in the same format as the initial search request just with updated values.

Ricerche salvateSaved searches

Elenco di richieste delle ricerche salvate:Request List of Saved Searches:

    armclient post /subscriptions/{SubId}/resourceGroups/{ResourceGroupId}/providers/Microsoft.OperationalInsights/workspaces/{WorkspaceName}/savedSearches?api-version=2015-03-20

Metodi supportati: GET PUT DELETESupported methods: GET PUT DELETE

Metodi di raccolta supportati: GETSupported collection methods: GET

La tabella seguente descrive le proprietà disponibili.The following table describes the properties that are available.

ProprietàProperty DescrizioneDescription
IDId Identificatore univoco.The unique identifier.
ETagEtag Obbligatoria per l'applicazione di patch.Required for Patch. Aggiornata dal server a ogni scrittura.Updated by server on each write. Il valore deve essere uguale al valore archiviato attuale o a "" per effettuare l'aggiornamento.Value must be equal to the current stored value or ‘’ to update. Viene restituito il codice 409 per i valori obsoleti/non validi.409 returned for old/invalid values.
properties.queryproperties.query Obbligatoria.Required. Query di ricerca.The search query.
properties.displayNameproperties.displayName Obbligatoria.Required. Nome visualizzato della query, definito dall'utente.The user-defined display name of the query.
properties.categoryproperties.category Obbligatoria.Required. Categoria della query, definita dall'utente.The user-defined category of the query.

Nota

L'API di ricerca di Log Analytics restituisce attualmente le ricerche salvate create dall'utente quando viene eseguito il polling di ricerche salvate in un'area di lavoro.The Log Analytics search API currently returns user-created saved searches when polled for saved searches in a workspace. L'API non restituisce le ricerche salvate fornite dalle soluzioni.The API does not return saved searches provided by solutions.

Creare le ricerche salvateCreate saved searches

Richiesta:Request:

    $savedSearchParametersJson = "{'properties': { 'Category': 'myCategory', 'DisplayName':'myDisplayName', 'Query':'* | measure Count() by Source', 'Version':'1'  }"
    armclient put /subscriptions/{Subscription ID}/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{Workspace ID}/savedSearches/thisismyid?api-version=2015-03-20 $savedSearchParametersJson

Nota

Il nome per tutte le ricerche salvate, per le pianificazioni e per le azioni create con l'API Log Analytics deve essere in minuscolo.The name for all saved searches, schedules, and actions created with the Log Analytics API must be in lowercase.

Eliminare le ricerche salvateDelete saved searches

Richiesta:Request:

    armclient delete /subscriptions/{Subscription ID}/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{Workspace ID}/savedSearches/thisIsMyId?api-version=2015-03-20

Aggiornare le ricerche salvateUpdate saved searches

Richiesta:Request:

    $savedSearchParametersJson = "{'etag': 'W/`"datetime\'2015-04-16T23%3A35%3A35.3182423Z\'`"', 'properties': { 'Category': 'myCategory', 'DisplayName':'myDisplayName', 'Query':'* | measure Count() by Source', 'Version':'1'  }"
    armclient put /subscriptions/{Subscription ID}/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{Workspace ID}/savedSearches/thisIsMyId?api-version=2015-03-20 $savedSearchParametersJson

Metadati - Solo JSONMetadata - JSON only

Ecco come visualizzare i campi per tutti i tipi di log per i dati raccolti nell'area di lavoro.Here’s a way to see the fields for all log types for the data collected in your workspace. Ad esempio, se si vuole sapere se il tipo di evento include un campo denominato Computer, questa query rappresenta uno dei modi per controllare.For example, if you want you know if the Event type has a field named Computer, then this query is one way to check.

Richiesta di campi:Request for Fields:

    armclient get /subscriptions/{SubId}/resourceGroups/{ResourceGroupId}/providers/Microsoft.OperationalInsights/workspaces/{WorkspaceName}/schema?api-version=2015-03-20

Risposta:Response:

    {
      "__metadata" : {
        "schema" : {
          "name" : "Example Name",
          "version" : 2
        },
        "resultType" : "schema",
        "requestTime" : 35
      },
      "value" : [{
          "name" : "MG",
          "displayName" : "MG",
          "type" : "Guid",
          "facetable" : true,
          "display" : false,
          "ownerType" : ["PerfHourly", "ProtectionStatus", "Capacity_SMBUtilizationByHost", "Capacity_ArrayUtilization", "Capacity_SMBShareUtilization", "SQLAssessmentRecommendation", "Event", "ConfigurationChange", "ConfigurationAlert", "ADAssessmentRecommendation", "ConfigurationObject", "ConfigurationObjectProperty"]
        }, {
          "name" : "ManagementGroupName",
          "displayName" : "ManagementGroupName",
          "type" : "String",
          "facetable" : true,
          "display" : true,
          "ownerType" : ["PerfHourly", "ProtectionStatus", "Event", "ConfigurationChange", "ConfigurationAlert", "W3CIISLog", "AlertHistory", "Recommendation", "Alert", "SecurityEvent", "UpdateAgent", "RequiredUpdate", "ConfigurationObject", "ConfigurationObjectProperty"]
        }
      ]
    }

La tabella seguente descrive le proprietà disponibili.The following table describes the properties that are available.

ProprietàProperty DescrizioneDescription
namename Nome del campo.Field name.
displayNamedisplayName Nome visualizzato del campo.The display name of the field.
typetype Tipo del valore del campo.The Type of the field value.
facetablefacetable Combinazione delle proprietà "indexed", "stored" e "facet" attuali.Combination of current ‘indexed’, ‘stored ‘and ‘facet’ properties.
displaydisplay Proprietà "display" attuale.Current ‘display’ property. True se il campo è visibile nella ricerca.True if field is visible in search.
ownerTypeownerType Ridotta solo ai tipi appartenenti agli indirizzi IP caricati.Reduced to only Types belonging to onboarded IP’s.

Parametri facoltativiOptional parameters

Le informazioni seguenti illustrano i parametri facoltativi disponibili.The following information describes optional parameters available.

EvidenziazioneHighlighting

Il parametro "Highlight" è un parametro facoltativo che può essere usato per richiedere che il sottosistema di ricerca includa un set di marcatori nella risposta.The “Highlight” parameter is an optional parameter you may use to request the search subsystem include a set of markers in its response.

Questi marcatori indicano l'inizio e la fine del testo evidenziato che corrisponde ai termini forniti nella query di ricerca.These markers indicate the start and end highlighted text that matches the terms provided in your search query. È possibile specificare i marcatori di inizio e di fine che vengono usati dalla ricerca per eseguire il wrapping del termine evidenziato.You may specify the start and end markers that are used by search to wrap the highlighted term.

Query di ricerca di esempioExample search query

    $savedSearchParametersJson =
    {
      "top":150,
      "highlight":{
        "pre":"{[hl]}",
        "post":"{[/hl]}"
      },
      "query":"*",
      "start":"2015-02-04T21:03:29.231Z",
      "end":"2015-02-11T21:03:29.231Z"
    }
    armclient post /subscriptions/{Subscription ID}/resourceGroups/OI-Default-East-US/providers/Microsoft.OperationalInsights/workspaces/{Workspace ID}/search?api-version=2015-03-20 $searchParametersJson

Risultati di esempio:Sample result:

    {
        "TimeGenerated":
        "2015-05-18T23:55:59Z", "Source":
        "EventLog": "Application",
        "Computer": "smokedturkey.net",
        "EventCategory": 0,
        "EventLevel":1,
        "EventLevelName":
        "Error"
        "Manager ", "__metadata":
        {
            "Type": "Event",
            "TimeGenerated": "2015-05-18T23:55:59Z",
            "highlighting": {
                "EventLevelName":
                ["{[hl]}Error{[/hl]}"]
            }
        }
    }

Si noti che il risultato precedente contiene un messaggio di errore con prefisso e suffisso.Notice that the preceding result contains an error message that has been prefixed and appended.

Gruppi di computerComputer groups

I gruppi di computer sono ricerche salvate speciali che restituiscono un set di computer.Computer groups are special saved searches that return a set of computers. È possibile usare un gruppo di computer in altre query per limitare i risultati ai computer nel gruppo.You can use a computer group in other queries to limit the results to the computers in the group. Un gruppo di computer viene implementato come una ricerca salvata con un tag Gruppo con il valore Computer.A computer group is implemented as a saved search with a Group tag with a value of Computer.

Di seguito viene riportata una risposta di esempio per un gruppo di computer.Following is a sample response for a computer group.

    "etag": "W/\"datetime'2016-04-01T13%3A38%3A04.7763203Z'\"",
    "properties": {
        "Category": "My Computer Groups",
        "DisplayName": "My Computer Group",
        "Query": "srv* | Distinct Computer",
        "Tags": [{
            "Name": "Group",
            "Value": "Computer"
          }],
    "Version": 1
    }

Recupero dei gruppi di computerRetrieving computer groups

Per recuperare un gruppo di computer, usare il metodo Get con l'ID del gruppo.To retrieve a computer group, use the Get method with the group ID.

armclient get /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/{Group ID}`?api-version=2015-03-20

Creazione o aggiornamento di un gruppo di computerCreating or updating a computer group

Per creare un gruppo di computer, usare il metodo Put con un ID di ricerca salvato univoco.To create a computer group, use the Put method with a unique saved search ID. Se si usa un ID di gruppo di computer esistente, tale gruppo viene modificato.If you use an existing computer group ID, then that one is modified. Quando si crea un gruppo di computer nel portale di Log Analytics, l'ID viene creato dal gruppo e dal nome.When you create a computer group in the Log Analytics portal, then the ID is created from the group and name.

La query usata per la definizione del gruppo deve restituire un insieme di computer per il gruppo per funzionare correttamente.The query used for the group definition must return a set of computers for the group to function properly. È consigliabile concludere la query con | Distinct Computer per assicurarsi che vengano restituiti i dati corretti.It's recommended that you end your query with | Distinct Computer to ensure the correct data is returned.

La definizione di una ricerca salvata deve includere un tag denominato Gruppo con un valore Computer affinché la ricerca venga classificata come un gruppo di computer.The definition of the saved search must include a tag named Group with a value of Computer for the search to be classified as a computer group.

    $etag=Get-Date -Format yyyy-MM-ddThh:mm:ss.msZ
    $groupName="My Computer Group"
    $groupQuery = "Computer=srv* | Distinct Computer"
    $groupCategory="My Computer Groups"
    $groupID = "My Computer Groups | My Computer Group"

    $groupJson = "{'etag': 'W/`"datetime\'" + $etag + "\'`"', 'properties': { 'Category': '" + $groupCategory + "', 'DisplayName':'"  + $groupName + "', 'Query':'" + $groupQuery + "', 'Tags': [{'Name': 'Group', 'Value': 'Computer'}], 'Version':'1'  }"

    armclient put /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/$groupId`?api-version=2015-03-20 $groupJson

Eliminazione di gruppi di computerDeleting computer groups

Per eliminare un gruppo di computer, usare il metodo Delete con l'ID del gruppo.To delete a computer group, use the Delete method with the group ID.

armclient delete /subscriptions/{Subscription ID}/resourceGroups/{Resource Group Name}/providers/Microsoft.OperationalInsights/workspaces/{Workspace Name}/savedSearches/$groupId`?api-version=2015-03-20

Passaggi successiviNext steps

  • Per informazioni su come creare query usando i campi personalizzati come criteri, vedere l'articolo relativo alle ricerche nei log .Learn about log searches to build queries using custom fields for criteria.