Azure API Management에서 Azure Event Hubs에 이벤트를 기록하는 방법

  • 아티클

적용 대상: 모든 API Management 계층

이 문서에서는 Azure Event Hubs를 사용하여 API Management 이벤트를 로그하는 방법을 설명합니다.

Azure Event Hubs는 초당 수백만 개의 이벤트를 수집할 수 있는 확장성이 뛰어난 데이터 수집 서비스이므로 연결된 디바이스와 애플리케이션이 생성하는 대량의 데이터를 처리하고 분석할 수 있습니다. Event Hubs는 이벤트 파이프라인에 대한 "현관"의 역할을 하고 데이터가 이벤트 허브에 수집되면 실시간 분석 공급자 또는 일괄 처리/스토리지 어댑터를 사용하여 변환 및 저장될 수 있습니다. Event Hubs는 이러한 이벤트를 소비하는 데에서 이벤트 스트림의 프로덕션을 분리하므로 이벤트 소비자가 자신의 개인 일정에 이벤트를 액세스할 수 있습니다.

필수 조건

이벤트 허브에 대한 액세스 구성

이벤트 허브에 이벤트를 로그하려면 API Management에서 액세스하기 위한 자격 증명을 구성해야 합니다. API Management는 다음 두 가지 액세스 메커니즘 중 하나를 지원합니다.

  • Event Hubs 연결 문자열.
  • API Management 인스턴스에 대한 관리 ID입니다.

옵션 1: Event Hubs 연결 문자열 구성

Event Hubs 연결 문자열을 만들려면 Event Hubs 연결 문자열 가져오기를 참조하세요.

  • Event Hubs 네임스페이스 또는 API Management에서 로깅하는 데 사용하는 특정 이벤트 허브에 대한 연결 문자열을 사용할 수 있습니다.
  • 연결 문자열에 대한 공유 액세스 정책은 최소한 보내기 권한을 사용하도록 설정해야 합니다.

옵션 2: API Management 관리 ID 구성

참고 항목

이벤트 허브에 이벤트를 로깅하기 위해 API Management 관리 ID를 사용하는 것은 API Management REST API 버전 2022-04-01-preview 이상에서 지원됩니다.

  1. API Management 인스턴스에서 시스템이 할당하거나 사용자가 할당한 API Management 관리 ID를 사용하도록 설정합니다.

    • 사용자가 할당한 관리 ID를 사용하도록 설정하는 경우 ID의 클라이언트 ID를 적어 둡니다.

  2. Event Hubs 네임스페이스 또는 로깅에 사용되는 이벤트 허브로 범위가 할당된 Azure Event Hubs 데이터 보낸 사람 역할에 ID를 할당합니다. 역할을 할당하려면 Azure Portal 또는 다른 Azure 도구를 사용합니다.

API Management 로거 만들기

다음 단계는 이벤트 허브에 이벤트를 로그할 수 있도록 API Management 서비스에서 로거를 구성하는 것입니다.

API Management REST API를 직접 사용하거나 Azure PowerShell, Bicep 템플릿 또는 Azure Resource Management 템플릿을 포함한 도구를 사용하여 API Management 로거를 만들고 관리합니다.

연결 문자열 자격 증명이 있는 로거

필수 조건은 Event Hubs 연결 문자열 구성을 참조하세요.

다음 예에서는 New-AzApiManagementLogger cmdlet을 사용하여 연결 문자열을 구성해 이벤트 허브에 대한 로거를 만듭니다.

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# Create logger
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName
New-AzApiManagementLogger -Context $context -LoggerId "ContosoLogger1" -Name "ApimEventHub" -ConnectionString "Endpoint=sb://<EventHubsNamespace>.servicebus.windows.net/;SharedAccessKeyName=<KeyName>;SharedAccessKey=<key>" -Description "Event hub logger with connection string"

시스템 할당 관리 ID 자격 증명이 있는 로거

필수 조건은 API Management 관리 ID 구성을 참조하세요.

API Management REST API 또는 Bicep 또는 ARM 템플릿을 사용하여 시스템 할당 관리 ID 자격 증명을 사용하여 이벤트 허브에 대한 로거를 구성합니다.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with system assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"SystemAssigned",
         "name":"<EventHubName>"
    }
  }
}

사용자 할당 관리 ID 자격 증명이 있는 로거

필수 조건은 API Management 관리 ID 구성을 참조하세요.

API Management REST API 또는 Bicep 또는 ARM 템플릿을 사용하여 사용자가 할당한 관리 ID 자격 증명으로 이벤트 허브에 대한 로거를 구성합니다.

{
  "properties": {
    "loggerType": "azureEventHub",
    "description": "adding a new logger with user-assigned managed identity",
    "credentials": {
         "endpointAddress":"<EventHubsNamespace>.servicebus.windows.net",
         "identityClientId":"<ClientID>",
         "name":"<EventHubName>"
    }
  }
}

log-to-eventhub 정책 구성

API Management에서 로거를 구성한 후에는 원하는 이벤트를 로깅하도록 log-to-eventhub 정책을 구성할 수 있습니다. 예를 들어, 인바운드 정책 섹션의 log-to-eventhub 정책을 사용하여 요청을 로그하거나 아웃바운드 정책 섹션에서 응답을 로그합니다.

  1. API Management 인스턴스로 이동합니다.

  2. API를 선택한 다음 정책을 추가할 API를 선택합니다. 이 예제에서는 무제한 제품의 Echo API에 정책을 추가합니다.

  3. 모든 작업을 선택합니다.

  4. 화면 맨 위에서 디자인 탭을 선택합니다.

  5. 인바운드 처리 또는 아웃바운드 처리 창에서 </>(코드 편집기) 아이콘을 선택합니다. 자세한 내용은 정책을 설정하거나 편집하는 방법을 참조하세요.

  6. 커서를 inbound 또는 outbound 정책 섹션에 둡니다.

  7. 오른쪽 창에서 고급 정책>EventHub에 대한 로그를 선택합니다. 그러면 log-to-eventhub 정책 문 템플릿을 삽입합니다.

    <log-to-eventhub logger-id="logger-id">
    @{
        return new JObject(
            new JProperty("EventTime", DateTime.UtcNow.ToString()),
            new JProperty("ServiceName", context.Deployment.ServiceName),
            new JProperty("RequestId", context.RequestId),
            new JProperty("RequestIp", context.Request.IpAddress),
            new JProperty("OperationName", context.Operation.Name)
        ).ToString();
    }
</log-to-eventhub>
    1. logger-id를 이전 단계에서 만든 로거의 이름으로 바꿉니다.
    2. 문자열을 log-to-eventhub 요소에 대한 값으로 반환하는 모든 식을 사용할 수 있습니다. 이 예제에서는 날짜 및 시간, 서비스 이름, 요청 ID, 요청 IP 주소, 작업 이름을 포함하는 JSON 형식의 문자열이 로깅됩니다.

  8. 저장을 선택하여 업데이트된 정책 구성을 저장합니다. 저장되는 즉시 정책이 활성화되며 지정된 이벤트 허브에 이벤트가 기록됩니다.

참고 항목

이 API Management 정책에서 이벤트 허브로 보낼 수 있는 지원되는 최대 메시지 크기는 200KB(킬로바이트)입니다. 이벤트 허브로 전송된 메시지가 200KB보다 큰 경우 자동으로 잘리고, 잘린 메시지는 이벤트 허브로 전송됩니다.

Azure Stream Analytics를 사용하여 Event Hubs의 로그 미리 보기

Azure Stream Analytics 쿼리를 사용하여 Event Hubs의 로그를 미리 볼 수 있습니다.

  1. Azure Portal에서 로거가 이벤트를 전송하는 이벤트 허브로 이동합니다.
  2. 기능에서 데이터 처리 탭을 선택합니다.
  3. 이벤트에서 실시간 인사이트 사용 카드에서 시작을 선택합니다.
  4. 입력 미리 보기 탭에서 로그를 미리 볼 수 있습니다. 표시된 데이터가 최신 상태가 아니면 새로 고침을 선택하여 최신 이벤트를 확인합니다.

다음 단계