Формат запроса для API запросов к журналам Azure Monitor

API запросов журналов позволяет выполнять запросы языка запросов Kusto (KQL) к рабочей области Log Analytics через общедоступную конечную точку REST. Получение или анализ данных журнала программным способом для автоматизации, пользовательских отчетов или интеграции с другими средствами.

В этой статье показано, как оформлять запросы GET и POST для конечной точки API запросов к журналам, включая прямые примеры REST и эквивалентные команды Azure CLI и командлеты Azure PowerShell.

Сведения о более широком наборе API Azure Monitor см. в индексе REST API Azure Monitor.

Формат конечной точки общедоступного запроса

Конечная точка API запросов общедоступных журналов имеет следующий формат:

https://api.loganalytics.azure.com/{apiVersion}/workspaces/{workspaceId}/query?[parameters]

• apiVersion — это версия API общедоступного запроса. Используйте v1.
• workspaceId — это GUID рабочей области Log Analytics, к которой выполняется запрос.
• [parameters] — это строковые значения запроса, такие как query, timespanи workspaces.

Параметры запроса

Передайте эти параметры в строке запроса для GET запросов или в тексте JSON для POST запросов.

Parameter	Обязательный	Description
query	Yes	Запрос KQL для выполнения.
timespan	Нет	Диапазон времени для запроса. Используйте длительность ISO 8601 (например, PT12H в течение 12 часов) или пару начала и окончания, разделенную / (например, 2024-01-01/2024-01-02). Если не указано, запрос выполняется по всем доступным данным.
workspaces	Нет	Дополнительные идентификаторы рабочих областей для включения в запрос между рабочими областями.

Формат запроса GET

Для GET запросов включите параметры запроса в строку запроса. Например, чтобы подсчитать AzureActivity события за Category последние 12 часов, используйте следующий запрос:

Azure CLI

Используйте az rest для вызова API запросов журналов напрямую.

subscriptionId="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
workspaceId="myWorkspaceId"
query="AzureActivity | summarize count() by Category"
timespan="PT12H"
logsQueryApiEndpoint="https://api.loganalytics.io"
resourceId="$logsQueryApiEndpoint/v1/workspaces/$workspaceId/query"

az account set --subscription "$subscriptionId"

az rest \
  --method get \
  --uri "$resourceId?query=$query&timespan=$timespan" \
  --resource "$logsQueryApiEndpoint"

Кроме того, Azure CLI поддерживает эту операцию с помощью команды az monitor log-analytics query. Это часть общедоступного расширения log-analytics, которое Azure CLI устанавливается автоматически.

subscriptionId="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
workspaceId="myWorkspaceId"
query="AzureActivity | summarize count() by Category"
timespan="PT12H"

az account set --subscription "$subscriptionId"

az monitor log-analytics query \
  --workspace "$workspaceId" \
  --analytics-query "$query" \
  --timespan "$timespan"

Powershell

Используйте Invoke-AzRestMethod для вызова API запросов журналов напрямую.

$subscriptionId = 'aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e'
$workspaceId = 'myWorkspaceId'
$query = 'AzureActivity | summarize count() by Category'
$timespan = 'PT12H'
$logsQueryApiEndpoint = 'https://api.loganalytics.io'
$resourceId = "$logsQueryApiEndpoint/v1/workspaces/$workspaceId/query"

Set-AzContext -Subscription $subscriptionId

$restParams = @{
    Method     = 'GET'
    Uri        = "${resourceId}?query=$query&timespan=$timespan"
    ResourceId = $logsQueryApiEndpoint
}

$response = Invoke-AzRestMethod @restParams
$results = $response.Content | ConvertFrom-Json
$results.tables

Кроме того, Azure PowerShell поддерживает эту операцию с помощью командлета Invoke-AzOperationalInsightsQuery (из модуля Az.OperationalInsights). Она автоматически обрабатывает проверку подлинности и сериализацию JSON.

$subscriptionId = 'aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e'
$workspaceId = 'myWorkspaceId'
$query = 'AzureActivity | summarize count() by Category'
$timespan = New-TimeSpan -Hours 12

Set-AzContext -Subscription $subscriptionId

$queryParams = @{
    WorkspaceId = $workspaceId
    Query       = $query
    Timespan    = $timespan
}

$results = Invoke-AzOperationalInsightsQuery @queryParams
$results.Results

Tip

Используется -IncludeStatistics для возврата данных о производительности запроса или -Wait задания времени ожидания на стороне сервера в секундах.

REST

GET https://api.loganalytics.azure.com/v1/workspaces/{workspaceId}/query?query=AzureActivity%20%7C%20summarize%20count%28%29%20by%20Category&timespan=PT12H
Authorization: Bearer {accessToken}

Формат запроса POST

Для POST запросов отправьте параметры запроса в тексте JSON.

• Тело запроса должно быть допустимым JSON.
• Включите Content-Type: application/json заголовок.
• Поместите такие значения запроса, как query, timespanи workspaces в текст JSON.
• Если указать timespan в строке запроса и тексте, служба использует пересечение двух значений.

Azure CLI

Используйте az rest для вызова API запросов журналов напрямую.

subscriptionId="aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
workspaceId="myWorkspaceId"
logsQueryApiEndpoint="https://api.loganalytics.io"
resourceId="$logsQueryApiEndpoint/v1/workspaces/$workspaceId/query"
payloadFile="./query-payload.json"

az account set --subscription "$subscriptionId"

az rest \
  --method post \
  --uri "$resourceId" \
  --resource "$logsQueryApiEndpoint" \
  --headers Content-Type=application/json \
  --body @"$payloadFile"

Файл полезной нагрузки (query-payload.json):

{
  "query": "AzureActivity | summarize count() by Category",
  "timespan": "PT12H"
}

Или используйте команду az monitor log-analytics query, которая скрывает детали формата HTTP-запроса и работает в обоих сценариях выполнения запросов: GET и POST. См. раздел формата запроса GET для примера команды.

Powershell

Используйте Invoke-AzRestMethod для вызова API запросов журналов напрямую.

$subscriptionId = 'aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e'
$workspaceId = 'myWorkspaceId'
$logsQueryApiEndpoint = 'https://api.loganalytics.io'
$resourceId = "$logsQueryApiEndpoint/v1/workspaces/$workspaceId/query"
$payloadFile = './query-payload.json'

Set-AzContext -Subscription $subscriptionId

$restParams = @{
    Method     = 'POST'
    Uri        = $resourceId
    ResourceId = $logsQueryApiEndpoint
    Payload    = Get-Content -Raw -Path $payloadFile
}

$response = Invoke-AzRestMethod @restParams
$results = $response.Content | ConvertFrom-Json
$results.tables

Файл данных запроса (query-payload.json):

{
  "query": "AzureActivity | summarize count() by Category",
  "timespan": "PT12H"
}

В качестве альтернативы используйте командлет Invoke-AzOperationalInsightsQuery, который скрывает детали формата HTTP-запроса и работает для сценариев запросов как GET, так и POST. См. раздел формата запроса GET для примера командлета.

REST

POST https://api.loganalytics.azure.com/v1/workspaces/{workspaceId}/query
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "query": "AzureActivity | summarize count() by Category",
  "timespan": "PT12H"
}

Связанный контент

• Доступ к API и проверка подлинности
• Формат ответа для API запросов Log Analytics
• Индекс REST API Azure Monitor