Microsoft Fabric: 행 수집

**Microsoft Fabric: 행 수집(ingest row)**을 사용하여 Fabric 수집 API를 통해 Journey 단계에서 Eventhouse(KQL) 테이블로 한 행을 스트리밍합니다. 자체 토큰을 사용하는 다른 통합 지점과 달리, 이 지점은 전체 계정에 대해 한 번 연결된 Entra ID 애플리케이션을 통해 인증합니다. 지점 자체에는 토큰 필드가 없습니다.

일반적인 사용 사례:

• 보고 테이블 피드: 도달한 Journey 단계마다 행을 삽입하여 다운스트림에서 대시보드 또는 예약된 쿼리에 사용합니다.
• 이벤트 발생 시 기록: 배치 파이프라인을 기다리지 않고 원시 Journey 데이터를 Eventhouse로 스트리밍합니다.
• 기존 데이터와 조인: Fabric 테이블이 자체 데이터 세트와 조인할 수 있는 디바이스 또는 태그 값을 삽입합니다.

시작하기 전에

**설정 > 타사 통합 > Microsoft Azure (Settings > 3rd-party integrations > Microsoft Azure)**에서 Entra ID 애플리케이션을 연결합니다:

1. Entra ID 디렉터리에 애플리케이션을 등록하고 클라이언트 암호를 생성합니다.
2. **디렉터리(테넌트) ID (Directory (tenant) ID)**에 테넌트(예: contoso.onmicrosoft.com)를 입력합니다.
3. **애플리케이션(클라이언트) ID (Application (client) ID)**에 앱 등록의 클라이언트 ID를 입력합니다.
4. **클라이언트 암호 (Client secret)**에 암호를 붙여넣습니다. 이 암호는 쓰기 전용으로 저장됩니다. Pushwoosh는 다시 표시하지 않으므로 교체하려면 새 암호를 붙여넣어야 합니다.
5. **Azure 연결 (Connect Azure)**을 클릭합니다.

Azure를 연결한 후, 통합을 설치하여 Journey 빌더에 지점이 나타나도록 합니다.

주의

클라이언트 암호는 Entra ID에서 생성할 때 설정한 자체 만료 날짜가 있습니다. 만료되는 날, 지점이 실패하기 시작하고 Control Panel에는 일반적인 “통합 재연결” 상태만 표시되며, 암호를 특정하여 가리키는 것은 없습니다. 암호 만료 날짜에 알림을 설정하여 만료 후가 아닌 만료 전에 교체하도록 하십시오.

Eventhouse 측에서도 세 가지 사항이 준비되어 있어야 하며, 그렇지 않으면 요청이 실패합니다:

• 대상 테이블에는 JSON 수집 매핑이 필요합니다. 이것 없이는 JSON의 스트리밍 수집이 작동하지 않습니다.
• 앱 등록에는 Eventhouse에 대한 ingestor 역할이 필요합니다. Fabric UI에는 이를 위한 버튼이 없습니다. Eventhouse의 쿼리 창에서 다음을 실행하여 권한을 부여하십시오:

.add database ['<database name>'] ingestors ('aadapp=<Application (client) ID>;<Directory (tenant) ID>')

• KQL 데이터베이스는 스트리밍 수집 정책이 활성화되어 있어야 합니다. 동일한 쿼리 창에서 다음을 실행하십시오:

.alter database ['<database name>'] policy streamingingestion enable

데이터베이스 이름에 하이픈이 포함된 경우 이 명령어들에서 데이터베이스 이름 주위에 ['...']를 유지하십시오. 하이픈이 있는 이름만으로는 구문 분석에 실패합니다.

지점 구성

1. 왼쪽 패널의 통합 (Integrations) 섹션에서 **Microsoft Fabric: 행 수집 (Microsoft Fabric: ingest row)**을 캔버스로 드래그합니다.
2. 지점을 더블 클릭하고 **단계 이름 (Step Name)**을 입력합니다.
3. **쿼리 URI 호스트 (Query URI host)**에 Eventhouse의 시스템 개요 (System overview) 페이지에 있는 **쿼리 URI (Query URI)**에서 호스트를 입력합니다. https://는 포함하지 마십시오. 예: trd-abc123.z9.kusto.fabric.microsoft.com.

4. **KQL 데이터베이스 (KQL database)**에 대상 데이터베이스의 이름을 입력합니다.

5. **테이블 (Table)**에 대상 테이블의 이름을 입력합니다.

6. **수집 매핑 (Ingestion mapping)**에 해당 테이블에 생성된 JSON 매핑의 이름을 입력합니다.

7. **열 (Columns)**에 쓸 Eventhouse 열마다 한 행을 추가합니다. 열 이름과 값을 입력합니다. 이름은 비어 있지 않고 고유해야 합니다. 값은 고정된 텍스트이거나 웹훅 본문과 동일한 매크로인 {{tag:Name}}과 같은 트래블러 매크로일 수 있습니다. 또는 **동적 값 삽입 (Insert Dynamic Value)**을 클릭하여 이 Journey의 이전 단계에서 생성된 속성(예: LLM 응답 또는 매핑된 웹훅 값)을 선택합니다.

예시

**테이블 (Table)**을 Events로 설정하고 **열 (Columns)**을 트래블러의 디바이스 ID({{device:hwid}})로 device_id로 설정하면 해당 테이블의 device_id 열에 행이 기록됩니다.

8. **저장 (Save)**을 클릭합니다.

응답

트래블러는 캔버스에서 다음에 연결하는 단계로 계속 진행합니다.

단계 실행 후 속성

이 지점은 응답 데이터를 Journey로 다시 매핑하지 않습니다.

실패 및 예기치 않은 응답

지점의 드로어에서 호출 로그를 열고 응답을 확인하십시오:

• 401 또는 403 — 연결된 Entra ID 애플리케이션의 자격 증명 또는 ingestor 역할이 잘못되었거나 누락되었습니다.
• 520 및 StreamingIngestionException: Failed to initialize cursor tracker... — KQL 데이터베이스의 스트리밍 수집 정책이 활성화되지 않았습니다. 오류 자체의 permanent: false 플래그는 “나중에 재시도”로 읽히지만, 재시도해도 이 문제가 해결되지는 않습니다. Eventhouse의 쿼리 창에서 .alter database ['<database name>'] policy streamingingestion enable을 실행하십시오(시작하기 전에 참조).

요청이 실패하면 트래블러는 Journey에서 제외됩니다. 오류 및 실패한 요청을 참조하십시오.

예시 시나리오: Journey 활동을 Fabric 대시보드로 스트리밍하기

한 팀이 배치 내보내기를 기다리지 않고 활성 Journey에서 도달한 모든 단계의 실시간 대시보드를 원합니다.

1. 추적하려는 단계 바로 뒤에 **Microsoft Fabric: 행 수집 (Microsoft Fabric: ingest row)**을 추가합니다. **KQL 데이터베이스 (KQL database)**를 am-test로, **테이블 (Table)**을 Events로, **수집 매핑 (Ingestion mapping)**을 EventsJsonMapping으로 설정합니다. **열 (Columns)**에서 device_id를 {{device:hwid}}로 설정합니다.
2. **저장 (Save)**을 클릭합니다.

이것이 실행되면, 이 단계에 도달하는 각 트래블러는 몇 초 내에 Eventhouse 테이블에 나타나 대시보드에 사용할 수 있게 됩니다.