Azure Monitor Log Analytics API 액세스

Azure Monitor Log Analytics 엔드포인트 https://api.loganalytics.azure.com를 사용하여 작업 영역에 쿼리 요청을 제출할 수 있습니다. 엔드포인트에 액세스하려면 Microsoft Entra ID를 통해 인증해야 합니다.

참고 항목

api.loganalytics.io 엔드포인트가 api.loganalytics.azure.com으로 대체되고 있습니다. api.loganalytics.io 엔드포인트는 당분간 계속 지원될 것입니다.

데모 API 키로 인증

Microsoft Entra 인증 없이 API를 빠르게 탐색하려면 API 키 인증을 지원하는 샘플 데이터가 있는 데모 작업 영역을 사용합니다.

샘플 작업 영역에 대해 쿼리를 인증하고 실행하려면 DEMO_WORKSPACE를 {workspace-id}로 사용하고 API 키 DEMO_KEY를 전달합니다.

애플리케이션 ID 또는 API 키가 잘못된 경우 API 서비스는 403(사용할 수 없음) 오류를 반환합니다.

API 키 DEMO_KEY는 헤더, URL 또는 기본 인증을 사용할지 여부에 따라 세 가지 방법으로 전달할 수 있습니다.

• 사용자 지정 헤더: 사용자 지정 헤더 X-Api-Key에 API 키를 입력합니다.
• 쿼리 매개 변수: URL 매개 변수 api_key에 API 키 입력합니다.
• 기본 인증: API 키를 사용자 이름 또는 암호로 입력합니다. 둘 다 제공하는 경우 API 키가 사용자 이름에 있어야 합니다.

이 예제에서는 헤더에서 작업 영역 ID 및 API 키를 사용합니다.

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

공용 API 엔드포인트

공용 API 엔드포인트는 다음과 같습니다.

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

여기서

• api-version: API 버전입니다. 현재 버전은 “v1”입니다.
• workspaceId: 작업 영역 ID입니다.

쿼리는 요청 본문에서 전달됩니다.

예시:

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

인증 설정

API에 액세스하려면 Microsoft Entra ID로 클라이언트 앱을 등록하고 토큰을 요청합니다.

1. Microsoft Entra ID에 앱을 등록합니다.

2. 앱의 개요 페이지에서 API 권한을 선택합니다.

3. 권한 추가를 선택합니다.

4. 내 조직에서 사용하는 API 탭에서 Log Analytics를 검색하고 목록에서 Log Analytics API를 선택합니다.

   

5. 위임된 권한을 선택합니다.

6. Data.Read 확인란을 선택합니다.

7. 권한 추가를 선택합니다.

   

이제 앱이 등록되고 API를 사용할 수 있는 권한이 있으므로 앱에 Log Analytics 작업 영역에 대한 액세스 권한을 부여합니다.

1. Log Analytics 작업 영역 개요 페이지에서 액세스 제어(IAM)를 선택합니다.

2. 역할 할당 추가를 선택합니다.

   

3. 읽기 권한자 역할을 선택한 다음, 구성원을 선택합니다.

   

4. 구성원 탭에서 구성원 선택을 선택합니다.

5. 선택 상자에 앱의 이름을 입력합니다.

6. 앱을 선택하고 선택을 선택합니다.

7. 검토 + 할당을 선택합니다.

   

8. Active Directory 설정 및 작업 영역 권한을 완료한 후 권한 부여 토큰을 요청합니다.

참고 항목

이 예제에서는 읽기 권한자 역할을 적용했습니다. 이 역할은 많은 기본 제공 역할 중 하나이며 필요한 것보다 더 많은 권한을 포함할 수 있습니다. 더 세분화된 역할 및 권한을 만들 수 있습니다. 자세한 내용은 Log Analytics 작업 영역에 대한 액세스 관리를 참조하세요.

권한 부여 토큰 요청

시작하기 전에 요청을 성공적으로 수행하는 데 필요한 모든 값이 있는지 확인합니다. 모든 요청에는 다음이 필요합니다.

• Microsoft Entra 테넌트 ID
• 작업 영역 ID.
• 앱에 대한 Microsoft Entra 클라이언트 ID
• 앱에 대한 Microsoft Entra 클라이언트 비밀

Log Analytics API는 세 가지 다른 Microsoft Entra ID OAuth2 흐름으로 Microsoft Entra 인증을 지원합니다.

• 클라이언트 자격 증명
• 인증 코드
• 암시적

클라이언트 자격 증명 흐름

클라이언트 자격 증명 흐름에서 토큰은 Log Analytics 엔드포인트와 함께 사용됩니다. Microsoft Entra ID에서 앱을 등록할 때 이전 단계에서 앱에 입력한 자격 증명을 사용하여 토큰을 수신하도록 단일 요청이 이루어집니다.

resource=https://api.loganalytics.azure.com을 사용합니다.

다음 방법 중 하나를 사용하여 인증 토큰을 가져옵니다.

• CLI
• REST API
• SDK

토큰을 요청할 때 resource 매개 변수를 제공해야 합니다. resource 매개 변수는 액세스하려는 리소스의 URL입니다.

리소스에는 다음이 포함됩니다.

• https://management.azure.com
• https://api.loganalytics.io
• https://monitoring.azure.com

REST (영문)

REST 요청을 사용하여 토큰 가져오기

토큰을 가져오려면 다음 REST API 호출을 사용합니다. 이 요청은 클라이언트 ID와 클라이언트 암호를 사용하여 요청을 인증합니다. 클라이언트 ID와 클라이언트 암호는 Microsoft Entra ID로 애플리케이션을 등록할 때 획득됩니다. 자세한 내용은 권한 부여 토큰 요청 및 API 작업을 위한 앱 등록을 참조하세요.

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

응답 본문의 형식은 다음과 같습니다.

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

CLI

Azure CLI를 사용하여 토큰 가져오기

CLI를 사용하여 토큰을 가져오려면 다음 명령을 사용할 수 있습니다.

az account get-access-token 

자세한 내용은 az account get-access-token을 참조하세요.

SDK

SDK를 사용하여 토큰 가져오기

다음 코드 샘플은 다음을 사용하여 토큰을 가져오는 방법을 보여 줍니다.

• C#
• NodeJS
• Python

C#

다음 코드는 Azure를 사용하여 토큰을 가져오는 방법을 보여 줍니다. ID 라이브러리 요청을 인증하려면 클라이언트 ID와 클라이언트 암호가 필요합니다.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

또는 DefaultAzureCredential 클래스를 사용하여 토큰을 가져올 수 있습니다. 이 방법은 기본 Azure 자격 증명을 사용하여 요청을 인증하며 클라이언트 ID 또는 클라이언트 암호가 필요하지 않습니다.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

다음과 같이 관리 ID 또는 서비스 주체 자격 증명을 지정할 수도 있습니다.

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

자세한 내용은 DefaultAzureCredential 클래스를 참조하세요.

Node.JS

JavaScript 및 NodeJS를 사용한 인증에 대한 자세한 내용은 JavaScript용 Azure SDK를 사용하여 Azure 서비스에 JavaScript 앱을 인증하는 방법을 참조하세요.

다음 코드는 DefaultAzureCredential 클래스를 사용하여 토큰을 가져오는 방법을 보여 줍니다. 이 방법은 기본 Azure 자격 증명을 사용하여 요청을 인증하며 클라이언트 ID 또는 클라이언트 암호가 필요하지 않습니다.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

InteractiveBrowserCredential 클래스를 사용하여 자격 증명을 가져올 수도 있습니다. 이 방법은 사용자가 Azure 서비스에 인증할 수 있는 브라우저 기반 인증 환경을 제공합니다.

자세한 내용은 DefaultAzureCredential 클래스 및 InteractiveBrowserCredential 클래스를 참조하세요.

또는 ClientSecretCredential 클래스를 사용하여 토큰을 가져올 수 있습니다. 이 방법을 사용하려면 요청을 인증하기 위해 클라이언트 ID와 클라이언트 암호가 필요합니다.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

자세한 내용은 ClientSecretCredential 클래스를 참조하세요.

Python

다음 코드는 DefaultAzureCredential 클래스를 사용하여 토큰을 가져오는 방법을 보여 줍니다. 이 방법은 기본 Azure 자격 증명을 사용하여 요청을 인증하며 클라이언트 ID 또는 클라이언트 암호가 필요하지 않습니다.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

InteractiveBrowserCredential 클래스를 사용하여 자격 증명을 가져올 수도 있습니다. 이 방법은 사용자가 Azure 서비스에 인증할 수 있는 브라우저 기반 인증 환경을 제공합니다.

자세한 내용은 DefaultAzureCredential 클래스 및 InteractiveBrowserCredential 클래스를 참조하세요.

또는 ClientSecretCredential 클래스를 사용하여 토큰을 가져올 수 있습니다. 이 방법을 사용하려면 요청을 인증하기 위해 클라이언트 ID와 클라이언트 암호가 필요합니다.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

자세한 내용은 ClientSecretCredential 클래스를 참조하세요.

Log Analytics 엔드포인트에 대한 요청에서 토큰을 사용합니다.

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

예제 응답:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

인증 코드 흐름

지원되는 기본 OAuth2 흐름은 인증 코드를 통해 이루어집니다. 이 메서드를 사용하려면 Azure Monitor Log Analytics API를 호출하는 데 사용할 토큰을 가져오기 위해 두 개의 HTTP 요청이 필요합니다. 요청당 하나의 엔드포인트인 두 개의 URL이 있습니다. 이러한 방법은 다음 섹션에서 설명합니다.

인증 코드 URL(GET 요청)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

권한 부여 URL을 요청할 때 client_id는 앱의 속성 메뉴에서 복사한 Microsoft Entra 앱의 애플리케이션 ID입니다. redirect_uri는 동일한 Microsoft Entra 앱의 홈페이지/로그인 URL입니다. 요청이 성공하면 이 엔드포인트는 URL에 인증 코드가 추가된 등록 시 제공한 로그인 페이지로 리디렉션합니다. 다음 예제를 참조하십시오.

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

이 시점에서 액세스 토큰을 요청하는 데 필요한 인증 코드를 얻게 됩니다.

인증 코드 토큰 URL(POST 요청)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

모든 값은 이전과 동일하지만 몇 가지 추가 사항이 있습니다. 인증 코드는 성공적인 리디렉션 후 이전 요청에서 받은 것과 동일한 코드입니다. 코드는 Microsoft Entra 앱에서 얻은 키와 결합됩니다. 키를 저장하지 않은 경우 Microsoft Entra 앱 메뉴의 키 탭에서 키를 삭제하고 새 키를 만들 수 있습니다. 응답은 다음 스키마가 있는 토큰이 포함된 JSON 문자열입니다. 토큰 값에 대한 형식이 표시됩니다.

응답 예제:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

이 응답의 액세스 토큰 부분은 Authorization: Bearer 헤더에서 Log Analytics API에 제공하는 것입니다. 또한 향후 새로 고침 토큰을 사용하여 부실한 access_token 및 refresh_token을 획득할 수 있습니다. 이 요청의 형식과 엔드포인트는 다음과 같습니다.

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

응답 예제:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

암시적 코드 흐름

Log Analytics API는 OAuth2 암시적 흐름도 지원합니다. 이 흐름의 경우 단일 요청만 필요하지만 새로 고침 토큰을 얻을 수 없습니다.

암시적 코드 권한 부여 URL

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

요청이 성공하면 다음과 같이 URL에 토큰이 있는 리디렉션 URI로 리디렉션됩니다.

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

이 access_token은 요청을 승인하기 위해 Log Analytics API에 전달될 때 Authorization: Bearer 헤더 값으로 사용할 수 있습니다.

자세한 정보

Microsoft Entra를 사용한 OAuth2에 대한 설명서는 다음에서 찾을 수 있습니다.

• Microsoft Entra 권한 부여 코드 흐름
• Microsoft Entra 암시적 허용 흐름
• Microsoft Entra S2S 클라이언트 자격 증명 흐름

다음 단계

• 요청 형식
• 응답 형식
• Azure 리소스에 대한 로그 쿼리
• 일괄 처리 쿼리