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

  • Makale
  • Okumak için 6 dakika

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ını seçme.

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

IoT Hub üzerinde hizmet bağlama izinlerine sahip olan herkes cihazda bir yöntem çağırabilir.

Doğrudan yöntemler bir istek-yanıt desenini izler ve sonuçlarına anında onay verilmesini gerektiren iletişimlere yöneliktir. Örneğin, bir fanı açmak 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 yararlı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 yöntemin bunu yapması 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öntemi Ç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

  • 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ü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, bağlantısı kesilmiş bir cihazın çevrimiçi olması için IoT Hub hizmetin beklemesi gereken doğrudan bir yöntemin çağrılması sırasında gereken süredir. Varsayılan değer 0'dır, yani doğrudan bir yöntem çağrılırsa 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ğırmak için güvenli bir şekilde istek başlatmanıza olanak sağlar.

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 Authorization ü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 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. 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ı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öntemlere benzer.

Bir cihazda doğrudan yöntemi 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, request id IoT 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.

Yanıt

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

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

  • $rid özelliği, IoT Hub 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:

  • karşılık gelen 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.

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: