Azure Monitor Log Analytics API 액세스

아티클
02/23/2024

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로 클라이언트 앱을 등록하고 토큰을 요청합니다.

Microsoft Entra ID에 앱을 등록합니다.
앱의 개요 페이지에서 API 권한을 선택합니다.
권한 추가를 선택합니다.
내 조직에서 사용하는 API 탭에서 Log Analytics를 검색하고 목록에서 Log Analytics API를 선택합니다.
위임된 권한을 선택합니다.
Data.Read 확인란을 선택합니다.
권한 추가를 선택합니다.

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

Log Analytics 작업 영역 개요 페이지에서 액세스 제어(IAM)를 선택합니다.
역할 할당 추가를 선택합니다.
읽기 권한자 역할을 선택한 다음, 구성원을 선택합니다.
구성원 탭에서 구성원 선택을 선택합니다.
선택 상자에 앱의 이름을 입력합니다.
앱을 선택하고 선택을 선택합니다.
검토 + 할당을 선택합니다.
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에서 앱을 등록할 때 이전 단계에서 앱에 입력한 자격 증명을 사용하여 토큰을 수신하도록 단일 요청이 이루어집니다.

https://api.loganalytics.azure.com 엔드포인트를 사용합니다.

클라이언트 자격 증명 토큰 URL(POST 요청)

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

성공적인 요청은 응답에서 다음과 같은 액세스 토큰을 받습니다.

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

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에 대한 설명서는 다음에서 찾을 수 있습니다.

Share via