다음을 통해 공유

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

적용 대상: 모든 API Management 계층

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

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

참고 항목

현재 이 기능은 작업 영역에서 사용할 수 없습니다.

필수 조건

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

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

  • API Management 인스턴스에 대한 관리 ID(권장)
  • Event Hubs 연결 문자열.

참고 항목

보안 강화를 위해 가능하면 관리 ID 자격 증명을 사용하는 것이 좋습니다.

옵션 1: API Management 관리 ID 구성

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

    • 사용자 할당 관리 ID를 사용하도록 설정하는 경우 ID의 개체 ID를 기록해 둡니다.

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

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

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

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

API Management 로거 만들기

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

API Management REST API를 직접 사용하거나 Azure PowerShell, Bicep 파일 또는 Azure Resource Management 템플릿과 같은 다른 도구를 사용하여 API Management 로거를 만들고 관리합니다.

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

시스템 할당 관리 ID 자격 증명을 사용하여 로거 만들기

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

API Management 로거 사용 - 다음 요청 본문을 사용하여 REST API 멤버 를 만들거나 업데이트 합니다.

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

사용자 할당 관리 ID 자격 증명을 사용하여 로거 만들기

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

API Management 로거 사용 - 다음 요청 본문을 사용하여 REST API 멤버 를 만들거나 업데이트 합니다.

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

옵션 2. 연결 문자열 자격 증명을 사용하여 로거 만들기

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

참고 항목

가능한 경우 관리 ID 자격 증명을 사용하여 로거를 구성하는 것이 좋습니다. 이 문서의 앞부분에 있는 관리 ID 자격 증명으로 로거 구성을 참조하세요.

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

# Details specific to API Management 
$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"

log-to-eventhub 정책을 구성

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

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

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

  3. 디자인 탭에서 모든 작업을 선택합니다.

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

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

  6. 탭 맨 위에 있는 코드 조각 표시를 선택합니다. 고급 정책>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 형식의 문자열이 로깅됩니다.

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

참고 항목

이 API Management 정책에서 이벤트 허브로 보낼 수 있는 지원되는 최대 메시지 크기는 200KB(킬로바이트)입니다. 이벤트 허브로 전송되는 메시지가 200KB보다 크면 자동으로 잘리고 잘린 메시지가 이벤트 허브로 전송됩니다. 더 큰 메시지의 경우 API Management와 함께 Azure Storage를 200KB 제한을 우회하는 해결 방법으로 사용하는 것이 좋습니다. 자세한 내용은 API Management에서 Azure Storage로 요청 보내기를 참조하세요.

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

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

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

관련 콘텐츠

  • Last updated on