了解 IoT 中樞的直接方法並從中樞叫用直接方法。

  • 發行項

IoT 中樞 直接方法可讓您從雲端遠端叫用裝置上的呼叫。 直接方法會遵循要求-回應模式，且適用於需要立即確認其結果的通訊。 例如，裝置的互動式控制，例如開啟風扇。 這項功能適用於視裝置是否能夠回應而不同之立即動作的案例。

注意

本文所述的功能僅適用於標準層 IoT 中樞。 如需基本和標準/免費 IoT 中樞 層的詳細資訊，請參閱為您的解決方案選擇正確的 IoT 中樞 層。

每個裝置方法都會以單一裝置為目標。 如果您想要在多個裝置上叫用直接方法，或排程已中斷連線裝置的方法，請參閱 在多個裝置上排程作業。

具有 IoT 中樞 服務連線許可權的任何人都可以在裝置上叫用方法。

如果不確定使用所需的屬性、直接方法或雲端到裝置訊息，請參閱雲端到裝置的通訊指引。

方法生命週期

直接方法會在裝置上實作，且可能需要方法承載中的零或多個輸入才能正確具現化。 您可以透過服務面向 URI ({iot hub}/twins/{device id}/methods/) 叫用直接方法。 裝置會透過裝置特定的 MQTT 主題 ($iothub/methods/POST/{method name}/) 或透過 AMQP 連結 (IoThub-methodname 和 IoThub-status 應用程式屬性) 來接收直接方法。

注意

當您在裝置上叫用直接方法時，屬性名稱和值只能包含 US-ASCII 可列印英數字元，但下列集合中的任何字元除外：$ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

直接方法是同步的，在逾時期間後成功或失敗（預設為30秒;可設定介於5到300秒之間）。 直接方法適用於您希望裝置在裝置上線並接收命令時，才能採取行動的互動式案例。 例如，從手機開燈。 在這些案例中，您想要立即看到成功或失敗，讓雲端服務可以儘快處理結果。 裝置可能會因為方法而傳回一些訊息本文，但並非必要。 在方法呼叫上，無法保證排序或任何並行語意。

直接方法從雲端這邊只能使用 HTTPS，而從裝置這邊則可以使用 MQTT、AMQP、MQTT over WebSockets 或 AMQP over WebSockets。

方法要求和回應的承載是最多 128 KB 的 JSON 文件。

從後端應用程式叫用直接方法

若要從後端應用程式叫用直接方法，請使用叫用裝置方法 REST API 或其在其中一個 IoT 中樞 服務 SDK 中的對等專案。

方法引動過程

裝置上的直接方法叫用是由下列項目所組成的 HTTPS 呼叫：

  • 裝置特有的要求 URI 以及 API 版本：

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

  • POST 方法

  • 包含授權、內容類型和內容編碼的標頭。

  • 透明 JSON 主體 ，格式如下：

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

要求中作為 responseTimeoutInSeconds 所提供的值是 IoT 中樞服務必須等待裝置上的直接方法執行完成的時間量。 請將此逾時設定為至少和裝置所預期的直接方法執行時間一樣久。 如果未提供逾時，則會使用預設值 30 秒。 responseTimeoutInSeconds 的最小值和最大值分別為 5 和 300 秒。

如要求中提供connectTimeoutInSeconds的值是叫用直接方法的時間量，IoT 中樞 服務必須等候中斷連線的裝置上線。 默認值為 0，表示裝置必須在直接方法叫用時已上線。 的最大值 connectTimeoutInSeconds 為300秒。

範例

此範例會起始在註冊至 Azure IoT 中樞的 IoT 裝置上叫用直接方法的要求。

若要開始，請使用適用於 Azure CLI 的 Microsoft Azure IoT 擴充功能來建立 SharedAccessSignature。

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

接下來，將 Authorization 標頭取代為您新產生的 SharedAccessSignature，然後修改 iothubName、 methodNamedeviceId和 payload 參數，以符合下列範例curl命令中的實作。

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

執行修改的命令以叫用指定的直接方法。 成功的要求會傳回 HTTP 200 狀態代碼。

注意

上述範例示範在裝置上叫用直接方法。 如果您想要在IoT Edge模組中叫用直接方法，請修改URL要求以包含 /modules/<moduleName> ，如下所示：

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

回應

後端應用程式會收到由下列項目所組成的回應：

  • HTTP 狀態代碼：

    • 200 表示直接方法的執行成功;
    • 404 表示裝置標識碼無效，或裝置在叫用直接方法時未上線，並之後使用 connectTimeoutInSeconds 隨附的錯誤訊息來瞭解根本原因：
    • 504 表示裝置未回應 內 responseTimeoutInSeconds直接方法呼叫所造成的網關逾時。

  • 包含要求標識碼、內容類型和內容編碼的標頭。

  • 下列格式的 JSON 主體 ：

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

    status和 payload 都是由裝置提供，並用來回應裝置本身的狀態代碼和方法回應。

IoT Edge 模組的方法叫用

叫用模組方法 REST API 或其對等的其中一個 IoT 中樞 服務 SDK 支援在模組上叫用直接方法。

使用 REST API 時，moduleId 會連同要求 URI 中的 deviceId 一起傳遞，或在使用服務 SDK 時作為參數傳遞。 例如： https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12 。 要求本文和回應類似於裝置上叫用的直接方法。

在裝置上處理直接方法

在 IoT 裝置上，您可以透過 MQTT、AMQP 或透過 WebSocket 接收這些通訊協定的直接方法。 IoT 中樞 裝置 SDK 可協助您接收和回應裝置上的直接方法，而不必擔心基礎通訊協定詳細數據。

MQTT

下一節是針對 MQTT 通訊協定。 若要深入瞭解如何直接搭配 IoT 中樞 使用 MQTT 通訊協定，請參閱 MQTT 通訊協議支援。

方法引動過程

裝置會在 MQTT 主題上接收直接方法要求：$iothub/methods/POST/{method name}/?$rid={request id}。 不過，request id 是由 IoT 中樞產生，且無法事先得知，因此請訂閱 $iothub/methods/POST/#，然後根據裝置所支援的方法名稱篩選傳遞的訊息。 (您將使用 request id 來回應。)

裝置收到的本文格式如下：

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

方法要求為 QoS 0。

回應

裝置會將回應傳送至 $iothub/methods/res/{status}/?$rid={request id}，其中：

  • status 屬性是方法執行的裝置提供狀態。

  • $rid 屬性是來自 IoT 中樞所接收方法叫用中的要求識別碼。 要求標識碼是十六進位格式值。

本文是由裝置所設定，且可以是任何狀態。

AMQP

下一節適用於 AMQP 通訊協定。 若要深入瞭解直接搭配 IoT 中樞 使用AMQP通訊協定，請參閱AMQP通訊協議支援。

方法引動過程

裝置會透過在位址 amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 上建立接收連結，以接收直接方法要求。

AMQP 訊息會抵達表示方法要求的接收連結。 它包含以下各節：

  • 相互關聯識別碼屬性，其中包含應該使用對應方法回應傳回的要求識別碼。

  • 名為 IoThub-methodname 的應用程式屬性，其中包含所叫用方法的名稱。

  • 包含方法承載為 JSON 的 AMQP 訊息本文。

回應

裝置會建立傳送連結，以傳回位址 amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 上的方法回應。

方法的回應會在傳送連結上傳回，且結構化如下：

  • 相互關聯標識碼屬性，其中包含傳入方法要求訊息的要求標識符。

  • 名為 IoThub-status 的應用程式屬性，其中包含使用者提供的方法狀態。

  • 包含方法回應為 JSON 的 AMQP 訊息本文。

下一步

現在您已瞭解如何使用直接方法，您可能會對下列 IoT 中樞 開發人員指南文章感興趣：