Azure Digital Twins에서 엔드포인트 만들기

아티클
02/23/2024

이 문서에서는 Azure Portal 또는 Azure CLI를 사용하여 Azure Digital Twin 이벤트 엔드포인트를 만드는 방법을 설명합니다. DigitalTwinsEndpoint 컨트롤 플레인 API를 사용하여 엔드포인트를 관리할 수도 있습니다.

Azure Digital Twins에서 다운스트림 서비스 또는 연결된 컴퓨팅 리소스로 이벤트 알림을 라우팅하는 것은 2단계 프로세스입니다. 엔드포인트를 만든 다음 해당 엔드포인트로 데이터를 보낼 이벤트 경로를 만듭니다. 이 문서에서는 이벤트를 수신할 수 있는 엔드포인트를 설정하는 첫 번째 단계를 설명합니다. 그런 다음, Azure Digital Twins에서 생성된 이벤트가 어떤 엔드포인트로 전달되는지 지정하는 이벤트 경로를 만들 수 있습니다.

필수 조건

무료로 설정할 수 있는 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를 실행합니다.

필수 리소스 만들기

다음 서비스는 인스턴스에 대해 만들 수 있는 지원되는 엔드포인트 유형입니다.

Event Grid 토픽
- Event Grid 엔드포인트의 경우 Event Grid 토픽만 지원됩니다. Event Grid 도메인은 엔드포인트로 지원되지 않습니다.
Event Hubs 허브
Service Bus 토픽

엔드포인트를 Azure Digital Twins에 연결하려면 엔드포인트에 사용 중인 이벤트 허브 또는 Service Bus 토픽이 이미 있어야 합니다.

다음 차트를 사용하여 엔드포인트를 만들기 전에 설정해야 하는 리소스를 확인합니다.

엔드포인트 유형	필수 리소스(생성 지침에 연결됨)
Event Grid 엔드포인트	Event Grid 토픽 *이벤트 스키마는 Event Grid 스키마 또는 클라우드 이벤트 스키마 v1.0이어야 합니다.
Event Hubs 엔드포인트	Event Hubs 네임스페이스 이벤트 허브 (선택 사항) 키 기반 인증에 대한 권한 부여 규칙
서비스 버스 엔드포인트	Service Bus 네임스페이스 Service Bus 토픽 (선택 사항) 키 기반 인증에 대한 권한 부여 규칙

엔드포인트 만들기

엔드포인트 리소스를 만든 후에는 Azure Digital Twins 엔드포인트에 사용할 수 있습니다.

포털
CLI

새 엔드포인트를 만들려면 Azure Portal의 인스턴스 페이지로 이동합니다. 포털 검색 창에 해당 이름을 입력하여 인스턴스를 찾을 수 있습니다.

인스턴스 메뉴에서 엔드포인트를 선택합니다. 그런 다음, 뒤에 오는 엔드포인트 페이지에서 + 엔드포인트 만들기를 선택합니다. 그러면 다음 단계에서 필드를 입력할 엔드포인트 만들기 페이지가 열립니다.
엔드포인트의 이름을 입력하고 엔드포인트 유형을 선택합니다.
위에서 설명하는 구독과 엔드포인트 리소스를 비롯하여, 엔드포인트 유형에 필요한 다른 세부 정보를 완료합니다.
1. Event Hubs 및 Service Bus 엔드포인트에 대해서만 인증 유형을 선택해야 합니다. 미리 만든 권한 부여 규칙 또는 시스템 할당 또는 사용자가 할당한 관리 ID에서 키 기반 인증을 사용할 수 있습니다. ID 인증 옵션을 사용하는 방법에 대한 자세한 내용은 엔드포인트 옵션: ID 기반 인증을 참조하세요.
저장을 선택하여 엔드포인트 만들기를 완료합니다.

엔드포인트를 만든 후 Azure Portal의 위쪽 표시줄에서 알림 아이콘을 확인하여 엔드포인트가 만들어졌는지 확인할 수 있습니다.

Azure Portal에서 엔드포인트 생성을 확인하는 알림의 스크린샷.

엔드포인트 만들기가 실패하면 오류 메시지가 표시되며 몇 분 후 다시 시도합니다.

Azure Digital Twins 인스턴스의 엔드포인트 페이지로 돌아가서 만든 엔드포인트를 확인할 수도 있습니다.

이제 Event Grid 토픽, 이벤트 허브 또는 Service Bus 토픽을 엔드포인트에 대해 선택한 이름 아래 Azure Digital Twins의 엔드포인트로 사용할 수 있습니다. 일반적으로 경로 및 필터 만들기에서 만들 수 있는 이벤트 경로의 대상으로 해당 이름을 사용합니다.

다음 예제에서는 Azure Digital Twins CLI에 대해 az dt endpoint create 명령을 사용하여 엔드포인트를 만드는 방법을 보여 줍니다. 명령의 자리 표시자를 사용자 고유의 리소스 세부 정보로 바꿉니다.

Event Grid 엔드포인트를 생성하려면 다음을 수행합니다.

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Event Hubs 엔드포인트(키 기반 인증)를 생성하려면 다음을 수행합니다.

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Service Bus 토픽 엔드포인트(키 기반 인증)를 생성하려면 다음을 수행합니다.

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

이러한 명령을 성공적으로 실행한 후에는 Event Grid, 이벤트 허브 또는 Service Bus 토픽을 --endpoint-name 인수로 제공한 이름 아래 Azure Digital Twins의 엔드포인트로 사용할 수 있습니다. 일반적으로 경로 및 필터 만들기에서 만들 수 있는 이벤트 경로의 대상으로 해당 이름을 사용합니다.

엔드포인트 옵션: ID 기반 인증

이 섹션에서는 지원되는 라우팅 대상으로 이벤트를 전달할 때 Azure Digital Twins 인스턴스에 대한 관리 ID를 사용하는 방법을 설명합니다. 라우팅에 관리 ID를 설정할 필요는 없지만 인스턴스가 Event Hub, Service Bus, 대상 및 Azure Storage Container와 같은 다른 Microsoft Entra 보호 리소스에 쉽게 액세스하는 데 도움이 될 수 있습니다. 관리 ID는 시스템 할당 또는 사용자 할당일 수 있습니다.

이 섹션의 나머지 부분에서는 관리 ID를 사용하여 엔드포인트를 설정하기 위한 세 단계를 안내합니다.

1. 인스턴스에 관리 ID 사용

기본 설정 환경과 일치하는 지침은 아래 탭을 사용합니다.

포털
CLI

먼저 Azure Digital Twins 인스턴스 관리 ID를 사용하도록 설정했는지 확인합니다.

그런 다음 인스턴스에 대한 Azure Digital Twins 데이터 소유자 역할이 있는지 확인합니다. 사용자 액세스 권한 설정에서 지침을 찾을 수 있습니다.

2. ID에 Azure 역할 할당

Azure Digital Twins 인스턴스에 대해 관리 ID가 생성되면 지원되는 대상으로의 이벤트 라우팅을 위해 다른 유형의 엔드포인트에 인증하기 위해 적합한 역할을 할당해야 합니다. 이 섹션에서는 역할 옵션 및 관리 ID에 이를 할당하는 방법을 설명합니다.

Important

이 단계를 완료했는지 확인합니다. 이 단계가 없으면 ID가 엔드포인트에 액세스할 수 없고 이벤트가 전달되지 않습니다.

대상 유형에 따라 Azure Digital Twins ID가 엔드포인트에 액세스해야 하는 최소 역할은 다음과 같습니다. 높은 권한의 역할(예: 데이터 소유자 역할)도 작동합니다.

대상	Azure 역할
Azure Event Hubs	Azure Event Hubs 데이터 보내는 사람
Azure Service Bus	Azure Service Bus 데이터 보내는 사람
Azure 스토리지 컨테이너	Storage Blob 데이터 Contributor

아래 탭을 사용하여 원하는 환경을 통해 역할을 할당합니다.

포털
CLI

ID에 역할을 할당하려면 브라우저에서 Azure Portal을 열어 시작합니다.

포털 검색 창에서 해당 이름을 검색하여 엔드포인트 리소스(Event Hub, Service Bus 토픽 또는 스토리지 컨테이너)로 이동합니다.
액세스 제어(IAM) 를 선택합니다.
역할 할당 추가>를 선택하여 역할 할당 추가 페이지를 엽니다.

아래 정보를 사용하여 Azure Digital Twins 인스턴스의 관리 ID에 원하는 역할을 할당합니다. 세부 단계에 대해서는 Azure Portal을 사용하여 Azure 역할 할당을 참조하세요.

설정	값
역할	드롭다운 메뉴에서 원하는 역할을 선택합니다.
다음에 대한 액세스 할당	관리 ID
멤버	역할을 할당하는 Azure Digital Twins 인스턴스의 사용자 할당 또는 시스템이 할당한 관리 ID를 선택합니다. 사용자 할당 ID에는 ID를 만들 때 선택한 이름이 있으며 시스템 할당 ID에는 Azure Digital Twins 인스턴스 이름과 일치하는 이름이 있습니다.

지정된 역할을 사용하여 하나 이상의 범위에 ID를 할당하기 위해 az dt create 명령에 --scopes 매개 변수를 추가할 수 있습니다. 이 매개변수가 있는 명령은 인스턴스를 처음 만들 때 또는 나중에 이미 존재하는 인스턴스의 이름을 전달하여 사용할 수 있습니다.

다음은 시스템이 할당한 관리 ID를 사용하여 인스턴스를 만들고 해당 ID에 이벤트 허브에서 MyCustomRole이라는 사용자 지정 역할을 할당하는 예입니다.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

이 명령을 사용한 역할 할당에 대한 추가 예제는 az dt create 참조 설명서를 참조하세요.

az role assignment 명령 그룹을 사용하여 역할을 만들고 관리할 수도 있습니다. 이 명령은 만들기 명령을 사용하여 역할 할당을 그룹화하지 않으려는 다른 시나리오를 지원하는 데 사용할 수 있습니다.

3. ID 기반 인증을 사용하여 엔드포인트 만들기

Azure Digital Twins 인스턴스에 대해 관리 ID를 설정하고 여기에 적합한 역할을 할당한 후에는 이 ID를 인증에 사용하는 엔드포인트를 만들 수 있습니다. 이 옵션은 Event Hubs 및 Service Bus 유형 엔드포인트에만 사용할 수 있습니다(Event Grid에는 지원되지 않음).

참고 항목

ID 기반 인증으로 변경하기 위해 키 기반 ID로 이미 생성된 엔드포인트를 편집할 수 없습니다. 엔드포인트를 처음 만들 때 인증 유형을 선택해야 합니다.

아래 탭을 사용하여 원하는 환경을 통해 엔드포인트를 만듭니다.

포털
CLI

Azure Digital Twins 엔드포인트 만들기 일반 지침에 따라 시작합니다.

엔드포인트 유형에 필요한 세부 정보를 작성하는 단계에서 인증 유형으로 시스템 할당 또는 사용자 할당(미리 보기)을 선택합니다.

엔드포인트 설정을 완료하고 저장을 선택합니다.

관리 ID는 엔드포인트를 만드는 데 사용되는 az dt endpoint create 명령에 매개 변수를 추가하여 엔드포인트에 추가됩니다. (이 명령에 대한 자세한 내용은 해당 참조 설명서 또는 Azure Digital Twins 엔드포인트 만들기 일반 지침을 참조하세요.).

선택한 유형의 관리 ID에 대해 아래 CLI 명령을 사용합니다.

시스템 할당 ID 명령

시스템 할당 인증을 사용하는 엔드포인트를 만들려면 --auth-type 매개 변수를 사용하여 IdentityBased 인증 유형을 지정합니다. 아래 예에서는 Event Hubs 엔드포인트에 대한 이 기능을 보여 줍니다.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

사용자 할당 ID 명령

사용자 할당 ID 인증을 사용하는 엔드포인트를 만들려면 --user 매개 변수를 사용하여 사용자 할당 ID 리소스 ID를 지정합니다. 아래 예에서는 Event Hubs 엔드포인트에 대한 이 기능을 보여 줍니다.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

관리 ID를 사용하지 않도록 설정할 때 고려 사항

ID는 이를 사용하는 엔드포인트와 별개로 관리되기 때문에 ID 또는 해당 역할에 대한 변경 사항이 Azure Digital Twins 인스턴스의 엔드포인트에 미칠 수 있는 영향을 고려하는 것이 중요합니다. ID를 사용하지 않도록 설정하거나 엔드포인트에 필요한 역할이 제거된 경우 엔드포인트에 액세스할 수 없게 되고 이벤트 흐름이 중단됩니다.

이제 사용하지 않도록 설정된 관리 ID로 설정된 엔드포인트를 계속 사용하려면 엔드포인트를 삭제하고 다른 인증 유형을 사용해서 다시 만들어야 합니다. 이렇게 변경한 후 엔드포인트에 대해 이벤트 전달이 재개되려면 최대 1시간까지 걸릴 수 있습니다.

엔드포인트 옵션: 배달 못한 편지

엔드포인트가 특정 기간 내에 이벤트를 전달할 수 없거나 특정 횟수만큼 이벤트를 전달하려고 시도한 후 이벤트를 전달할 수 없는 경우 배달되지 않은 이벤트를 스토리지 계정으로 보낼 수 있습니다. 이 프로세스를 배달 못한 편지 처리라고 합니다.

Azure Portal 또는 Azure Digital Twins CLI를 사용하여 필요한 스토리지 리소스를 설정할 수 있습니다. 그렇지만 배달 못한 편지를 사용하는 엔드포인트를 만들려면 Azure Digital Twins CLI 또는 컨트롤 플레인 API를 사용해야 합니다.

배달 못한 편지에 대한 자세한 내용은 엔드포인트 및 이벤트 경로를 참조하세요. 배달 못한 편지를 사용하여 엔드포인트를 설정하는 방법에 대한 지침은 이 섹션의 나머지 부분에서 이어집니다.

스토리지 리소스 설정

배달 못한 편지 위치를 설정하기 전에 Azure 계정에 설정된 컨테이너가 있는 스토리지 계정이 있어야 합니다.

나중에 엔드포인트를 만들 때 이 컨테이너에 대한 URI를 제공합니다. 배달 못한 편지 위치는 SAS 토큰이 있는 컨테이너 URI로 엔드포인트에 제공됩니다. 이 토큰에는 스토리지 계정 내의 대상 컨테이너에 대한 write 권한이 필요합니다. 완전히 구성된 배달 못한 편지 SAS URI의 형식은 다음과 같습니다. https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

아래 단계에 따라 Azure 계정에서 이러한 스토리지 리소스를 설정하고 다음 섹션에서 엔드포인트 연결 설정을 준비합니다.

스토리지 계정 만들기의 단계에 따라 Azure 구독에서 스토리지 계정을 만듭니다. 나중에 사용할 수 있도록 스토리지 계정 이름을 적어 둡니다.
컨테이너 만들기의 단계에 따라 새 스토리지 계정 내에 컨테이너를 만듭니다. 나중에 사용할 수 있도록 컨테이너 이름을 적어 둡니다.

SAS 토큰 만들기

그런 다음, 엔드포인트가 액세스하는 데 사용할 수 있는 스토리지 계정에 대한 SAS 토큰을 만듭니다.

포털
CLI

Azure Portal에서 스토리지 계정으로 이동하여 시작합니다(포털 검색 창에서 이름으로 찾을 수 있음).
스토리지 계정 페이지에서 왼쪽 탐색 모음의 공유 액세스 서명 링크를 선택하여 SAS 토큰 설정을 시작합니다.
공유 액세스 서명 페이지의 허용되는 서비스 및 허용되는 리소스 종류에서 원하는 설정을 선택합니다. 각 범주에서 하나 이상의 상자를 선택해야 합니다. 허용되는 권한에서 쓰기를 선택합니다(원하는 경우 다른 권한도 선택할 수도 있음).
나머지 설정에 대해 원하는 값을 설정합니다.
완료되면 SAS 및 연결 문자열 생성 단추를 선택하여 SAS 토큰을 생성합니다.
이렇게 하면 동일한 페이지 하단의 설정 선택 아래에 여러 SAS 및 연결 문자열 값이 생성됩니다. 아래로 스크롤하여 해당 값을 확인하고 클립보드에 복사 아이콘을 사용하여 SAS 토큰 값을 복사합니다. 나중에 사용할 수 있도록 저장합니다.

다음 명령을 사용하여 스토리지 계정 키를 검색하고 키 중 하나에 대한 값을 복사합니다.
```
az storage account keys list --account-name <storage-account-name>
```
다음 명령을 사용하여 만료 날짜를 선택하고 스토리지 계정에 대한 SAS 토큰을 생성합니다.
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
이 명령의 출력은 SAS 토큰입니다. 나중에 사용할 SAS 토큰 값을 복사합니다.

참고 항목

이 명령은 "blob", "file", "queue" 및 "table" services와 "개체" 리소스 종류를 포함하고 "쓰기" 권한을 허용합니다.

az storage account generate-sas 명령과 해당 매개 변수에 대한 자세한 내용은 Azure CLI 참조서를 참조하세요.

배달 못한 편지를 사용하는 엔드포인트를 만들려면 Azure Portal이 아니라 CLI 명령 또는 컨트롤 플레인 API를 사용하여 엔드포인트를 만들어야 합니다.

Azure CLI를 사용하여 이 유형의 엔드포인트를 만드는 방법에 대한 지침을 보려면 이 섹션의 CLI 탭으로 전환합니다.

배달 못한 편지를 사용하는 엔드포인트를 만들려면 az dt endpoint create 명령에 --deadletter-sas-uri 매개 변수를 추가하여 엔드포인트를 만듭니다.

이 매개 변수의 값은 이전 섹션에서 수집한 스토리지 계정 이름, 컨테이너 이름 및 SAS 토큰으로 구성된 배달 못한 편지 SAS URI입니다. 이 매개 변수는 키 기반 인증을 사용하여 엔드포인트를 만듭니다. 매개 변수는 다음과 같습니다.

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

팁

ID 기반 인증을 사용하여 배달 못한 편지 엔드포인트를 만들려면 이 섹션의 배달 못한 편지 매개 변수와 적절한 관리 ID 매개 변수를 모두 동일한 명령에 추가합니다.

또는 CLI 대신 Azure Digital Twins 컨트롤 플레인 API를 사용하여 배달 못한 편지 엔드포인트를 만들 수도 있습니다. 이렇게 하려면 DigitalTwinsEndpoint 설명서를 참조하여 요청을 구조화하고 배달 못한 편지 매개 변수를 추가하는 방법을 확인합니다.

메시지 스토리지 스키마

배달 못한 편지를 사용하는 엔드포인트가 설정되면 배달 못한 편지 메시지가 다음 형식으로 스토리지 계정에 저장됩니다.

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

배달 못한 편지 메시지는 원래 엔드포인트로 전달되도록 의도된 원래 이벤트의 스키마와 일치합니다.

다음은 트윈 생성 알림에 대한 배달 못한 편지 메시지의 예제입니다.

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

다음 단계

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

다음을 통해 공유