Aracılığıyla paylaş

IoT Hub'dan doğrudan yöntemleri anlama ve çağırma

IoT Hub doğrudan yöntemleri, buluttan uzaktan cihazlarda çağrı yapmanızı sağlar. Doğrudan yöntemler istek-yanıt desenini izler ve sonuçların hemen onaylanmasını gerektiren iletişimlere yöneliktir. Örneğin, bir cihazın fanını açma gibi etkileşimli denetimi. Bu işlev, cihazın yanıt verip veremediğine bağlı olarak anında eylem seyrinin farklı olduğu senaryolar için kullanışlıdır.

Uyarı

Bu makalede açıklanan özellikler yalnızca IoT Hub'ın standart katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. çözüm için doğru IoT Hub katmanını ve boyutunu seçme.

Her cihaz yöntemi tek bir cihazı hedefler. Birden çok cihazda doğrudan yöntemleri çağırmak veya bağlantısı kesilmiş cihazlar için yöntemleri zamanlamak istiyorsanız bkz. Birden çok cihazda iş zamanlama.

IoT Hub'da hizmet bağlama izinleri olan herkes cihazda bir yöntem çağırabilir.

İstenen özellikleri, doğrudan yöntemleri veya buluttan cihaza iletileri kullanma arasında şüphe varsa Buluttan cihaza iletişim kılavuzuna bakın.

Yöntem yaşam döngüsü

Direct methods are implemented on the device and might require zero or more inputs in the method payload to correctly instantiate. Hizmete yönelik bir URI ({iot hub}/twins/{device id}/methods/) aracılığıyla doğrudan bir yöntem çağırırsınız. Cihaz, cihaza özgü bir MQTT konusu ($iothub/methods/POST/{method name}/) veya AMQP bağlantıları (IoThub-methodname ve IoThub-status uygulama özellikleri) aracılığıyla doğrudan yöntemler alır.

Uyarı

Bir cihazda doğrudan bir yöntem çağırdığınızda, özellik adları ve değerleri, aşağıdaki kümedekiler dışında yalnızca yazdırılabilir US-ASCII alfasayısal karakterler içerebilir: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Doğrudan yöntemler zaman uyumludur ve zaman aşımı süresinden sonra başarılı veya başarısız olur (varsayılan 30 saniye; 5 ile 300 saniye arasında ayarlanabilir). Doğrudan yöntemler, bir cihazın yalnızca çevrimiçiyse ve komut alıyorsa davranmasını istediğiniz etkileşimli senaryolarda kullanışlıdır. Örneğin, telefondan bir ışığı açma. Bu senaryolarda, bulut hizmetinin en kısa sürede sonuç üzerinde işlem gerçekleştirebilmesi için anında bir başarı veya başarısızlık görmek istiyorsunuz. The device might return some message body as a result of the method, but it isn't required. Yöntem çağrılarında sıralama veya eşzamanlılık semantiği garantisi yoktur.

Doğrudan yöntemler, bulut tarafında yalnızca HTTPS ve cihaz tarafında ise MQTT, AMQP, WebSockets üzerinden MQTT veya WebSockets üzerinden AMQP'dir.

Yöntem istekleri ve yanıtları için yük, 128 KB'a kadar olan bir JSON belgesidir.

Arka uç uygulamasından doğrudan yöntem çağırma

Bir arka uç uygulamasından doğrudan yöntem çağırmak için Cihazlar - Çağırma Yöntemi REST API'sini veya IoT Hub hizmeti SDK'larından birinde eşdeğerini kullanın.

Method invocation

Bir cihazdaki doğrudan yöntem çağrıları, aşağıdaki öğelerden oluşan HTTPS çağrılarıdır:

  • API sürümüyle birlikte cihaza özgü istek URI'si :

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

  • POST yöntemi

  • Yetkilendirme, içerik türü ve içerik kodlamasını içeren üst bilgiler.

  • Aşağıdaki biçimde saydam bir JSON gövdesi :

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

İstekte responseTimeoutInSeconds olarak sağlanan değer, IoT Hub hizmetinin bir cihazda doğrudan yöntem yürütme işleminin tamamlanması için beklemesi gereken süredir. Set this time-out to be at least as long as the expected execution time of a direct method by a device. Zaman aşımı değeri sağlanmazsa varsayılan değer olan 30 saniye kullanılır. responseTimeoutInSeconds için en düşük ve en yüksek değerler sırasıyla 5 ve 300 saniyedir.

İstekte connectTimeoutInSeconds olarak sağlanan değer, bağlantısı kesilmiş bir cihazın çevrimiçi olmasını beklerken IoT Hub hizmetinin, doğrudan bir yöntem çağrısı yaptığında beklemesi gereken süredir. Varsayılan değer 0'dır, yani bir doğrudan yöntem çağrıldığında cihazların zaten çevrimiçi olması gerekir. için connectTimeoutInSeconds en yüksek değer 300 saniyedir.

Örnek

Bu örnek, Azure IoT hub'ına kayıtlı bir IoT cihazında doğrudan yöntem çağırma isteği başlatır.

Başlamak için, Azure CLI için Microsoft Azure IoT uzantısını kullanarak bir SharedAccessSignature oluşturun.

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

Ardından, Yetkilendirme üst bilgisini yeni oluşturduğunuz SharedAccessSignature ile değiştirin ve aşağıdaki örnek iothubName komuttaki uygulamanıza uygun olacak şekilde deviceId, methodName, payload ve curl parametrelerini değiştirin.

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"
    }
}'

Belirtilen doğrudan yöntemi çağırmak için değiştirilen komutu yürütür. Başarılı istekler bir HTTP 200 durum kodu döndürür.

Uyarı

Önceki örnekte, bir cihazda doğrudan yöntem çağırma gösterilmektedir. IoT Edge modülünde doğrudan bir yöntem çağırmak istiyorsanız, URL isteğini aşağıdaki örnekte gösterildiği gibi içerecek /modules/<moduleName> şekilde değiştirin:

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

Yanıt

Arka uç uygulaması aşağıdaki öğelerden oluşan bir yanıt alır:

  • HTTP durum kodu:

    • 200, doğrudan yöntemin başarıyla yürütüldiğini gösterir;
    • 404, ya cihaz kimliğinin geçersiz olduğunu ya da cihazın doğrudan bir yöntem çağrıldığında ve sonrasında çevrimiçi olmadığını gösterir (temel nedeni anlamak için connectTimeoutInSeconds eşlik eden hata iletisini kullanın);
    • 504, cihazın responseTimeoutInSeconds içinde doğrudan yöntem çağrısına yanıt vermemesi nedeniyle ağ geçidi zaman aşımını belirtir.

  • İstek kimliğini, içerik türünü ve içerik kodlamasını içeren üst bilgiler.

  • Aşağıdaki biçimde bir JSON gövdesi :

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

    Hem status hem de payload cihaz tarafından sağlanır ve cihazın kendi durum kodu ve yöntem yanıtı ile yanıt vermek için kullanılır.

IoT Edge modülleri için yöntem çağırma

Bir modülde doğrudan yöntem çağırmak için Modüller - Çağırma Yöntemi REST API'sini veya IoT Hub hizmet SDK'larından birinde eşdeğerini kullanın.

moduleId, REST API kullanılırken istek URI'sindeki deviceId ile birlikte veya hizmet SDK'sı kullanılırken parametre olarak geçirilir. Örneğin, https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. İstek gövdesi ve yanıtı, cihazda çağrılan doğrudan yöntemlerinkine benzer.

Handle a direct method on a device

IoT cihazında MQTT, AMQP veya WebSockets üzerinden bu protokollerden biri üzerinden doğrudan yöntemler alınabilir. IoT Hub cihaz SDK'ları, temel alınan protokol ayrıntıları konusunda endişelenmenize gerek kalmadan cihazlarda doğrudan yöntemleri almanıza ve yanıtlamanıza yardımcı olur.

MQTT

Aşağıdaki bölüm MQTT protokolü içindir. MQTT protokolunu doğrudan IoT Hub ile kullanma hakkında daha fazla bilgi edinmek için bkz. MQTT protokolunu kullanarak IoT hub'ı ile iletişim kurma.

Method invocation

Cihazlar MQTT konusunda doğrudan yöntem istekleri alır: $iothub/methods/POST/{method name}/?$rid={request id}. Ancak, IoT Hub tarafından üretildiği için request id önceden bilinemiyor, bu yüzden $iothub/methods/POST/# abone olun ve ardından cihazınızın desteklediği yöntem adlarına göre teslim edilen iletileri filtreleyin. (Yanıt vermek için oluşturulan request id öğesini kullanırsınız.)

The body that the device receives is in the following format:

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

Yöntem istekleri QoS 0'dır.

Yanıt

Cihaz yanıtlarını $iothub/methods/res/{status}/?$rid={request id}'a gönderir; burada:

  • status özelliği, cihaz tarafından sağlanan yöntem yürütme durumudur.

  • $rid özelliği, IoT Hub'dan alınan yöntem çağrısından gelen istek kimliğidir. İstek kimliği onaltılık biçimlendirilmiş bir değerdir.

The device sets the body and can be any status.

AMQP

Aşağıdaki bölüm AMQP protokolü içindir. AMQP protokolunu doğrudan IoT Hub ile kullanma hakkında daha fazla bilgi edinmek için bkz. AMQP Protokolunu kullanarak IoT hub'ınız ile iletişim kurma.

Method invocation

Cihaz, amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundadresinde bir alma bağlantısı oluşturarak doğrudan yöntem istekleri alır.

AMQP iletisi, yöntem isteğini temsil eden alma bağlantısına ulaşır. Aşağıdaki bölümleri içerir:

  • Bağıntı kimliği özelliği, ilgili yöntem yanıtıyla geri iletilmesi gereken bir istek kimliği içerir.

  • Çağrılan yöntemin adını içeren IoThub-methodnameadlı bir uygulama özelliği.

  • JSON olarak yöntem yükünü içeren AMQP ileti gövdesi.

Yanıt

Cihaz, amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundadresinde yöntem yanıtını döndürmek için bir gönderme bağlantısı oluşturur.

Yöntemin yanıtı gönderme bağlantısında döndürülür ve aşağıdaki gibi yapılandırılır:

  • The correlation ID property, which contains the request ID passed in the method's request message.

  • Kullanıcı tarafından sağlanan yöntem durumunu içeren IoThub-statusadlı bir uygulama özelliği.

  • JSON olarak yöntem yanıtını içeren AMQP ileti gövdesi.

Sonraki adımlar

Doğrudan yöntemleri kullanmayı öğrendiğinize göre, aşağıdaki IoT Hub geliştirici kılavuzu makaleleriyle ilgilenebilirsiniz: