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

이 문서에서는 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에서 이 세부 정보를 확인할 수 있습니다.

    Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted.

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

Azure CLI에 대한 환경 준비

필수 리소스 만들기

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

  • 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 엔드포인트에 사용할 수 있습니다.

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

  1. 인스턴스 메뉴에서 엔드포인트를 선택합니다. 그런 다음, 뒤에 오는 엔드포인트 페이지에서 + 엔드포인트 만들기를 선택합니다. 그러면 다음 단계에서 필드를 입력할 엔드포인트 만들기 페이지가 열립니다.

    Screenshot of creating an endpoint of type Event Grid in the Azure portal.

  2. 엔드포인트의 이름을 입력하고 엔드포인트 유형을 선택합니다.

  3. 위에서 설명하는 구독과 엔드포인트 리소스를 비롯하여, 엔드포인트 유형에 필요한 다른 세부 정보를 완료합니다.

    1. Event Hubs 및 Service Bus 엔드포인트에 대해서만 인증 유형을 선택해야 합니다. 미리 만든 권한 부여 규칙 또는 시스템 할당 또는 사용자가 할당한 관리 ID에서 키 기반 인증을 사용할 수 있습니다. ID 인증 옵션을 사용하는 방법에 대한 자세한 내용은 엔드포인트 옵션: ID 기반 인증을 참조하세요.

    Screenshot of creating an endpoint of type Event Hubs in the Azure portal.

  4. 저장을 선택하여 엔드포인트 만들기를 완료합니다.

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

Screenshot of the notification to verify the creation of an endpoint in the Azure portal.

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

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

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

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

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

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

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

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

먼저 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

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

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

  1. 포털 검색 창에서 해당 이름을 검색하여 엔드포인트 리소스(Event Hub, Service Bus 토픽 또는 스토리지 컨테이너)로 이동합니다.

  2. 액세스 제어(IAM) 를 선택합니다.

  3. 역할 할당 추가>를 선택하여 역할 할당 추가 페이지를 엽니다.

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

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

    Screenshot of the 'Add role assignment' page for an Azure Digital Twins instance.

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

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

참고 항목

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

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

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

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

Screenshot of creating an endpoint of type Event Hubs.

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

관리 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 계정에서 이러한 스토리지 리소스를 설정하고 다음 섹션에서 엔드포인트 연결 설정을 준비합니다.

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

SAS 토큰 만들기

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

  1. Azure Portal에서 스토리지 계정으로 이동하여 시작합니다(포털 검색 창에서 이름으로 찾을 수 있음).

  2. 스토리지 계정 페이지에서 왼쪽 탐색 모음의 공유 액세스 서명 링크를 선택하여 SAS 토큰 설정을 시작합니다.

    Screenshot of the storage account page in the Azure portal.

  3. 공유 액세스 서명 페이지허용되는 서비스허용되는 리소스 종류에서 원하는 설정을 선택합니다. 각 범주에서 하나 이상의 상자를 선택해야 합니다. 허용되는 권한에서 쓰기를 선택합니다(원하는 경우 다른 권한도 선택할 수도 있음).

  4. 나머지 설정에 대해 원하는 값을 설정합니다.

  5. 완료되면 SAS 및 연결 문자열 생성 단추를 선택하여 SAS 토큰을 생성합니다.

    Screenshot of the storage account page in the Azure portal showing all the setting selection to generate a SAS token.

  6. 이렇게 하면 동일한 페이지 하단의 설정 선택 아래에 여러 SAS 및 연결 문자열 값이 생성됩니다. 아래로 스크롤하여 해당 값을 확인하고 클립보드에 복사 아이콘을 사용하여 SAS 토큰 값을 복사합니다. 나중에 사용할 수 있도록 저장합니다.

    Screenshot of the storage account page in the Azure portal highlighting how to copy the SAS token to use in the dead-letter secret.

배달 못한 편지 엔드포인트 만들기

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

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

메시지 스토리지 스키마

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

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