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

IoT Hub, buluttaki cihazlarda doğrudan yöntemleri çağırma olanağı sunar. Doğrudan yöntemler, (kullanıcı tarafından belirtilen bir zaman aşımından sonra) hemen başarılı veya başarısız olması için HTTP çağrısına benzer bir cihazla istek-yanıt etkileşimini temsil ederler. Bu yaklaşım, cihazın yanıt verip verememesine bağlı olarak farklılık gösteren acil eylem senaryoları için yararlıdır.

Not

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

Her cihaz yöntemi tek bir cihazı hedefler. Birden çok cihaz üzerinde işleri zamanlama, birden çok cihaz üzerinde doğrudan yöntemleri çağırmak için bir yol sağlamayı ve bağlantısı kesilmiş cihazlar için yöntem çağırmayı zamanlamayı gösterir.

Hizmet bağlantısı izinlerine sahip IoT Hub cihazda bir yöntem çağırabilirsiniz.

Doğrudan yöntemler bir istek-yanıt desenini takip eder ve sonuçların hemen onayını gerektiren iletişimlere yöneliktir. Örneğin, cihazın fanı açma gibi etkileşimli denetimi.

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

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

Doğrudan yöntemler cihazda uygulanır ve doğru şekilde örneğinin uygulanması için yöntem yükünde sıfır veya daha fazla giriş gerekli olabilir. Hizmete yönelik URI ( ) aracılığıyla doğrudan yöntem {iot hub}/twins/{device id}/methods/ çağırırsınız. Cihaz, cihaza özgü bir MQTT konusu ( ) veya AMQP bağlantıları (ve uygulama özellikleri) aracılığıyla $iothub/methods/POST/{method name}/ IoThub-methodname doğrudan yöntemler IoThub-status alır.

Not

Bir cihazda doğrudan yöntem çağırsanız, özellik adları ve değerleri aşağıdaki kümede yer alan herhangi biri dışında yalnızca US-ASCII yazdırılabilir alfasayısal içerebilir: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Doğrudan yöntemler zaman uyumludur ve zaman aşımı süresi (varsayılan: 30 saniye, 5 ile 300 saniye arasında ayarlanabiliyor) sonra başarılı veya başarısız olur. Doğrudan yöntemler, yalnızca cihaz çevrimiçi ise ve komut alıyorsa, bir cihazın harekete geçsin istediğiniz etkileşimli senaryolarda yararlıdır. Örneğin, telefondan bir ışığı açma. Bu senaryolarda, bulut hizmetinin sonuç üzerinde mümkün olan en kısa sürede işlem yapmak için hemen bir başarı veya başarısızlık görmek istiyor. Cihaz, yönteminin sonucu olarak bazı ileti gövdelerini geri getirebilirsiniz, ancak yöntemin bunu yapmak için gerekli değildir. Yöntem çağrılarını sıralama veya eşzamanlılık semantiği garantisi yoktur.

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

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

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

Şimdi bir arka uç uygulamasından doğrudan yöntem çağırabilirsiniz.

Yöntem çağırma

Bir cihazdaki doğrudan yöntem çağrıları, aşağıdaki öğelerden yapılmış 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=2018-06-30
    
  • POST yöntemi

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

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

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

İstekte olduğu gibi sağlanan değer, bir IoT Hub doğrudan yöntem yürütmenin tamamlanması için bekleyen responseTimeoutInSeconds süredir. Bu zaman aşımını, bir cihaz tarafından doğrudan yöntemin beklenen yürütme süresi kadar olacak şekilde ayarlayın. Zaman aşımı sağlanmazsa varsayılan 30 saniyelik değer kullanılır. için en düşük ve en yüksek responseTimeoutInSeconds değerler sırasıyla 5 ve 300 saniyedir.

İstekte olduğu gibi sağlanan değer, bağlı olmayan bir cihazın çevrimiçi olması için IoT Hub bir doğrudan yöntemin çağrılma connectTimeoutInSeconds süresidir. Varsayılan değer 0'dır, yani doğrudan yöntem çağrılarak cihazların zaten çevrimiçi olması gerekir. için maksimum değer connectTimeoutInSeconds 300 saniyedir.

Örnek

Bu örnek, bir IoT cihazına kayıtlı bir IoT cihazında Doğrudan Yöntem çağırma isteğini güvenli bir şekilde Azure IoT Hub.

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

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

Ardından Yetkilendirme üst bilgisini yeni oluşturulan SharedAccessSignature ile değiştirin ve ardından aşağıdaki örnek komutta , ve parametrelerini uygulamanıza göre iothubName deviceId methodName payload curl değiştirin.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2018-06-30 \
  -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 Direct Metodu'na çağrı yapmak için değiştirilen komutu yürütün. Başarılı istekler bir HTTP 200 durum kodu geri döner.

Not

Yukarıdaki örnek, bir cihazda Doğrudan Yöntem'in nasıl belirtildiğini gösterir. IoT Edge Modülünde Doğrudan Yöntem çağırmak isterseniz, url isteğini aşağıda gösterildiği gibi değiştirmeniz gerekir:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2018-06-30

Yanıt

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

  • HTTP durum kodu:

    • 200, doğrudan yöntemin başarıyla yürütülmesini gösterir;
    • 404, cihaz kimliğinin geçersiz olduğunu veya doğrudan yöntem çağrılarak cihazın çevrimiçi olmadığını gösterir (kök nedeni anlamak için eşlik eden hata connectTimeoutInSeconds iletisini kullanın);
    • 504, cihazın içinde doğrudan yöntem çağrısına yanıt vermemiş olması nedeniyle ağ geçidi zaman aşımı olduğunu responseTimeoutInSeconds gösterir.
  • ETag, istek kimliği, içerik türü 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 cihaz tarafından sağlanır ve cihazın kendi durum kodu body ve/veya açıklamasıyla yanıt vermek için kullanılır.

Modüller için IoT Edge çağırma

Modül kimliği kullanarak doğrudan yöntemlerin iptali, IoT Hizmeti İstemcisi C# SDK'sı içinde de desteklemektedir.

Bu amaçla yöntemini kullanın ServiceClient.InvokeDeviceMethodAsync() ve ve deviceId moduleId parametresini parametre olarak iletir.

Bir cihazda doğrudan yöntemi işleme

Şimdi bir IoT cihazında doğrudan yöntemin nasıl işlen bir yöntem olduğunu ele atın.

MQTT

Aşağıdaki bölüm MQTT protokolüne göredir.

Yöntem çağırma

Cihazlar MQTT konu başlığında doğrudan yöntem istekleri alır: $iothub/methods/POST/{method name}/?$rid={request id} . Cihaz başına abonelik sayısı 5 ile sınırlıdır. Bu nedenle her doğrudan yönteme ayrı ayrı abone olunmamaları önerilir. Bunun yerine abone olmak ve ardından $iothub/methods/POST/# teslim edilen iletileri istediğiniz yöntem adlarına göre filtrelemeyi göz önünde bulundurabilirsiniz.

Cihazın aldığı gövde aşağıdaki biçimdedir:

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

Yöntem istekleri QoS 0'dır.

Yanıt

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

  • özelliği, status yöntem yürütmenin cihaz tarafından sağlanan durumu olur.

  • özelliği, $rid IoT Hub'dan alınan yöntem çağırmadan gelen istek IoT Hub.

Gövde cihaz tarafından ayarlanır ve herhangi bir durumda olabilir.

AMQP

Aşağıdaki bölüm AMQP protokolüne göredir.

Yöntem çağırma

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

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

  • karşılık gelen yöntem yanıtıyla geri geçirileb bir istek kimliği içeren bağıntı kimliği özelliği.

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

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

Yanıt

Cihaz, adresine yöntem yanıtını göndermek için bir gönderme bağlantısı amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 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ılmıştır:

  • Yöntemin istek iletisine geçirilen istek kimliğini içeren bağıntı kimliği özelliği.

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

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

Ek başvuru malzemeleri

Geliştirici kılavuzunda yer alan IoT Hub konular şunlardır:

  • IoT Hub uç noktaları, her IoT hub'ını çalışma zamanı ve yönetim işlemleri için ortaya çıkaran çeşitli uç noktaları açıklar.

  • Azaltma ve kotalar, geçerli olan kotaları ve bu kotaları kullanırken beklemeniz gereken azaltma davranışını IoT Hub.

  • Azure IoT cihaz ve hizmet SDK'leri, hem cihaz hem de hizmet uygulamaları geliştirirken kullanabileceğiniz ve IoT Hub.

  • IoT Hub ikizler, işler ve ileti yönlendirme için sorgu dili, IoT Hub ikizleri ve işleriniz hakkında daha fazla bilgi almak için kullanabileceğiniz IoT Hub dilini açıklar.

  • IoT Hub MQTT desteği, MQTT protokolü için IoT Hub daha fazla bilgi sağlar.

Sonraki adımlar

Artık doğrudan yöntemleri kullanmayı öğrendiniz. Geliştirici kılavuzu makalesinde IoT Hub ilginizi çekebilirsiniz:

Bu makalede açıklanan kavramların bazılarını denemek istiyorsanız aşağıdaki IoT Hub öğreticisiyle karşılaşabilirsiniz: