Azure CLI를 사용하여 경로 및 엔드포인트 만들기 및 삭제

  • 아티클

이 문서에서는 Azure CLI를 사용하여 Azure IoT Hub 경로 및 엔드포인트를 관리하는 방법을 보여줍니다. Azure CLI를 사용하여 Azure Event Hubs, Azure Service Bus 큐 및 토픽, Azure Storage 및 Cosmos DB에 대한 경로 및 엔드포인트를 만드는 방법을 알아봅니다.

IoT Hub에서 라우팅의 작동 방식에 대한 자세한 내용은 IoT Hub 메시지 라우팅을 사용하여 디바이스-클라우드 메시지를 다른 엔드포인트로 보내기를 참조하세요. 메시지를 스토리지에 보내는 경로를 설정한 다음 시뮬레이션된 디바이스에서 테스트하는 방법을 알아보려면 자습서: IoT Hub 메시지 라우팅을 사용하여 디바이스 데이터를 Azure Storage로 보내기를 참조하세요.

필수 조건

문서에 설명된 절차는 다음 리소스를 사용합니다.

  • Azure CLI
  • IoT 허브
  • Azure의 엔드포인트 서비스

Azure CLI

이 문서에서는 IoT Hub 및 기타 Azure 서비스 작업에 Azure CLI를 사용합니다. Azure CLI에 액세스하는 방법을 선택할 수 있습니다.

IoT Hub

Azure 구독에서 IoT 허브가 필요합니다. 아직 허브가 없는 경우 Azure CLI를 사용하여 IoT 허브를 만드는 단계를 따를 수 있습니다.

엔드포인트 서비스

경로에 대한 엔드포인트로 사용하려면 하나 이상의 다른 Azure 서비스가 필요합니다. 엔드포인트는 디바이스 메시지 및 이벤트 로그를 받습니다.

라우트된 디바이스 및 이벤트 데이터를 수신하기 위해 엔드포인트로 사용할 Azure 서비스(이벤트 허브, 서비스 큐 또는 토픽, 스토리지 계정 또는 Cosmos DB 컨테이너)를 결정합니다. 사용하도록 선택한 서비스에 대해 엔드포인트 서비스를 만드는 단계를 완료합니다.

  1. Event Hubs 네임스페이스 및 이벤트 허브 만들기 자세한 내용은 빠른 시작: Azure CLI를 사용하여 이벤트 허브 만들기를 참조하세요.

  2. IoT Hub에 이벤트 허브로 데이터를 보낼 수 있는 권한을 부여하는 데 사용할 권한 부여 규칙을 만듭니다.

    팁

    name 매개 변수의 값 RootManageSharedAccessKey은 클레임 관리, 보내기, 수신을 허용하는(액세스) 기본 이름입니다. 클레임을 제한하려는 경우 name 매개 변수에 자신의 고유한 이름을 부여하고 --rights 플래그와 클레임 중 하나를 포함합니다. 예: --name my-name --rights Send.

    az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey

    자세한 내용은 Azure Event Hubs에 대한 액세스 권한 부여를 참조하세요.

엔드포인트 만들기

모든 IoT Hub 경로는 라우트된 디바이스 및 이벤트 데이터를 수신하는 엔드포인트를 가리킵니다. 둘 이상의 경로가 동일한 엔드포인트를 가리킬 수 있습니다. 현재 IoT Hub는 Event Hubs, Service Bus 큐 또는 토픽, 스토리지 및 Cosmos DB에 대한 엔드포인트를 지원합니다. 엔드포인트에 사용하는 서비스의 인스턴스는 엔드포인트를 만들기 전에 Azure 구독에 있어야 합니다.

참고 항목

이 문서에서는 Azure CLI용 azure-iot 확장 버전 0.19.0에서 도입된 az iot hub message-endpoint 명령 그룹을 사용합니다. azure-iot 확장의 이전 버전에서는 az iot hub routing-endpoint 명령 그룹을 사용했으며, 이는 유사하고 여전히 지원되지만 Cosmos DB 엔드포인트 만들기를 지원하지 않습니다.

다음 명령을 사용하여 azure-iot 확장의 최신 버전으로 업데이트합니다.

az extension update --name azure-iot

Event Hubs 엔드포인트를 만들려면 필수 구성 요소에서 만든 권한 부여 규칙을 사용합니다.

  1. az eventhubs eventhub authorization-rule keys list 명령을 사용하여 권한 부여 규칙을 나열합니다. 자리 표시자 매개 변수에 대해 다음 값을 제공합니다.

    parameter value
    eventhub_group 이벤트 허브의 리소스 그룹입니다.
    eventhub_namespace Event Hubs 네임스페이스의 이름입니다.
    eventhub_name 이벤트 허브의 이름입니다.
    rule_name 이벤트 허브에 대한 권한 부여 규칙의 이름입니다. 필수 구성 요소에서 예제를 복사한 경우 이 이름은 RootManageSharedAccessKey입니다. 
    az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}

  2. 출력에서 이벤트 허브 연결 문자열을 복사합니다.

  3. az iot hub message-endpoint create eventhub 명령을 사용하여 사용자 지정 엔드포인트를 만듭니다. 자리 표시자 매개 변수에 대해 다음 값을 제공합니다.

    parameter value
    iothub_name 이 엔드포인트를 만드는 IoT 허브의 이름입니다.
    endpoint_name 새 엔드포인트의 고유한 이름입니다.
    eventhub_subscription 이벤트 허브의 구독 ID입니다. 이벤트 허브가 IoT 허브와 동일한 구독에 있는 경우 이 인수를 제외할 수 있습니다.
    eventhub_group 이벤트 허브의 리소스 그룹입니다. 이벤트 허브가 IoT 허브와 동일한 리소스 그룹에 있는 경우 이 인수를 제외할 수 있습니다.
    eventhub_connection_string 이벤트 허브 권한 부여 규칙에서 복사한 연결 문자열입니다. 
    az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}

엔드포인트 삭제

IoT 허브에서 엔드포인트를 삭제하려면 az iot hub message-endpoint delete 명령을 사용합니다. 이 명령을 사용하면 단일 엔드포인트를 삭제하거나, 단일 유형의 모든 엔드포인트를 삭제하거나, 허브에서 모든 엔드포인트를 삭제할 수 있습니다.

예를 들어 다음 명령은 스토리지 리소스를 가리키는 IoT 허브의 모든 엔드포인트를 삭제합니다.

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

IoT Hub 경로 만들기

IoT Hub에서 메시지를 보내거나 이벤트를 캡처하는 경로를 만들 수 있습니다. 각 경로에는 데이터 원본과 엔드포인트가 있습니다. 데이터 원본은 메시지 또는 이벤트 로그가 시작되는 위치입니다. 엔드포인트는 메시지 또는 이벤트 로그가 끝나는 위치입니다. IoT 허브에서 새 경로를 만들 때 데이터 원본 및 엔드포인트의 위치를 선택합니다. 필요에 따라, 메시지 경로에 쿼리를 추가하여 메시지 또는 이벤트를 필터링한 후 엔드포인트로 보낼 수 있습니다.

참고 항목

이 문서에서는 Azure CLI용 azure-iot 확장 버전 0.19.0에서 도입된 az iot hub message-route 명령 그룹을 사용합니다. 이전 버전의 azure-iot 확장에서는 az iot hub route 명령 그룹을 사용했는데, 이는 유사하고 여전히 지원됩니다.

다음 명령을 사용하여 azure-iot 확장의 최신 버전으로 업데이트합니다.

az extension update --name azure-iot

  1. az iot hub message-route create 명령을 사용하여 해당 엔드포인트를 사용해서 새 IoT Hub 경로를 만듭니다. 자리 표시자 매개 변수에 대해 다음 값을 제공합니다.

    parameter value
    iothub_name 이 경로를 만드는 IoT 허브의 이름입니다.
    route_name 새 경로의 고유한 이름입니다.
    endpoint_name 경로에서 데이터를 보낼 엔드포인트의 이름입니다.
    data_source 경로의 원본입니다. 허용되는 값은 deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid 또는 twinchangeevents입니다. 
    az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}

  2. 새 경로가 IoT 허브에 있는지 확인하려면 az iot hub message-route list 명령을 사용하여 IoT 허브의 모든 경로를 확인합니다.

    az iot hub message-route list --hub-name {iothub_name}

    이 예제와 유사한 응답이 Azure CLI에 표시됩니다.

    [
   {
     "condition": "true",
     "endpointNames": [
       "endpoint_name"
     ],
     "isEnabled": true,
     "name": "route_name",
     "source": "DeviceConnectionStateEvents"
   }
]

IoT Hub 경로 업데이트

경로가 만들어진 후 경로의 일부 속성을 업데이트할 수 있습니다. 기존 경로의 원본, 엔드포인트, 조건 또는 사용 상태를 변경할 수 있습니다.

az iot hub message-route show 명령을 사용하여 경로의 세부 정보를 봅니다.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

az iot hub message-route update 명령을 사용하여 경로의 속성을 업데이트합니다. 예를 들어 다음 명령은 경로의 원본을 업데이트합니다.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

IoT Hub 경로 삭제

az iot hub message-route delete 명령을 사용하여 IoT 허브에서 경로를 삭제합니다.

다른 경로가 동일한 엔드포인트를 가리킬 수 있으므로 경로를 삭제해도 해당 엔드포인트는 삭제되지 않습니다. 엔드포인트를 삭제하려는 경우 경로 삭제와 별도로 삭제할 수 있습니다.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

대체 경로 관리

대체 경로는 기존 경로의 쿼리 조건을 충족하지 않는 devicemessages 원본에서 모든 메시지를 기본 제공 엔드포인트로 보냅니다.

az iot hub message-route fallback show 명령을 사용하여 IoT 허브에서 대체 경로의 상태를 확인합니다.

az iot hub message-route fallback show --hub-name {iothub_name}

az iot hub message-route fallback set 명령을 사용하여 IoT 허브에서 대체 경로를 사용하거나 사용하지 않도록 설정합니다.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

다음 단계

이 방법 문서에서는 Event Hubs, Service Bus 큐 및 토픽, Azure Storage에 대한 경로 및 엔드포인트를 만드는 방법을 알아보았습니다.

메시지 라우팅에 대한 자세한 내용은 자습서: IoT 허브 메시지 라우팅을 사용하여 Azure Storage로 디바이스 데이터 보내기를 참조하세요. 이 자습서에서는 스토리지 경로를 만들고 IoT 허브의 디바이스를 사용하여 테스트합니다.