IoT Hub 엔드포인트
Azure IoT Hub는 상호 작용하는 디바이스 및 서비스를 지원하기 위해 다양한 엔드포인트를 노출합니다.
참고 항목
클라우드-디바이스 메시지, 디바이스 트윈스, 디바이스 관리 등 이 문서에 언급된 일부 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.
IoT Hub 이름
Azure Portal의 IoT 허브 개요 작업 창에서 IoT 허브의 호스트 이름을 찾을 수 있습니다. 기본적으로 IoT Hub의 DNS 이름은 다음 예제와 유사합니다.
{your iot hub name}.azure-devices.net
개발 및 관리를 위한 IoT Hub 엔드포인트
Azure IoT Hub는 다중 테넌트 서비스이며 다양한 행위자에게 기능을 노출합니다. 아래 다이어그램에서는 IoT Hub가 노출하는 다양한 엔드포인트를 보여줍니다.
다음 목록에서는 엔드포인트를 설명합니다.
리소스 공급자: Azure Resource Manager 인터페이스입니다. 이 인터페이스를 통해 Azure 구독 소유자는 IoT Hub를 생성 및 삭제하고 IoT Hub 속성을 업데이트할 수 있습니다. IoT Hub 속성은 디바이스 수준 액세스 제어와 달리 허브 수준 공유 액세스 정책 및 클라우드-디바이스/디바이스-클라우드 메시징을 위한 기능 옵션을 제어합니다. 또한 IoT Hub 리소스 공급자는 사용자가 디바이스 ID를 내보낼 수 있도록 합니다.
디바이스 ID 관리: 디바이스 ID를 관리(만들기, 검색, 업데이트 및 삭제)하기 위한 HTTPS REST 엔드포인트 집합입니다. 디바이스 ID는 디바이스 인증 및 액세스 제어에 사용됩니다.
디바이스 쌍 관리: 디바이스 쌍(태그 및 속성 업데이트)을 쿼리하고 업데이트하기 위한 서비스 지향 HTTPS REST 엔드포인트 집합입니다.
작업 관리: 작업을 쿼리하고 관리하기 위한 서비스 지향 HTTPS REST 엔드포인트 집합입니다.
디바이스 엔드포인트: ID 레지스트리에 있는 각 디바이스에 대한 엔드포인트 집합입니다. 달리 명시된 경우를 제외하고, 엔드포인트는 MQTT v3.1.1, HTTPS 1.1, AMQP 1.0 프로토콜을 사용하여 노출됩니다. AMQP 및 MQTT는 포트 443에서 WebSockets을 통해 사용할 수도 있습니다. 이러한 디바이스 엔드포인트에는 다음이 포함됩니다.
디바이스-클라우드 메시지 보내기
클라우드-디바이스 메시지 받기
파일 업로드 시작
디바이스 쌍 속성 검색 및 업데이트(HTTPS는 지원되지 않음)
직접 메서드 요청 수신(HTTPS는 지원되지 않음)
서비스 엔드포인트: 솔루션 백 엔드가 디바이스와 통신하기 위한 엔드포인트 집합입니다. 한 가지 예외를 제외하고 엔드포인트는 AMQP 및 WebSocket을 통한 AMQP 프로토콜을 사용하여 노출됩니다. 직접 메서드 호출 엔드포인트는 HTTPS 프로토콜을 통해 노출됩니다.
디바이스-클라우드 메시지 수신: 이 엔드포인트는 메시지 라우팅 개념에서 설명한 기본 제공 엔드포인트입니다. 백 엔드 서비스는 이 엔드포인트를 사용하여 디바이스에서 보낸 모든 디바이스-클라우드 메시지를 읽을 수 있습니다. 이 기본 제공 엔드포인트 외에도 IoT Hub에 사용자 지정 엔드포인트를 만들 수 있습니다.
클라우드-디바이스 메시지를 보내고 배달 승인 받기
파일 업로드 알림 받기
직접 메서드 호출
Azure IoT Hub SDK 문서에서는 이러한 엔드포인트에 액세스할 수 있는 다양한 방법을 설명합니다.
모든 IoT Hub 엔드포인트는 TLS 프로토콜을 사용하고 어떤 엔드포인트도 암호화되지/보안되지 않은 채널에 공개되지 않습니다.
Important
X.509 CA(인증 기관) 인증을 사용하는 디바이스에 대한 다음 기능은 아직 일반 공급되지 않으며 미리 보기 모드를 사용하도록 설정해야 합니다.
- HTTPS, Websocket을 통한 MQTT 및 Websocket 프로토콜을 통한 AMQP
- 파일 업로드(모든 프로토콜)
이러한 기능은 일반적으로 X.509 지문 인증을 사용하는 디바이스에서 사용할 수 있습니다. IoT Hub를 사용하는 X.509 인증에 대해 자세히 알아보려면 지원되는 X.509 인증서를 참조하세요.
메시지 라우팅을 위한 사용자 지정 엔드포인트
Azure 구독의 기존 Azure 서비스를 IoT 허브에 연결하여 메시지 라우팅을 위한 엔드포인트 역할을 할 수 있습니다. 이러한 엔드포인트는 서비스 엔드포인트 역할을 하며 메시지 경로에 대한 싱크로 사용됩니다. 디바이스는 이러한 엔드포인트에 직접 쓸 수 없습니다. 메시지 라우팅에 대한 자세한 내용은 IoT Hub 메시지 라우팅을 사용하여 디바이스-클라우드 메시지를 다른 엔드포인트로 보내기를 참조하세요.
IoT Hub는 다음 Azure 서비스를 사용자 지정 엔드포인트로 지원합니다.
- 스토리지 컨테이너
- Event Hubs
- Service Bus 큐
- Service Bus 토픽
- Cosmos DB
허브당 엔드포인트 제한은 할당량 및 제한을 참조하세요.
기본 제공 엔드포인트
표준 Event Hubs 통합 및 SDK를 사용하여 기본 제공 엔드포인트(메시지/이벤트)에서 디바이스-클라우드 메시지를 수신할 수 있습니다. 경로가 만들어지면 기본 제공 엔드포인트에 대한 경로가 만들어지지 않는 한 데이터가 기본 제공 엔드포인트로 흐르는 것을 중지합니다. 경로가 만들어지지 않더라도 기본 제공 엔드포인트로 메시지를 라우팅하려면 대체 경로를 활성화해야 합니다. 포털 또는 CLI를 사용하여 허브를 만드는 경우 대체는 기본적으로 활성화됩니다.
라우팅 엔드포인트로 Azure Storage
IoT Hub에서 메시지를 Azure Blob Storage 및 ADLS Gen2(Azure Data Lake Storage Gen2) 계정으로 라우팅할 수 두 개의 스토리지 서비스가 있습니다. 두 가지 모두 해당 스토리지에 대해 Blob을 사용합니다. Azure Data Lake Gen2를 사용하려면 스토리지 계정에 계층 구조 네임스페이스를 사용하도록 설정해야 합니다. 자세한 내용은 Azure Data Lake Storage와 함께 사용할 스토리지 계정 만들기를 참조하세요.
IoT Hub는 Apache Avro 형식 및 JSON 형식으로 Azure Storage에 데이터를 쓰도록 지원합니다. 기본값은 AVRO입니다. JSON 인코딩을 사용하려면 contentType 속성을 application/json으로 설정하고 메시지 시스템 속성에서 contentEncoding 속성을 UTF-8로 설정합니다. 이러한 두 값은 대/소문자를 구분하지 않습니다. 콘텐츠 인코딩이 설정되지 않은 경우 IoT Hub는 base 64 인코딩 형식으로 메시지를 작성합니다.
인코딩 형식은 Blob Storage 엔드포인트가 구성된 경우에만 설정할 수 있습니다. 기존 엔드포인트에 대해서는 편집할 수 없습니다.
IoT Hub는 일괄 처리가 특정 크기 또는 특정 시간이 경과할 때마다 메시지를 일괄 처리하고 스토리지에 데이터를 씁니다. IoT Hub는 기본적으로 다음 파일 명명 규칙을 따릅니다. {iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm} 파일 명명 규칙을 사용할 수 있지만 나열된 모든 토큰을 사용해야 합니다. 쓸 데이터가 없는 경우 IoT Hub는 빈 Blob에 씁니다.
Blob 또는 파일을 나열한 다음, 이를 반복하여 파티션을 가정하지 않고 모든 Blob 또는 파일을 읽을 수 있도록 하는 것이 좋습니다. 파티션 범위는 Microsoft 시작 장애 조치(failover) 또는 IoT Hub 수동 장애 조치(failover) 중에 변경할 수 있습니다. Blob 목록을 열거하기 위해 Blob API 나열을 사용하거나 파일 목록에 대해 ADLS Gen2 API 나열을 사용할 수 있습니다. 예시:
public void ListBlobsInContainer(string containerName, string iothub)
{
var storageAccount = CloudStorageAccount(Microsoft.Azure.Storage.Auth.StorageCredentials storageCredentials, bool useHttps);
var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
if (cloudBlobContainer.Exists())
{
var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
foreach (IListBlobItem item in results)
{
Console.WriteLine(item.Uri);
}
}
}
라우팅 엔드포인트로 Service Bus 큐 및 Service Bus 토픽
IoT Hub으로 사용되는 Service Bus 큐 및 토픽에는 세션 또는 중복 검색이 사용하도록 설정되어 있어서는 안 됩니다. 두 옵션 중 하나가 사용하도록 설정되어 있으면 Azure Portal에서 엔드포인트가 연결할 수 없음으로 표시됩니다.
라우팅 엔드포인트로 Event Hubs
기본 제공 Event Hubs 호환 엔드포인트 외에, Event Hubs 유형의 사용자 지정 엔드포인트로 데이터를 라우팅할 수도 있습니다.
라우팅 엔드포인트로서의 Azure Cosmos DB
IoT Hub에서 Azure Cosmos DB로 직접 데이터를 보낼 수 있습니다. IoT Hub는 JSON(메시지 콘텐츠 형식에 지정된 경우) 또는 Base 64로 인코딩된 이진 파일로 Cosmos DB에 쓰기를 지원합니다.
대규모 시나리오를 지원하려면 Cosmos DB 엔드포인트에 대해 가상 파티션 키를 사용하도록 설정할 수 있습니다. Cosmos DB는 하이퍼스케일 데이터 저장소이므로 여기에 기록된 모든 데이터/문서에는 논리 파티션을 나타내는 필드가 포함되어야 합니다. 각 논리 파티션의 최대 크기는 20GB입니다. 파티션 키 이름에서 파티션 키 속성 이름을 지정할 수 있습니다. 파티션 키 속성 이름은 컨테이너 수준에서 정의되며 업데이트할 수 없습니다.
예상 데이터 볼륨을 기반으로 파티션 키 템플릿에서 템플릿을 지정하여 가상 파티션 키 값을 구성할 수 있습니다. 예를 들어, 제조 시나리오에서는 논리 파티션이 한 달 안에 최대 20GB 한도에 도달할 수 있습니다. 이 경우 디바이스 ID와 월의 조합으로 가상 파티션 키를 정의할 수 있습니다. 만들어진 파티션 키 값은 각각의 새 Cosmos DB 레코드에 대한 파티션 키 속성에 자동으로 추가되어 각 디바이스에 대해 논리적 파티션이 매월 만들어지도록 합니다.
주의
Cosmos DB에 인증하기 위해 시스템이 할당한 관리 ID를 사용하는 경우 Azure CLI 또는 Azure PowerShell을 사용하여 Cosmos DB 기본 제공 데이터 기여자 기본 제공 역할 정의를 ID에 할당해야 합니다. Cosmos DB에 대한 역할 할당은 현재 Azure Portal에서 지원되지 않습니다. 다양한 역할에 대한 자세한 내용은 Azure Cosmos DB에 대한 역할 기반 액세스 구성을 참조하세요. CLI를 통한 역할 할당 방법은 Azure Cosmos DB SQL 역할 리소스 관리를 참조하세요.
엔드포인트 상태
REST API Endpoint Health 가져오기를 사용 하 여 Endpoint의 Health 상태 를 가져올 수 있습니다. 엔드포인트가 이러한 상태 중 하나에 있을 때 대기 시간이 더 길어질 것으로 예상되므로, 라우팅 메시지 대기 시간과 관련된 IoT Hub 라우팅 메트릭을 사용하여 오류를 식별하고 디버깅하는 것이 좋습니다. IoT Hub 사용에 대한 자세한 내용은 IoT Hub 모니터링을 참조하세요.
| 상태 | 설명 |
|---|---|
| healthy | 엔드포인트가 예상대로 메시지를 수락하고 있습니다. |
| 비정상 | 엔드포인트가 메시지를 수락하지 않고 있으며 IoT Hub가 이 엔드포인트에 메시지를 보내려고 재시도하고 있습니다. |
| 알 수 없음 | IoT Hub가 이 엔드포인트에 메시지를 전달하려고 시도하지 않았습니다. |
| 성능 저하됨 | 엔드포인트가 예상보다 느리게 메시지를 수락하거나 비정상 상태에서 복구되고 있습니다. |
| 데드 | IoT Hub는 이 엔드포인트에 메시지를 더 이상 전달하지 않습니다. 이 엔드포인트로 메시지를 보내려는 재시도가 실패했습니다. |
다음 단계
다음 항목에 대해 자세히 알아봅니다.