다음을 통해 공유

IoT Hub의 직접 메서드 호출 및 이해

  • 아티클

IoT Hub 직접 메서드를 사용하면 클라우드에서 디바이스에 대한 호출을 원격으로 호출할 수 있습니다. 직접 메서드는 요청-응답 패턴을 따르며, 결과를 즉각적으로 확인해야 하는 통신에 유의미합니다. 팬 켜기 등, 대화형 디바이스 제어를 예로 들 수 있습니다. 이 기능은 즉각적인 조치 과정이 디바이스의 응답 여부에 따라 달라지는 시나리오에서 유용합니다.

참고 항목

이 문서에서 설명하는 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.

각 디바이스 메서드는 단일 디바이스를 대상으로 합니다. 여러 디바이스에서 직접 메서드를 호출하거나, 연결이 끊긴 디바이스에 대한 메서드를 예약하려면 여러 디바이스에서 작업 예약을 참조하세요.

IoT Hub에 서비스 연결 권한만 있다면 누구든 디바이스에서 메서드를 호출할 수 있습니다.

desired 속성, 직접 메서드 또는 클라우드-디바이스 메시지 사용에 대해 궁금한 점이 있으면 클라우드-디바이스 통신 지침을 참조하세요.

메서드 수명 주기

직접 메서드는 디바이스에서 구현되며, 제대로 인스턴스화하기 위해 메서드 페이로드에 0개 이상의 입력이 필요할 수 있습니다. 직접 메서드는 서비스 지향 URI를 통해 호출합니다({iot hub}/twins/{device id}/methods/). 디바이스는 디바이스별 MQTT 항목($iothub/methods/POST/{method name}/) 또는 AMQP 링크(IoThub-methodname 및 IoThub-status 애플리케이션 속성)를 통해 직접 메서드를 수신합니다.

참고 항목

디바이스에서 직접 메서드를 호출할 때 속성 이름과 값은 US-ASCII로 출력 가능한 영숫자만 포함할 수 있으며 다음 집합은 제외됩니다. $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

직접 메서드는 동기식이며 제한 시간(기본값: 30초, 5~300초 설정 가능)이 지나면 성공하거나 실패합니다. 직접 메서드는 디바이스가 온라인 상태에서 명령을 수신하는 경우에만 작동하기를 바라는 대화형 시나리오에서 유용합니다. 예를 들어 휴대폰에서 불을 켭니다. 이러한 시나리오에서는 클라우드 서비스가 결과에 최대한 빨리 대응할 수 있도록 즉각적인 성공이나 실패를 보려고 합니다. 디바이스는 메서드의 결과로 일부 메시지 본문을 반환할 수 있지만 필수는 아닙니다. 메서드 호출의 순서 지정 또는 동시성 의미 체계에 대한 보장은 없습니다.

직접 메서드는 클라우드 쪽에서는 HTTPS 전용, 디바이스 쪽에서는 MQTT, AMQP, WebSocket을 통한 MQTT 또는 WebSocket을 통한 AMQP입니다.

메서드 요청 및 응답에 대한 페이로드는 최대 128KB의 JSON 문서입니다.

백 엔드 앱에서 직접 메서드 호출

백 엔드 앱에서 직접 메서드를 호출하려면 IoT Hub 서비스 SDK 중 하나에서 디바이스 메서드 호출 REST API 또는 이에 상응하는 API를 사용합니다.

메서드 호출

디바이스의 직접 메서드 호출은 다음 항목으로 구성된 HTTPS 호출입니다.

  • 디바이스와 관련된 요청 URI 및 API 버전:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • POST 메서드

  • 권한 부여, 콘텐츠 형식 및 콘텐츠 인코딩이 포함된 헤더.

  • 다음과 같은 형식의 투명한 JSON 본문:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

요청에서 responseTimeoutInSeconds로 제공되는 값은 디바이스에서 직접 메서드 실행이 완료될 때까지 IoT Hub 서비스가 기다려야 하는 시간입니다. 이 제한 시간을 디바이스에서 직접 메서드를 실행하는 데 예상되는 시간 이상으로 설정합니다. timeout 값이 제공되지 않으면 기본값인 30초가 사용됩니다. responseTimeoutInSeconds의 최소값 및 최대값은 각각 5 및 300초입니다.

요청에서 connectTimeoutInSeconds 로 제공되는 값은 직접 메서드를 호출하는 시간으로, 연결이 끊어진 디바이스가 온라인 상태가 될 때까지 IoT Hub 서비스에서 대기해야 하는 시간입니다. 기본값은 0입니다. 즉, 직접 메서드를 호출할 때 디바이스가 이미 온라인 상태여야 합니다. connectTimeoutInSeconds에 대한 최대값은 300초입니다.

예시

이 예제에서는 Azure IoT Hub에 등록된 IoT 디바이스에서 직접 메서드를 호출하는 요청을 시작합니다.

시작하려면 Azure CLI에 대한 Microsoft Azure IoT 확장을 사용하여 SharedAccessSignature를 만듭니다.

az iot hub generate-sas-token -n <iothubName> --du <duration>

그런 다음 인증 헤더를 새로 생성된 SharedAccessSignature로 바꾸고, iothubName, deviceId, methodName 및 payload 매개 변수를 아래 예제 curl 명령의 구현과 일치하도록 수정합니다.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

수정된 명령을 실행하여 지정된 직접 메서드를 호출합니다. 성공적인 요청은 HTTP 200 상태 코드를 반환합니다.

참고 항목

위의 예는 디바이스에서 직접 메서드를 호출하는 방법을 보여 줍니다. IoT Edge 모듈에서 직접 메서드를 호출하려면 아래와 같이 /modules/<moduleName>을(를) 포함하도록 URL 요청을 수정하세요.

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

응답

백 엔드 앱은 다음 항목으로 구성된 응답을 받습니다.

  • HTTP 상태 코드:

    • 200은 직접 메서드를 성공적으로 실행했음을 나타냅니다.
    • 404는 디바이스 ID가 잘못되거나, 직접 메서드를 호출한 후 connectTimeoutInSeconds에 대해 디바이스가 온라인 상태가 아니었음을 나타냅니다(함께 표시되는 오류 메시지를 사용하여 근본 원인 파악)
    • 504는 디바이스가 responseTimeoutInSeconds 내에서 직접 메서드 호출에 응답하지 않아 발생한 게이트웨이 시간 제한 초과를 나타냅니다.

  • 요청 ID, 콘텐츠 형식 및 콘텐츠 인코딩이 포함된 헤더.

  • 다음과 같은 형식의 JSON 본문:

    {
    "status" : 201,
    "payload" : {...}
}

    status 및 payload 모두 디바이스에서 제공되며 디바이스의 자체 상태 코드 및 메서드 응답으로 응답하는 데 사용됩니다.

IoT Edge 모듈에 대한 메서드 호출

모듈에서 직접 메서드 호출은 모듈 메서드 호출 REST API 또는 IoT Hub 서비스 SDK 중 하나에서 이에 상응하는 API에서 지원됩니다.

moduleId는 REST API를 사용할 때 요청 URI의 deviceId와 함께 전달되거나 서비스 SDK를 사용할 때 매개 변수로 전달됩니다. 예: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. 요청 본문 및 응답은 디바이스에서 호출되는 직접 메서드와 유사합니다.

디바이스에서 직접 메서드 처리

IoT 디바이스에서 MQTT, AMQP 또는 WebSocket을 통해 이러한 프로토콜 중 하나를 통해 직접 메서드를 수신할 수 있습니다. IoT Hub 디바이스 SDK를 사용하면 기본 프로토콜 세부 정보에 대해 걱정할 필요 없이 디바이스에서 직접 메서드를 수신하고 이에 응답할 수 있습니다.

MQTT

다음 섹션은 MQTT 프로토콜에 대해 설명합니다. IoT Hub에서 MQTT 프로토콜을 직접 사용하는 방법에 대한 자세한 내용은 MQTT 프로토콜 지원을 참조하세요.

메서드 호출

디바이스는 MQTT 토픽으로 직접 메서드 요청을 수신합니다. $iothub/methods/POST/{method name}/?$rid={request id} 그러나 request id는 IoT Hub에서 생성되며 미리 알 수 없으므로 $iothub/methods/POST/#에 가입한 다음 디바이스에서 지원하는 메서드 이름을 기반으로 전달된 메시지를 필터링합니다. (request id를 사용하여 응답합니다.)

디바이스가 수신하는 본문은 다음과 같은 형식입니다.

{
    "input1": "someInput",
    "input2": "anotherInput"
}

메서드 요청은 QoS 0입니다.

응답

디바이스는 $iothub/methods/res/{status}/?$rid={request id}에 응답을 보내는데 여기서:

  • status 속성은 디바이스가 제공하는 메서드 실행 상태입니다.

  • $rid 속성은 IoT Hub로부터 수신한 메서드 호출의 요청 ID입니다. 요청 ID는 16진수 형식 값입니다.

본문은 디바이스에 의해 설정되며 모든 상태가 될 수 있습니다.

AMQP

다음 섹션은 AMQP 프로토콜에 대해 설명합니다. IoT Hub에서 AMQP 프로토콜을 직접 사용하는 방법에 대한 자세한 내용은 AMQP 프로토콜 지원을 참조하세요.

메서드 호출

디바이스는 amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 주소에서 수신 링크를 만들어 직접 메서드 요청을 수신합니다.

AMQP 메시지는 메서드 요청을 나타내는 수신 링크에 도착하며 여기에는 다음 단원이 포함되어 있습니다.

  • 해당하는 메서드 응답과 함께 다시 전달해야 하는 요청 ID가 포함된 상관 관계 ID 속성

  • 호출 중인 메서드의 이름이 포함된 애플리케이션 속성 IoThub-methodname

  • 메서드 페이로드가 JSON으로 포함된 AMQP 메시지 본문

응답

디바이스는 amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 주소에서 메서드 응답을 반환하기 위한 전송 링크를 만듭니다.

전송 링크에서 반환되는 메서드의 응답은 다음과 같은 항목으로 구성됩니다.

  • 메서드의 요청 메시지에서 전달된 요청 ID를 포함하는 상관 관계 ID 속성

  • 사용자가 제공한 메서드 상태가 포함된 애플리케이션 속성 IoThub-status

  • 메서드 응답이 JSON으로 포함된 AMQP 메시지 본문

다음 단계

직접 메서드를 사용하는 방법에 대해 알아봤으니 다음 IoT Hub 개발자 가이드 문서를 살펴보세요.