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

2025-06-19

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

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

필수 조건

무료로 설정할 수 있는 Azure 계정입니다.
Azure 구독의 Azure Digital Twins 인스턴스입니다. 인스턴스가 없는 경우 인스턴스 및 인증 설정의 단계에 따라 인스턴스를 만듭니다. 설치의 다음 값을 이후 문서에서 사용하기 위해 준비해 두십시오.
- 인스턴스 이름
- 리소스 그룹
인스턴스를 설정한 후 Azure Portal에서 이 세부 정보를 확인할 수 있습니다.

이 가이드를 따르는 동안 Azure CLI를 사용하려는 경우 다음 섹션의 지침을 따르세요.

Azure CLI에 대한 환경 준비

Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell 시작을 참조하세요.
CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.
- 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 Azure에 인증을 참조하세요.
- 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI를 사용하여 확장 사용 및 관리를 참조하세요.
- az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

필수 리소스 만들기

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

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

엔드포인트를 Azure Digital Twins에 연결하기 전에 엔드포인트에 사용하는 Event Grid 토픽, 이벤트 허브 또는 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를 사용하도록 설정한 경우에만 사용할 수 있습니다. 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 토픽을 Azure Digital Twins의 엔드포인트로 사용할 수 있습니다. 엔드포인트에는 인수와 함께 제공한 이름이 있습니다 --endpoint-name . 일반적으로 해당 이름을 이벤트 경로의 대상으로 사용하며, 경로 및 필터 만들기에서 경로를 생성할 수 있습니다.

엔드포인트 옵션: 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에 이를 할당하는 방법을 설명합니다.

중요한

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

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

목적지	Azure 역할
Azure Event Hubs	Azure Event Hubs 데이터 보내는 사람
Azure Service Bus (Azure 서비스 버스)	Azure Service Bus 데이터 보내는 사람
Azure 스토리지 컨테이너	Storage Blob 데이터 기여자

다음 탭을 사용하여 선호하는 경험을 통해 역할을 할당합니다.

포털
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를 할당하기 위해 --scopes 명령에 az dt create 매개 변수를 추가할 수 있습니다. 인스턴스를 처음 만들 때 또는 나중에 기존 인스턴스의 이름을 전달하여 이 명령을 사용합니다.

다음은 시스템이 할당한 관리 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 명령 그룹을 사용하여 역할을 만들고 관리할 수도 있습니다. 이 명령을 사용하여 create 명령을 사용하여 역할 할당을 그룹화하지 않으려는 다른 시나리오를 지원합니다.

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 명령

시스템 할당 인증을 사용하는 엔드포인트를 만들려면 IdentityBased 매개 변수를 사용하여 --auth-type 인증 유형을 지정합니다. 다음 예제에서는 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를 사용하는 엔드포인트와 별도로 관리되므로 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 bfqt), "object" 리소스 종류(--resource-types o) 및 "write" 권한(--permissions w)이 포함됩니다.

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

데드 레터링이 활성화된 엔드포인트를 만들려면 CLI 명령이나 컨트롤 플레인 API를 사용하십시오. Azure Portal에서는 이러한 유형의 엔드포인트를 만들 수 없습니다.

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

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

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

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

팁

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

Azure Digital Twins 컨트롤 플레인 API를 사용하여 데드 레터 엔드포인트를 생성할 수도 있습니다. CLI 대신 이 방법을 사용할 수 있습니다. 이렇게 하려면 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"
}

다음 단계

엔드포인트를 만든 후 엔드포인트에 데이터를 보내는 이벤트 경로를 정의합니다. 이벤트 경로를 사용하면 시스템 전체와 다운스트림 서비스에 이벤트 흐름을 설정할 수 있습니다. 단일 경로는 여러 알림 및 이벤트 유형을 허용할 수 있습니다. 엔드포인트로 이벤트 경로를 생성하려면 경로 및 필터 만들기를 참조하십시오.