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

  • Makale

IoT Hub, buluttaki cihazlarda doğrudan yöntem çağırmanıza olanak tanır. Kullanıcı tarafından belirtilen bir zaman aşımı süresinden sonra anında başarılı veya başarısız olmasıyla bir HTTP çağrısına benzeyen doğrudan yöntemler, bir cihazla yapılan istek-yanıt etkileşimini temsil eder. 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 standart IoT Hub katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. Çözümünüz için doğru IoT Hub katmanı seçme.

Her cihaz yöntemi tek bir cihazı hedefler. Birden çok cihazda işleri zamanlama, birden çok cihazda doğrudan yöntemleri çağırmanın ve bağlantısız cihazlar için yöntem çağırmayı zamanlamanın nasıl sağlandığı gösterilir.

IoT Hub üzerinde hizmet bağlantısı izinleri olan herkes cihazda bir yöntem çağırabilir.

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

İ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ü

Doğrudan yöntemler cihazda uygulanır ve doğru şekilde örneklenmek için yöntem yükünde sıfır veya daha fazla giriş gerektirebilir. 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 () veya AMQP bağlantıları ($iothub/methods/POST/{method name}/IoThub-methodnameve IoThub-status uygulama özellikleri) aracılığıyla doğrudan yöntemler alır.

Not

Bir cihazda doğrudan yöntem çağırdığınızda, özellik adları ve değerleri aşağıdaki kümedekiler 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ü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çi olduğunda ve komut alıyorsa işlem yapmaları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. Cihaz, yöntemin bir sonucu olarak bazı ileti gövdesi döndürebilir, ancak yöntemin bunu yapması için gerekli değildir. 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 MQTT, AMQP, WebSockets üzerinden MQTT veya WebSockets üzerinden AMQP'tir.

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 cihaz yöntemini çağırma REST API'sini veya IoT Hub hizmet SDK'larından birinde eşdeğerini kullanın.

Yöntem çağırma

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

  • Yetkilendirmeyi, içerik türünü 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 olduğu gibi responseTimeoutInSeconds sağlanan değer, IoT Hub hizmetinin bir cihazda doğrudan yöntem yürütmesinin tamamlanması için beklemesi gereken süredir. Bu zaman aşımını en azından bir cihaz tarafından doğrudan bir yöntemin beklenen yürütme süresi kadar olacak şekilde ayarlayın. Zaman aşımı sağlanmazsa, varsayılan değer olan 30 saniye kullanılır. için responseTimeoutInSeconds en düşük ve en yüksek değerler sırasıyla 5 ve 300 saniyedir.

İstekte olduğu gibi connectTimeoutInSeconds sağlanan değer, IoT Hub hizmetinin bağlantısı kesilmiş bir cihazın çevrimiçi olması için beklemesi gereken doğrudan bir yöntemin çağrılması için gereken süredir. Varsayılan değer 0'dır, yani doğrudan bir yöntem çağrıldıysa cihazların zaten çevrimiçi olması gerekir. için connectTimeoutInSeconds en büyük değer 300 saniyedir.

Örnek

Bu örnek, Azure IoT hub'ına kayıtlı bir IoT cihazında doğrudan yöntemi çağırmak için güvenli bir şekilde istek başlatmanıza olanak sağlar.

Başlamak için, SharedAccessSignature oluşturmak üzere Azure CLI için Microsoft Azure IoT uzantısını kullanın.

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

Ardından Authorization üst bilgisini yeni oluşturulan SharedAccessSignature ile değiştirin, ardından , ve parametrelerini aşağıdaki örnek curl komutta uygulamanızla eşleşecek şekilde değiştirin iothubNamemethodNamedeviceId.payload

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.

Not

Yukarıdaki örnekte, bir cihazda doğrudan yöntem çağırma gösterilmektedir. bir IoT Edge Modülünde doğrudan yöntem çağırmak istiyorsanız, 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=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, cihaz kimliğinin geçersiz olduğunu veya doğrudan bir yöntemin çağrılmasından sonra cihazın çevrimiçi olmadığını gösterir (kök nedeni anlamak için connectTimeoutInSeconds eşlik eden hata iletisini kullanın);
    • 504, cihazın içinde responseTimeoutInSecondsdoğrudan yöntem çağrısına yanıt vermemesi nedeniyle oluşan ağ geçidi zaman aşımını gösterir.

  • İ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 hem payload de status cihaz tarafından sağlanır ve cihazın kendi durum kodu ve yöntem yanıtıyla yanıt vermek için kullanılır.

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

Bir modülde doğrudan yöntemleri çağırmak, Invoke modül yöntemi REST API'si veya IoT Hub hizmet SDK'larından birinde eşdeğeri tarafından desteklenir.

moduleId REST API kullanılırken istek URI'sinde ile deviceId 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öntemlere benzer.

Bir cihazda doğrudan yöntem işleme

IoT cihazında MQTT, AMQP veya WebSockets üzerinden bu protokollerden herhangi 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 protokollerini doğrudan IoT Hub ile kullanma hakkında daha fazla bilgi edinmek için bkz. MQTT protokolü desteği.

Yöntem çağırma

Cihazlar MQTT konusunda doğrudan yöntem istekleri alır: $iothub/methods/POST/{method name}/?$rid={request id}. Ancak, IoT Hub request id tarafından oluşturulur ve önceden bilinmez, bu nedenle cihazınız tarafından desteklenen yöntem adlarına göre teslim edilen iletilere $iothub/methods/POST/# abone olun ve ardından bunları filtreleyin. (Yanıt vermek için öğesini request id kullanacaksınız.)

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

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

Yöntem istekleri QoS 0'dır.

Yanıt

Cihaz, aşağıdaki durumlarda öğesine $iothub/methods/res/{status}/?$rid={request id}yanıtlar gönderir:

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

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

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

AMQP

Aşağıdaki bölüm AMQP protokolü içindir. AMQP protokollerini doğrudan IoT Hub ile kullanma hakkında daha fazla bilgi edinmek için bkz. AMQP protokolü desteği.

Yöntem çağırma

Cihaz, adresinde amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundbir 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:

  • İlgili yöntem yanıtıyla geri geçirilmesi gereken bir istek kimliği içeren bağıntı kimliği özelliği.

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

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

Yanıt

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

Yöntemin yanıtı, gönderen bağlantıda döndürülür ve aşağıdaki gibi yapılandırılır:

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

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

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

Ek başvuru malzemesi

IoT Hub geliştirici kılavuzundaki diğer başvuru konuları şunlardır:

Sonraki adımlar

Artık doğrudan yöntemleri kullanmayı öğrendinsiniz, aşağıdaki geliştirici kılavuzu makalesini IoT Hub ilginizi çekebilir:

Bu makalede açıklanan kavramlardan bazılarını denemek isterseniz, aşağıdaki IoT Hub öğreticisi ilginizi çekebilir: