Azure Event Hubs 데이터 연결

아티클
05/08/2023

Azure Event Hubs는 빅 데이터 스트리밍 플랫폼 및 이벤트 수집 서비스입니다. Azure Data Explorer는 고객 관리형 Event Hubs에서 지속적으로 수집합니다.

Event Hubs 수집 파이프라인은 여러 단계로 이벤트를 Azure Data Explorer로 전송합니다. 먼저 Azure Portal에서 이벤트 허브를 만듭니다. 그런 다음 Azure Data Explorer에서 특정 형식의 데이터가 지정된 수집 속성을 사용하여 수집될 대상 테이블을 만듭니다. Event Hubs 연결에서 이벤트 라우팅을 알아야 합니다. 데이터는 이벤트 시스템 속성에 따라 선택한 속성에 포함될 수 있습니다. Event Hubs에 대한 연결을 생성하여 이벤트 허브를 생성하고 이벤트로 보냅니다. 이 프로세스는 Azure Portal을 통해 C# 또는 Python을 사용하여 프로그래밍 방식으로 관리하거나 Azure Resource Manager 템플릿을 사용하여 관리할 수 있습니다.

Azure Data Explorer의 데이터 수집에 대한 일반적인 정보는 Azure Data Explorer 데이터 수집 개요를 참조하세요.

Azure Data Explorer 데이터 연결 인증 메커니즘

관리 ID 기반 데이터 연결(권장): 관리 ID 기반 데이터 연결을 사용하는 것이 데이터 원본에 연결하는 가장 안전한 방법입니다. 이는 데이터 원본에서 데이터를 가져오는 기능을 완전히 제어합니다. 관리 ID를 사용하여 데이터 연결을 설정하려면 다음 단계가 필요합니다.
1. 클러스터에 관리 ID를 추가합니다.
2. 데이터 원본의 관리 ID에 권한을 부여합니다.
3. 대상 데이터베이스에서 관리 ID 정책을 설정합니다.
4. 관리 ID 인증을 사용하여 데이터 연결을 만들어 데이터를 가져옵니다.

주의

관리 ID 권한이 데이터 원본에서 제거되면 데이터 연결이 비활성화되고 데이터 원본에서 데이터를 가져올 수 없습니다.

키 기반 데이터 연결: 데이터 연결에 관리 ID가 지정되지 않은 경우 연결이 자동으로 키 기반 인증으로 기본 설정됩니다. 키 기반 연결은 Azure Event Hubs 연결 문자열과 같은 리소스 연결 문자열을 사용하여 데이터를 가져옵니다. Azure Data Explorer는 지정된 리소스에 대한 리소스 연결 문자열을 생성하고 데이터 연결에 안전하게 저장합니다. 그런 다음, 연결 문자열을 사용하여 데이터 원본에서 데이터를 가져옵니다.

주의

키가 회전되면 데이터 연결이 비활성화되고 데이터 원본에서 데이터를 가져올 수 없습니다. 이 문제를 해결하려면 데이터 연결을 업데이트하거나 다시 만듭니다.

MI가 Azure Event Hubs에서 데이터를 가져올 수 있도록 최소한 Azure Event Hubs 데이터 수신기가 있어야 합니다.

데이터 형식

데이터는 EventData 개체 형식으로 이벤트 허브에서 읽습니다.
지원되는 형식을 참조하세요.
참고
- Event Hub에서 수집해도 RAW 형식은 지원되지 않습니다.
- Azure Event Hub 스키마 레지스트리 및 스키마 없는 Avro는 지원되지 않습니다.
GZip 압축 알고리즘을 사용하여 데이터를 압축할 수 있습니다. 수집 속성을 사용하거나 정적 데이터 연결 설정에서 Compression를 동적으로 지정할 수 있습니다.

참고

압축 형식(Avro, Parquet, ORC, ApacheAvro 및 W3CLOGFILE)에 대해서는 데이터 압축이 지원되지 않습니다. 사용자 지정 인코딩 및 포함된 시스템 속성은 압축된 데이터에서 지원되지 않습니다.

Event Hubs 속성

Azure Data Explorer는 다음 Event Hubs 속성을 지원합니다.

이벤트를 관련 테이블로 라우팅하는 데 도움이 되는 수집 속성의 닫힌 집합.
지정된 매핑에 따라 데이터에 포함할 수 있는 이벤트 시스템 속성의 닫힌 집합.

참고

메타데이터를 이벤트와 연결하는 데 사용되는 Event Hubs 사용자 지정 속성 수집은 지원되지 않습니다. 사용자 지정 속성을 수집해야 하는 경우 이벤트 데이터의 본문에 보냅니다. 자세한 내용은 사용자 지정 속성 수집을 참조하세요.

수집 속성

수집 프로세스는 수집 속성을 통해 데이터를 라우팅할 위치와 처리 방법을 알게 됩니다. EventData.Properties를 사용하여 이벤트 수집의 수집 속성을 지정할 수 있습니다. 다음 속성을 설정할 수 있습니다.

참고

속성 이름은 대/소문자를 구분합니다.

속성	Description
데이터베이스	대상 데이터베이스의 대/소문자 구분 이름입니다. 기본적으로 데이터는 데이터 연결과 관련된 대상 데이터베이스에 수집됩니다. 기본 데이터베이스를 재정의하고 다른 데이터베이스로 데이터를 보내려면 이 속성을 사용합니다. 이렇게 하려면 먼저 연결을 다중 데이터베이스 연결로 설정해야 합니다.
테이블	기존 대상 테이블의 대/소문자 구분 이름입니다. `Data Connection` 창에 설정된 `Table`을 재정의합니다.
서식	데이터 형식 `Data Connection` 창에 설정된 `Data format`을 재정의합니다.
IngestionMappingReference	사용할 기존 수집 매핑의 이름입니다. `Data Connection` 창에 설정된 `Column mapping`을 재정의합니다.
압축	데이터 압축, `None`(기본값) 또는 `GZip` 압축.
Encoding	데이터 인코딩, 기본값은 UTF8입니다. .NET 지원 인코딩 중 하나일 수 있습니다.
태그	수집된 데이터와 연결할 JSON 배열 문자열 형식의 태그 목록입니다. 태그를 사용할 때 성능에 영향이 있습니다.
RawHeaders	이벤트 원본이 Kafka이고 Azure Data Explorer 바이트 배열 역직렬화를 사용하여 다른 라우팅 속성을 읽어야 함을 나타냅니다. 값은 무시됩니다.

참고

데이터 연결을 만든 후에 큐에 넣은 이벤트만 수집됩니다.

이벤트 라우팅

클러스터에 대한 데이터 연결을 만들 때 수집된 데이터를 보낼 위치에 대한 라우팅을 지정할 수 있습니다. 기본 라우팅은 대상 데이터베이스와 연결된 연결 문자열에 지정된 대상 테이블로 라우팅하는 것입니다. 데이터의 기본 라우팅을 정적 라우팅이라고도 합니다. 위에서 언급한 이벤트 데이터 속성을 설정하여 데이터에 대한 대체 라우팅을 지정할 수 있습니다.

대체 데이터베이스로 이벤트 데이터 라우팅

대체 데이터베이스로 데이터 라우팅은 기본적으로 꺼져 있습니다. 데이터를 다른 데이터베이스로 보내려면 먼저 연결을 다중 데이터베이스 연결로 설정해야 합니다. Azure Portal Azure Portal, C#, Python 또는 ARM 템플릿에서 이 작업을 수행할 수 있습니다. 데이터베이스 라우팅을 허용하는 데 사용되는 사용자, 그룹, 서비스 주체 또는 관리 ID에는 적어도 클러스터에 대한 기여자 역할 및 쓰기 권한이 있어야 합니다.

대체 데이터베이스를 지정하려면 Database수집 속성을 설정합니다.

경고

연결을 다중 데이터베이스 데이터 연결로 설정하지 않고 대체 데이터베이스를 지정하면 수집이 실패합니다.

대체 테이블로 이벤트 데이터 라우팅

각 이벤트에 대한 대체 테이블을 지정하려면 Table, Format, Compression 및 매핑 수집 속성을 설정합니다. 연결은 이벤트의 정적 속성을 재정의하여 EventData.Properties에 지정된 대로 수집된 데이터를 동적으로 라우팅합니다.

다음 예제에서는 이벤트 허브 세부 정보를 설정하고 날씨 메트릭 데이터를 대체 데이터베이스(MetricsDB) 및 테이블(WeatherMetrics)로 보내는 방법을 보여 줍니다. 데이터는 JSON 형식이며 mapping1은 WeatherMetrics 테이블에 미리 정의되어 있습니다.

// This sample uses Azure.Messaging.EventHubs which is a .Net Framework library.
await using var producerClient = new EventHubProducerClient("<eventHubConnectionString>");
// Create the event and add optional "dynamic routing" properties
var eventData = new EventData(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(
    new { Timestamp = DateTime.UtcNow, MetricName = "Temperature", Value = 32 }
)));
eventData.Properties.Add("Database", "MetricsDB");
eventData.Properties.Add("Table", "WeatherMetrics");
eventData.Properties.Add("Format", "json");
eventData.Properties.Add("IngestionMappingReference", "mapping1");
eventData.Properties.Add("Tags", "['myDataTag']");
var events = new[] { eventData };
// Send events
await producerClient.SendAsync(events);

이벤트 시스템 속성 매핑

시스템 속성은 이벤트를 큐에 넣을 때 Event Hub 서비스에서 설정한 속성을 저장합니다. 이벤트 허브에 대한 데이터 연결은 지정된 매핑에 따라 선택한 시스템 속성 집합을 테이블에 수집된 데이터에 포함할 수 있습니다.

참고

시스템 속성 포함은 json 및 테이블 형식(예: JSON, MultiJSON, CSV, TSV, PSV, SCsv, SOHsv, TSVE)에 대해 지원됩니다.
지원되지 않는 형식(예: TXT 또는 Parquet, Avro 등과 같은 압축 형식)을 사용하는 경우 데이터는 계속 수집되지만 속성은 무시됩니다.
Event Hub 메시지 압축이 설정된 경우 시스템 속성 포함이 지원되지 않습니다. 이러한 시나리오에서는 적절한 오류가 내보내지고 데이터가 수집되지 않습니다.
테이블 형식 데이터의 경우 시스템 속성은 단일 레코드 이벤트 메시지에 대해서만 지원됩니다.
json 데이터의 경우 시스템 속성은 여러 레코드 이벤트 메시지에 대해서도 지원됩니다. 이러한 경우 시스템 속성은 이벤트 메시지의 첫 번째 레코드에만 추가됩니다.
매핑의 경우 CSV 속성은 데이터 연결 생성 시 나열된 순서대로 레코드의 시작 부분에 추가됩니다. 나중에 변경될 수 있으므로 이러한 속성의 순서에 의존하지 마세요.
JSON 매핑의 경우 속성은 시스템 속성 테이블의 속성 이름에 따라 추가됩니다.

Event Hubs 서비스는 다음 시스템 속성을 노출합니다.

속성	데이터 형식	Description
x-opt-enqueued-time	`datetime`	이벤트를 큐에 넣은 UTC 시간
x-opt-sequence-number	`long`	이벤트 허브의 파티션 스트림 내에 있는 이벤트의 논리적 시퀀스 번호
x-opt-offset	`string`	이벤트 허브 파티션 스트림의 데이터 오프셋입니다. 오프셋 식별자는 이벤트 허브 스트림의 파티션 내에서 고유합니다.
x-opt-publisher	`string`	게시자 엔드포인트에 메시지를 보낸 경우 게시자 이름
x-opt-partition-key	`string`	이벤트를 저장한 해당 파티션의 파티션 키

IoT Central 이벤트 허브로 작업하는 경우 페이로드에 IoT Hub 시스템 속성을 포함할 수도 있습니다. 전체 목록은 IoT Hub 시스템 속성을 참조하세요.

테이블의 데이터 원본 섹션에서 이벤트 시스템 속성을 선택한 경우 테이블 스키마 및 매핑에 속성을 포함해야 합니다.

스키마 매핑 예제

테이블 스키마 매핑 예제

데이터에 세 개의 열(Timespan, Metric, Value)이 포함되고 포함된 속성이 x-opt-enqueued-time와 x-opt-offset인 경우 다음 명령을 사용하여 테이블 스키마를 만들거나 변경합니다.

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, EventHubEnqueuedTime:datetime, EventHubOffset:string)

CSV 매핑 예제

다음 명령을 실행하여 레코드의 시작 부분에 데이터를 추가합니다. 서수 값을 기록해 둡니다.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "Timespan", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "EventHubEnqueuedTime", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "EventHubOffset", "Properties":{"Ordinal":"1"}}'
    ']'

JSON 매핑 예제

시스템 속성 매핑을 사용하여 데이터를 추가합니다. 다음 명령을 실행하세요.

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "Timespan", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.value"}},'
    '    { "column" : "EventHubEnqueuedTime", "Properties":{"Path":"$.x-opt-enqueued-time"}},'
    '    { "column" : "EventHubOffset", "Properties":{"Path":"$.x-opt-offset"}}'
    ']'

Event Hub 캡처 Avro 파일에 대한 스키마 매핑

Event Hub 데이터를 사용하는 한 가지 방법은 Azure Blob Storage 또는 Azure Data Lake Storage의 Azure Event Hubs를 통해 이벤트를 캡처하는 것입니다. 그런 다음, Azure Data Explorer에서 Event Grid 데이터 연결을 사용하여 작성된 캡처 파일을 수집할 수 있습니다.

캡처 파일의 스키마는 Event Hub로 전송된 원래 이벤트의 스키마와 다릅니다. 이러한 차이점을 염두에 두고 대상 테이블 스키마를 디자인해야 합니다. 특히 이벤트 페이로드는 캡처 파일에 바이트 배열로 표시되며 이 배열은 Event Grid Azure Data Explorer 데이터 연결에 의해 자동으로 디코딩되지 않습니다. Event Hub Avro 캡처 데이터의 파일 스키마에 대한 자세한 내용은 Azure Event Hubs에서 캡처된 Avro 파일 탐색을 참조하세요.

이벤트 페이로드를 올바르게 디코딩하려면 다음을 수행합니다.

캡처된 이벤트의 Body 필드를 대상 테이블의 dynamic 형식 열에 매핑합니다.
unicode_codepoints_to_string() 함수를 사용하여 바이트 배열을 읽을 수 있는 문자열로 변환하는 업데이트 정책을 적용합니다.

사용자 지정 속성 수집

Event Hubs에서 이벤트를 수집할 때는 이벤트 데이터 개체의 body 섹션에서 데이터를 가져옵니다. 그러나 Event Hubs 사용자 지정 속성은 개체의 properties 섹션에 정의되며 수집되지 않습니다. 고객 속성을 수집하려면 해당 속성을 개체의 body 섹션에 있는 데이터에 포함해야 합니다.

다음 예제에서는 Event Hubs에서 정의한 사용자 지정 속성 customProperty를 포함하는 이벤트 데이터 개체(왼쪽)와 수집에 필요한 포함된 속성(오른쪽)을 포함하는 이벤트 데이터 개체를 비교합니다.

{
"body":{
"value": 42
},
"properties":{
"customProperty": "123456789"
}
}

{
"body":{
"value": 42,
"customProperty": "123456789"
}
}

다음 방법 중 하나를 사용하여 이벤트 데이터 개체의 body 섹션에 있는 데이터에 사용자 지정 속성을 포함할 수 있습니다.

Event Hubs에서 이벤트 데이터 개체를 만들 때 사용자 지정 속성을 개체의 body 섹션에 있는 데이터의 일부로 포함합니다.
Azure Stream Analytics를 사용하여 이벤트 허브의 이벤트를 처리하고 이벤트 데이터에 사용자 지정 속성을 포함합니다. Azure Stream Analytics에서 기본적으로 Azure Data Explorer 출력 커넥터를 사용하여 데이터를 수집하거나 다른 이벤트 허브로 데이터를 라우팅한 후 클러스터로 라우팅할 수 있습니다.
Azure Functions를 사용하여 사용자 지정 속성을 추가한 다음, 데이터를 수집합니다.

지역 간 이벤트 허브 데이터 연결

최상의 성능을 위해 클러스터와 동일한 지역에 다음과 같은 리소스를 모두 만듭니다. 다른 대안이 없는 경우 프리미엄 또는 전용 이벤트 허브 계층을 사용하는 것이 좋습니다. 이벤트 허브 계층 비교는 여기에서 찾을 수 있습니다.

이벤트 허브 만들기

이벤트 허브를 만듭니다(아직 없는 경우). 이벤트 허브에 대한 연결은 Azure Portal을 통해 C# 또는 Python을 사용하여 프로그래밍 방식으로 관리하거나 Azure Resource Manager 템플릿을 사용하여 관리할 수 있습니다.

참고

이벤트 허브를 만든 후 파티션을 동적으로 추가하는 기능은 Event Hubs 프리미엄 및 전용 계층에서만 사용할 수 있습니다. 파티션 수를 설정할 때 장기적인 크기 조정을 고려하세요.
소비자 그룹은 소비자별로 고유해야 합니다. Azure Data Explorer 연결 전용 소비자 그룹을 만듭니다.

이벤트 보내기

데이터를 생성하고 이벤트 허브로 보내는 샘플 앱을 참조하세요.

샘플 데이터를 생성하는 방법에 대한 예제는 이벤트 허브에서 Azure Data Explorer로 데이터 수집을 참조하세요.

지리적 재해 복구 솔루션 설정

이벤트 허브는 지리적 재해 복구 솔루션을 제공합니다. Azure Data Explorer는 Alias 이벤트 허브 네임스페이스를 지원하지 않습니다. 솔루션에서 지리적 재해 복구를 구현하려면 두 개의 이벤트 허브 데이터 연결을 만듭니다. 하나는 기본 네임스페이스용이고 다른 하나는 보조 네임스페이스용입니다. Azure Data Explorer는 두 개의 이벤트 허브 연결을 모두 수신 대기합니다.

참고

기본 네임스페이스에서 보조 네임스페이스로 장애 조치(failover)를 구현하는 것은 사용자의 책임입니다.

Azure Event Hubs 데이터 연결

Azure Data Explorer 데이터 연결 인증 메커니즘

데이터 형식

Event Hubs 속성

수집 속성

이벤트 라우팅

대체 데이터베이스로 이벤트 데이터 라우팅

대체 테이블로 이벤트 데이터 라우팅

이벤트 시스템 속성 매핑

스키마 매핑 예제

Event Hub 캡처 Avro 파일에 대한 스키마 매핑

사용자 지정 속성 수집

지역 간 이벤트 허브 데이터 연결

이벤트 허브 만들기

이벤트 보내기

지리적 재해 복구 솔루션 설정

피드백

피드백

추가 리소스

Azure Event Hubs 데이터 연결

Azure Data Explorer 데이터 연결 인증 메커니즘

데이터 형식

Event Hubs 속성

수집 속성

이벤트 라우팅

대체 데이터베이스로 이벤트 데이터 라우팅

대체 테이블로 이벤트 데이터 라우팅

이벤트 시스템 속성 매핑

스키마 매핑 예제

Event Hub 캡처 Avro 파일에 대한 스키마 매핑

사용자 지정 속성 수집

지역 간 이벤트 허브 데이터 연결

이벤트 허브 만들기

이벤트 보내기

지리적 재해 복구 솔루션 설정

관련 콘텐츠

피드백

피드백

추가 리소스