Azure Digital Twins에서 이벤트 경로 및 필터 만들기

이 문서에서는 Azure Portal, Azure CLI az dt route 명령, 이벤트 경로 데이터 평면 API 및 .NET(C#) SDK를 사용하여 이벤트 경로를 만드는 과정을 안내합니다.

Azure Digital Twins에서 다운스트림 서비스 또는 연결된 컴퓨팅 리소스로 이벤트 알림을 라우팅하는 것은 2단계 프로세스입니다. 엔드포인트를 만든 다음 해당 엔드포인트로 데이터를 보낼 이벤트 경로를 만듭니다. 이 문서에서는 Azure Digital Twin 엔드포인트에 배달되는 이벤트를 제어하는 경로를 설정하는 두 번째 단계를 다룹니다. 이 문서를 진행하려면 엔드포인트가 이미 만들어져 있어야 합니다.

필수 조건

• 무료로 설정할 수 있는 Azure 계정이 필요합니다.

• Azure 구독에는 Azure Digital Twins 인스턴스가 필요합니다. 인스턴스가 아직 없는 경우 인스턴스 및 인증 설정의 단계를 사용하여 만들 수 있습니다. 이 문서의 뒷부분에서 쉽게 사용할 수 있도록 설정에서 다음 값을 가져옵니다.

  • 인스턴스 이름
  • Resource group

  인스턴스를 설정한 후 Azure Portal에서 이 세부 정보를 확인할 수 있습니다.

  

• 엔드포인트 만들기의 지침에 따라 엔드포인트를 만듭니다. 이 문서에서는 해당 엔드포인트로 데이터를 보내는 경로를 만듭니다.

다음으로 이 가이드를 수행하는 동안 Azure CLI를 사용하려는 경우 아래 지침을 따르세요.

Azure CLI에 대한 환경 준비

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

이벤트 경로 만들기

엔드포인트를 만든 후에 실제로 데이터를 엔드포인트로 보내려면 이벤트 경로를 정의해야 합니다. 이러한 경로를 통해 개발자는 시스템을 거쳐 다운스트림 서비스로 이벤트 흐름을 보낼 수 있습니다. 단일 경로에서 여러 알림과 이벤트 유형을 선택하도록 허용할 수 있습니다. 엔드포인트 및 이벤트 경로에서 이벤트 경로에 대해 자세히 알아보세요.

참고 항목

경로 만들기로 이동하기 전에 필수 조건에 설명된 대로 엔드포인트를 하나 이상 만들었는지 확인합니다.

최근에 사용자 엔드포인트만 배포한 경우 새 이벤트 경로에 해당 엔드포인트를 사용하기 전에 배포가 완료되었는지 확인합니다. 엔드포인트가 준비되지 않아 경로 배포가 실패하면 몇 분 정도 기다렸다가 다시 시도합니다.

이 흐름을 스크립팅하는 경우 경로 설정을 진행하기 전에 엔드포인트 서비스가 배포를 완료할 때까지 2-3분 동안 대기 시간을 구축하여 이 문제를 해결할 수 있습니다.

경로 정의에는 다음 요소가 포함될 수 있습니다.

• 사용하려는 경로 이름
• 사용하려는 엔드포인트 이름
• 엔드포인트로 전송되는 이벤트를 정의하는 필터
  • 보내는 이벤트가 없게 경로를 사용하지 않도록 설정하려면 필터 값 false를 사용합니다.
  • 특정 필터링이 없는 경로를 사용하도록 설정하려면 필터 값 true를 사용합니다.
  • 다른 유형의 필터에 대한 자세한 내용은 아래의 필터 이벤트 섹션을 참조하세요.

경로 이름이 없으면 Azure Digital Twins 외부로 메시지가 라우팅되지 않습니다. 경로 이름이 있고 필터가 true이면 모든 메시지가 엔드포인트로 라우팅됩니다. 경로 이름이 있고 다른 필터가 추가된 경우 메시지가 해당 필터를 기반으로 필터링됩니다.

이벤트 경로는 Azure Portal, EventRoutes 데이터 평면 API 또는 az dt route CLI 명령을 사용하여 만들 수 있습니다. 이 섹션의 나머지 부분에서 만들기 프로세스를 안내합니다.

포털

이벤트 경로를 만들려면 Azure Portal에서 Azure Digital Twins 인스턴스에 대한 세부 정보 페이지로 이동합니다. 포털 검색 창에 해당 이름을 입력하여 인스턴스를 찾을 수 있습니다.

인스턴스 메뉴에서 이벤트 경로를 선택합니다. 그런 다음, 이어지는 이벤트 경로 페이지에서 + 이벤트 경로 만들기를 선택합니다.

열리는 이벤트 경로 만들기 페이지에서 최소한 다음을 선택합니다.

• 이름 필드에서 경로 이름
• 경로를 만드는 데 사용할 엔드포인트

경로를 사용하려면 적어도 true인 이벤트 경로 필터도 추가해야 합니다. (기본값 false를 그대로 두면 경로는 생성되나 이벤트를 해당 경로로 보내지 않습니다.) 이렇게 하려면 고급 편집기에 대한 스위치를 전환하여 사용하도록 설정하고 필터 상자에 true를 기입합니다.

완료되면 저장 단추를 선택하여 이벤트 경로를 만듭니다.

CLI

Azure Digital Twins CLI에 대한 az dt route 명령을 사용하여 경로를 관리할 수 있습니다.

CLI 사용 및 사용 가능한 명령에 대한 자세한 내용은 Azure Digital Twins CLI 명령 집합을 참조하세요.

.NET SDK

이 섹션에서는 .NET(C#) SDK를 사용하여 이벤트 경로를 만드는 방법을 보여 줍니다.

CreateOrReplaceEventRouteAsync는 이벤트 경로를 추가하는 데 사용되는 SDK 호출입니다. 사용 예제는 다음과 같습니다.

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

팁

모든 SDK 함수는 동기 및 비동기 버전으로 제공됩니다.

이벤트 경로 샘플 SDK 코드

다음 샘플 메서드는 C# SDK를 사용하여 이벤트 경로를 만들고, 나열하고, 삭제하는 방법을 보여 줍니다.

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

이벤트 필터링

위에서 설명한 것처럼 경로에는 필터 필드가 있습니다. 경로의 필터 값이 false라면 엔드포인트로 보내는 이벤트가 없습니다.

true의 최소 필터를 사용하도록 설정한 후 엔드포인트는 Azure Digital Twins에서 다양한 종류의 이벤트를 수신합니다.

• Azure Digital Twins 서비스 API를 사용하여 디지털 트윈에서 발생된 원격 분석
• Azure Digital Twins 인스턴스의 모든 트윈에 대한 속성 변경 시 발생하는 트윈 속성 변경 알림
• 트윈 또는 관계를 만들거나 삭제했을 때 발생하는 수명 주기 이벤트

더 구체적인 필터를 정의하면 전송되는 이벤트 유형을 제한할 수 있습니다.

참고 항목

필터는 대/소문자를 구분하며 페이로드 대/소문자와 일치해야 합니다. 원격 분석 필터의 경우 대/소문자를 디바이스에서 보낸 원격 분석의 대/소문자와 일치시켜야 합니다.

포털

이벤트 경로를 만드는 동안 이벤트 필터를 추가하려면 이벤트 경로 만들기 페이지의 이벤트 경로 필터 추가 섹션을 사용합니다.

몇 가지 기본 공통 필터 옵션에서 선택하거나, 고급 필터 옵션을 사용하여 직접 사용자 지정 필터를 작성할 수 있습니다.

기본 필터 사용

기본 필터를 사용하려면 이벤트 유형 옵션을 확장하고, 엔드포인트에 보내려는 이벤트에 해당하는 확인란을 선택합니다.

그러면 선택한 필터의 텍스트로 필터 텍스트 상자가 자동 입력됩니다.

고급 필터 사용

고급 필터 옵션을 사용하여 고유한 사용자 지정 필터를 작성할 수 있습니다.

고급 필터 옵션을 사용하여 이벤트 경로를 만들려면 고급 편집기에 대한 스위치를 전환하여 사용하도록 설정합니다. 그런 다음, 필터 상자에서 고유의 이벤트 필터를 작성할 수 있습니다.

API

이벤트 경로 데이터 평면 API를 사용하여 사용자 지정 필터를 작성할 수 있습니다. 필터를 추가하려면 다음 본문에서 https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31에 대한 PUT 요청을 사용하면 됩니다.

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

지원되는 경로 필터

다음은 지원되는 경로 필터입니다.

필터 이름	설명	텍스트 스키마 필터링	지원되는 값
True / False	필터링 없이 경로를 만들거나, 이벤트를 보내지 않도록 경로를 비활성화할 수 있습니다.	<true/false>	true = 경로가 필터링 없이 활성화됨 false = 경로가 비활성화됨
Type	디지털 트윈 인스턴스를 통해 흐르는 이벤트 유형	type = '<event-type>'	가능한 이벤트 유형 값은 다음과 같습니다. Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
원본	Azure Digital Twins 인스턴스의 이름	source = '<host-name>'	가능한 호스트 이름 값은 다음과 같습니다. 알림의 경우: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net 원격 분석의 경우: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
Subject	위의 이벤트 원본의 컨텍스트에 있는 이벤트 설명	subject = '<subject>'	가능한 주체 값은 다음과 같습니다. 알림의 경우: 제목은 <twin-ID>입니다. 또는 여러 부분이나 ID로 고유하게 식별되는 주체에 대한 URI 형식: <twin-ID>/relationships/<relationship-ID> 원격 분석의 경우: 제목은 comp1.comp2와 같은 구성 요소 경로(트윈 구성 요소에서 원격 분석을 내보내는 경우)입니다. 구성 요소에서 원격 분석을 내보내지 않으면 해당 제목 필드가 비어 있습니다.
데이터 스키마	DTDL 모델 ID	dataschema = '<model-dtmi-ID>'	원격 분석의 경우: 데이터 스키마는 원격 분석을 내보내는 트윈 또는 구성 요소의 모델 ID입니다. 예를 들어 dtmi:example:com:floor4;2 알림(만들기/삭제)의 경우: 데이터 스키마는 $body.$metadata.$model의 알림 본문에서 액세스할 수 있습니다. 알림(업데이트)의 경우: 데이터 스키마는 $body.modelId의 알림 본문에서 액세스할 수 있습니다.
내용 유형	데이터 값의 콘텐츠 형식	datacontenttype = '<content-type>'	콘텐츠 형식은 application/json입니다.
사양 버전	사용 중인 이벤트 스키마의 버전	specversion = '<version>'	버전은 1.0이어야 합니다. 이 값은 CloudEvents 스키마 버전 1.0을 나타냅니다.
알림 본문	알림의 data 필드에 있는 모든 속성 참조	$body.<property>	알림 예시는 이벤트 알림을 참조하세요. data 필드의 모든 속성은 $body를 사용하여 참조할 수 있습니다.

참고 항목

Azure Digital Twins는 현재 배열 내의 필드를 기반으로 하는 이벤트 필터링을 지원하지 않습니다. 여기에는 디지털 트윈 변경 알림의 patch 섹션 내 속성 필터링이 포함됩니다.

위의 데이터에 대한 참조로 반환되는 값으로 지원되는 데이터 형식은 다음과 같습니다.

데이터 형식	예시
문자열	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
정수	$body.errorCode > 200
Double	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

경로 필터를 정의할 때 지원되는 연산자는 다음과 같습니다.

패밀리	연산자	예시
논리	AND, OR, ( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
비교	<, <=, >, >=, =, !=	$body.temperature <= 5.5

경로 필터를 정의할 때 지원되는 함수는 다음과 같습니다.

함수	Description	예시
STARTS_WITH(x,y)	값 x가 문자열 y로 시작하면 true를 반환합니다.	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x, y)	값 x가 문자열 y로 끝나면 true를 반환합니다.	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	값 x에 문자열 y가 포함된 경우 true를 반환합니다.	CONTAINS(subject, '<twin-ID>')

필터를 구현하거나 업데이트하는 경우 변경 내용이 데이터 파이프라인에 반영되는 데 몇 분 정도 걸릴 수 있습니다.

이벤트 경로 모니터링

개수, 대기 시간 및 실패율과 같은 라우팅 메트릭은 Azure Portal에서 볼 수 있습니다.

Azure Monitor를 사용하여 메트릭을 보고 관리하는 방법에 대한 자세한 내용은 메트릭 탐색기 시작을 참조하세요. Azure Digital Twins에 사용할 수 있는 라우팅 메트릭의 전체 목록은 Azure Digital Twins 라우팅 메트릭을 참조하세요.

다음 단계

받을 수 있는 다양한 이벤트 메시지 유형에 대해 읽어 보세요.

• 이벤트 알림