Azure Monitor 로그 쿼리 API 개요

로그 쿼리 API를 사용하여 Azure Monitor Logs에서 수집한 전체 데이터 집합을 쿼리합니다. 이 REST API는 서비스 전체에서 사용되는 것과 동일한 쿼리 언어를 사용하여 데이터를 검색하고, 데이터의 새 시각화를 빌드하고, Log Analytics 기능을 확장합니다. 더 광범위한 Azure Monitor API 화면은 Azure Monitor REST API 인덱스의 로그 쿼리 섹션을 참조하세요.

쿼리 엔드포인트

모든 쿼리는 공용 REST 엔드포인트를 통해 Log Analytics 작업 영역을 대상으로 합니다.

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"
}

{workspaceId}를 Log Analytics 작업 영역의 GUID로 바꾸고 {accessToken}를 Microsoft Entra Bearer 토큰으로 바꾸세요.

API는 배열을 포함하는 JSON 응답을 반환합니다 tables . 각 테이블에는 (스키마) 및 columns (데이터)가 포함됩니다 rows .

{
  "tables": [
    {
      "name": "PrimaryResult",
      "columns": [
        { "name": "Category", "type": "string" },
        { "name": "count_", "type": "long" }
      ],
      "rows": [
        ["Administrative", 20839],
        ["Recommendation", 122],
        ["Alert", 64],
        ["ServiceHealth", 11]
      ]
    }
  ]
}

전체 요청 매개 변수 참조(작업 영역 간 옵션 포함 timespan )는 요청 형식을 참조하세요. 자세한 응답 구조 및 오류 처리는 응답 형식을 참조하세요.

로그 쿼리 API 인증

애플리케이션은 로그 쿼리 API에 액세스하기 위해 인증해야 합니다.

  • 작업 영역을 쿼리하려면 Microsoft Entra 인증을 사용해야 합니다.
  • Microsoft Entra 인증을 사용하지 않고 API를 빠르게 탐색하려면 데모 API 키를 사용하여 비프로덕션 테스트 환경에서 샘플 데이터를 쿼리합니다.

작업 영역 데이터에 대한 Microsoft Entra 인증

로그 쿼리 API는 Microsoft Entra ID OAuth2로 Microsoft Entra 인증을 지원합니다. 애플리케이션에 맞는 흐름을 선택합니다.

  • 권한 부여 코드(PKCE 사용, 대화형 앱에 권장)
  • 클라이언트 자격 증명(비대화형 서비스 간 액세스용)

암시적 허용 흐름은 이전 버전과의 호환성을 위해 지원되지만 더 이상 권장되지 않습니다. 새 애플리케이션의 경우 PKCE 또는 클라이언트 자격 증명 흐름에서 권한 부여 코드 흐름을 사용합니다.

권한 부여 코드 흐름에는 애플리케이션에 하나 이상의 사용자 대화형 로그인이 필요합니다. 비대화형 흐름이 필요한 경우 클라이언트 자격 증명 흐름을 사용합니다.

토큰을 받은 후 로그 쿼리 API를 호출하는 프로세스는 모든 흐름에 대해 동일합니다. 요청에는 OAuth2 흐름에서 받은 토큰으로 채워진 Authorization: Bearer 헤더가 필요합니다.

참고

Microsoft Entra 인증을 사용하는 경우 로그 쿼리 API가 새 역할 기반 액세스 제어 권한을 인식하는 데 몇 분 정도 걸릴 수 있습니다. 사용 권한이 전파되는 동안 REST API 호출은 오류 코드 403으로 실패할 수 있습니다.

샘플 데이터에 대한 API 키 인증

Microsoft Entra 인증을 사용하지 않고 API를 빠르게 탐색하려면 Microsoft 샘플 데이터가 포함된 데모 작업 영역을 제공합니다. API 키를 사용하여 인증합니다.

로그 쿼리 API 제한

API는 동시성, 결과 크기, 쿼리 기간 및 제한 속도에 대한 제한을 적용합니다. 이러한 제한은 작업 영역마다 적용되며 쿼리 원본에 따라 달라집니다. 임계값의 전체 목록은 쿼리 API 제한을 참조하세요.

클라이언트 라이브러리 및 명령줄 도구

Azure Monitor 다양한 프로그래밍 언어에 대한 클라이언트 라이브러리를 지원합니다. REST API를 직접 호출하는 대신, 이러한 라이브러리는 인증, 재시도 및 응답 구문 분석도 처리하는 로그 쿼리 API를 호출하기 위한 래퍼를 제공합니다. 클라이언트 라이브러리는 다음을 위해 사용할 수 있습니다.

명령줄에서 쿼리하는 것과 비슷한 방식으로 Azure CLI 또는 Azure PowerShell 사용합니다.

작업 영역에 대해 KQL 쿼리를 실행하는 데 사용합니다 az monitor log-analytics query .

az monitor log-analytics query \
  --workspace "myWorkspaceId" \
  --analytics-query "AzureActivity | summarize count() by Category" \
  --timespan "PT12H"

API 사용해 보기

코드를 작성하지 않고 API를 탐색하려면 Bruno 또는 Insomnia 와 같은 API 클라이언트를 사용하여 시각적 인터페이스를 사용하여 쿼리를 빌드합니다. 명령줄에서 cURL 을 사용하고 읽을 수 있는 JSON을 위해 출력을 jsonlint 로 파이프할 수도 있습니다.

관련 콘텐츠

  • Last updated on