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

  • Makale

IoT Hub doğrudan yöntemleri , buluttan cihazlarda çağrıları uzaktan çağırmanı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.

Not

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ünüz için doğru IoT Hub katmanını 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ü

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ç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. Cihaz, yöntemin bir sonucu olarak ileti gövdesi döndürebilir, ancak 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ından 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 hizmeti 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

  • 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 olduğu gibi responseTimeoutInSeconds 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. Bu zaman aşımını, 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, bağlantısı kesilmiş bir cihazın çevrimiçi olması için IoT Hub hizmetinin 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 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, Bir 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 Yetkilendirme üst bilgisini yeni oluşturduğunuz SharedAccessSignature ile değiştirin, ardından , ve parametrelerini aşağıdaki örnek curl komutta uygulamanızla eşleşecek şekilde değiştirin iothubNamemethodName deviceId.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. IoT Edge Modülünde doğrudan yöntem çağırmak istiyorsanız, url isteğini aşağıda 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

Response

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ının ardından 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'siyle birlikte deviceId 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.

Bir cihazda doğrudan yöntem işleme

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 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 request id Hub 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 bunları filtreleyin. (Yanıtlamak 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.

Response

Cihaz, yanıtlarını $iothub/methods/res/{status}/?$rid={request id}öğesine gönderir. Burada:

  • status özelliği, yöntem yürütmenin cihaz tarafından sağlanan 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.

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.

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

Response

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önderme bağlantısında 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.

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

Sonraki adımlar

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