Udostępnij za pośrednictwem

Jak kontrolować urządzenia przy użyciu interfejsu API REST usługi IoT Central

  • Artykuł

Interfejs API REST usługi IoT Central umożliwia tworzenie aplikacji klienckich, które integrują się z aplikacjami usługi IoT Central. Interfejs API REST umożliwia sterowanie urządzeniami w aplikacji usługi IoT Central. Interfejs API REST umożliwia:

  • Odczytaj ostatnią znaną wartość telemetrii z urządzenia.
  • Odczytywanie wartości właściwości z urządzenia.
  • Ustaw właściwości zapisywalne na urządzeniu.
  • Wywołaj polecenia na urządzeniu.

W tym artykule opisano sposób używania interfejsu API do kontrolowania /devices/{device_id} poszczególnych urządzeń. Zadania można również użyć do zbiorczego sterowania urządzeniami.

Urządzenie może grupować właściwości, dane telemetryczne i polecenia, które obsługuje w składnikach i modułach.

Każde wywołanie interfejsu API REST usługi IoT Central wymaga nagłówka autoryzacji. Aby dowiedzieć się więcej, zobacz Jak uwierzytelniać i autoryzować wywołania interfejsu API REST usługi IoT Central.

Aby uzyskać dokumentację referencyjną interfejsu API REST usługi IoT Central, zobacz Dokumentacja interfejsu API REST usługi Azure IoT Central.

Napiwek

Narzędzie Postman umożliwia wypróbowanie wywołań interfejsu API REST opisanych w tym artykule. Pobierz kolekcję IoT Central Postman i zaimportuj ją do narzędzia Postman. W kolekcji należy ustawić zmienne, takie jak poddomena aplikacji i token administratora.

Aby dowiedzieć się, jak kontrolować urządzenia przy użyciu interfejsu użytkownika usługi IoT Central, zobacz

Składniki i moduły

Składniki umożliwiają grupowanie i ponowne używanie możliwości urządzenia. Aby dowiedzieć się więcej na temat składników i modeli urządzeń, zobacz Przewodnik modelowania technologii IoT Plug and Play.

Nie wszystkie szablony urządzeń używają składników. Poniższy zrzut ekranu przedstawia szablon urządzenia dla prostego termostatu, w którym wszystkie możliwości są zdefiniowane w jednym interfejsie nazywanym składnikiem głównym:

Screenshot that shows a simple no component thermostat device.

Poniższy zrzut ekranu przedstawia szablon urządzenia kontrolera temperatury, który używa składników. Kontroler temperatury ma dwa składniki termostatu i składnik informacji o urządzeniu:

Screenshot that shows a temperature controller device with two thermostat components and a device information component.

W usłudze IoT Central moduł odwołuje się do modułu usługi IoT Edge działającego na połączonym urządzeniu usługi IoT Edge. Moduł może mieć prosty model, taki jak termostat, który nie używa składników. Moduł może również używać składników do organizowania bardziej złożonego zestawu możliwości. Poniższy zrzut ekranu przedstawia przykład szablonu urządzenia, który używa modułów. Urządzenie czujnika środowiska ma moduł o nazwie SimulatedTemperatureSensor i dziedziczony interfejs o nazwie management:

Screenshot that shows an environmental sensor device with a module.

Pobieranie składnika urządzenia

Użyj następującego żądania, aby pobrać składniki z urządzenia o nazwie temperature-controller-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components?api-version=2022-07-31

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Tablica value zawiera szczegóły każdego składnika urządzenia:

{
  "value": [
    {
      "@type": "Component",
      "name": "thermostat1",
      "displayName": "Thermostat One",
      "description": "Thermostat One of Two."
    },
    {
      "@type": "Component",
      "name": "thermostat2",
      "displayName": "Thermostat Two",
      "description": "Thermostat Two of Two."
    },
    {
      "@type": "Component",
      "name": "deviceInformation",
      "displayName": "Device Information interface",
      "description": "Optional interface with basic device hardware information."
    }
  ]
}

Pobieranie modułu urządzenia

Użyj następującego żądania, aby pobrać listę modułów uruchomionych na połączonym urządzeniu usługi IoT Edge o nazwie environmental-sensor-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Tablica modułów obejmuje tylko moduły niestandardowe uruchomione na urządzeniu usługi IoT Edge, a nie wbudowane $edgeAgent i $edgeHub moduły:

{
  "value": [
    {
      "@type": [
        "Relationship",
        "EdgeModule"
      ],
      "name": "SimulatedTemperatureSensor",
      "displayName": "SimulatedTemperatureSensor"
    }
  ]
}

Użyj następującego żądania, aby pobrać listę składników w module o nazwie SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules?api-version=2022-07-31

Odczytywanie danych telemetrycznych

Użyj następującego żądania, aby pobrać ostatnią znaną wartość telemetrii z urządzenia, które nie używa składników. W tym przykładzie urządzenie jest wywoływanethermostat-01, a dane telemetryczne są nazywane :temperature

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/telemetry/temperature?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "timestamp": "2021-03-24T12:33:15.223Z",
  "value": 40.10993804456927
}

Użyj następującego żądania, aby pobrać ostatnią znaną wartość telemetrii z urządzenia, które korzysta ze składników. W tym przykładzie urządzenie nosi nazwę temperature-controller-01, składnik jest nazywany , a telemetria nosi nazwę thermostat2temperature:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/telemetry/temperature?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "timestamp": "2021-03-24T12:43:44.968Z",
  "value": 70.29168040339141
}

Jeśli urządzenie jest urządzeniem usługi IoT Edge, użyj następującego żądania, aby pobrać ostatnią znaną wartość telemetrii z modułu. W tym przykładzie użyto urządzenia o nazwie environmental-sensor-01 z modułem o nazwie SimulatedTemperatureSensor i telemetrii o nazwie ambient. Typ ambient telemetrii ma wartości temperatury i wilgotności:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/telemetry/ambient?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "timestamp": "2021-03-25T15:44:34.955Z",
  "value": {
    "temperature": 21.18032378129676,
    "humidity": 25
  }
}

Napiwek

Aby uzyskać dostęp do danych telemetrycznych ze składnika w module, użyj polecenia /api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/telemetry/{telemetryName}.

Odczytywanie właściwości

Użyj następującego żądania, aby pobrać wartości właściwości z urządzenia, które nie używa składników. W tym przykładzie urządzenie nosi nazwę thermostat-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

Odpowiedź na to żądanie wygląda podobnie do poniższego przykładu. Pokazuje, że urządzenie zgłasza pojedynczą wartość właściwości:

{
  "maxTempSinceLastReboot": 93.95907131817654,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T12:47:46.7571438Z"
    }
  }
}

Użyj następującego żądania, aby pobrać wartości właściwości ze wszystkich składników. W tym przykładzie urządzenie nosi nazwę temperature-controller-01:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/properties?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "serialNumber": "Explicabo animi nihil qui facere sit explicabo nisi.",
  "$metadata": {
    "serialNumber": {
      "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
    }
  },
  "thermostat1": {
    "maxTempSinceLastReboot": 79.7290121339184,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "thermostat2": {
    "maxTempSinceLastReboot": 54.214860556320424,
    "$metadata": {
      "maxTempSinceLastReboot": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    }
  },
  "deviceInformation": {
    "manufacturer": "Eveniet culpa sed sit omnis.",
    "$metadata": {
      "manufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "model": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "swVersion": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "osName": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorArchitecture": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "processorManufacturer": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalStorage": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      },
      "totalMemory": {
        "lastUpdateTime": "2021-03-24T13:58:52.5999859Z"
      }
    },
    "model": "Necessitatibus id ab dolores vel eligendi fuga.",
    "swVersion": "Ut minus ipsum ut omnis est asperiores harum.",
    "osName": "Atque sit omnis eum sapiente eum tenetur est dolor.",
    "processorArchitecture": "Ratione enim dolor iste iure.",
    "processorManufacturer": "Aliquam eligendi sit ipsa.",
    "totalStorage": 36.02825898541592,
    "totalMemory": 55.442695395750505
  }
}

Użyj następującego żądania, aby pobrać wartość właściwości z pojedynczego składnika. W tym przykładzie urządzenie jest wywoływanetemperature-controller-01, a składnik jest nazywany :thermostat2

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "maxTempSinceLastReboot": 24.445128131004935,
  "$metadata": {
    "maxTempSinceLastReboot": {
      "lastUpdateTime": "2021-03-24T14:03:53.787491Z"
    }
  }
}

Jeśli urządzenie jest urządzeniem usługi IoT Edge, użyj następującego żądania, aby pobrać wartości właściwości z modułu. W tym przykładzie użyto urządzenia o nazwie environmental-sensor-01 z modułem o nazwie SimulatedTemperatureSensor:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "$metadata": {
    "SendData": {
      "desiredValue": true,
      "desiredVersion": 1
    },
    "SendInterval": {
      "desiredValue": 10,
      "desiredVersion": 1
    }
  }
}

Napiwek

Aby uzyskać dostęp do właściwości z składnika w module, użyj polecenia /devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties.

Właściwości zapisu

Niektóre właściwości można zapisywać. W przykładowym modelu termostatu targetTemperature właściwość jest właściwością zapisywalną.

Użyj następującego żądania, aby zapisać pojedynczą wartość właściwości na urządzeniu, które nie używa składników. W tym przykładzie urządzenie nosi nazwę thermostat-01:

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/properties?api-version=2022-07-31

Treść żądania wygląda podobnie do następującego przykładu:

{
  "targetTemperature": 65.5
}

Odpowiedź na to żądanie wygląda następująco:

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Napiwek

Aby zaktualizować wszystkie właściwości na urządzeniu, użyj polecenia PUT zamiast PATCH.

Użyj następującego żądania, aby zapisać pojedynczą wartość właściwości na urządzeniu, które używa składników. W tym przykładzie urządzenie jest wywoływanetemperature-controller-01, a składnik jest nazywany :thermostat2

PATCH https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/properties?api-version=2022-07-31

Treść żądania wygląda podobnie do następującego przykładu:

{
  "targetTemperature": 65.5
}

Odpowiedź na to żądanie wygląda następująco:

{
  "$metadata": {
    "targetTemperature": {
      "desiredValue": 65.5
    }
  }
}

Napiwek

Aby zaktualizować wszystkie właściwości składnika, użyj polecenia PUT zamiast PATCH.

Jeśli urządzenie jest urządzeniem usługi IoT Edge, użyj następującego żądania, aby zapisać pojedynczą wartość właściwości w module. W tym przykładzie użyto urządzenia o nazwie , modułu o environmental-sensor-01nazwie i właściwości o nazwie SimulatedTemperatureSensorSendInterval:

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/environmental-sensor-01/modules/SimulatedTemperatureSensor/properties?api-version=2022-07-31

Treść żądania wygląda podobnie do następującego przykładu:

{
  "SendInterval": 20
}

Odpowiedź na to żądanie wygląda następująco:

{
  "$metadata": {
    "SendInterval": {
      "desiredValue": 20
    }
  }
}

Napiwek

Aby zaktualizować wszystkie właściwości modułu, użyj polecenia PUT zamiast PATCH.

Aktualizowanie właściwości modułu

Jeśli używasz urządzenia usługi IoT Edge, użyj następującego żądania, aby pobrać wartości właściwości z modułu:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/properties?api-version=2022-07-31

Jeśli używasz urządzenia usługi IoT Edge, użyj następującego żądania, aby pobrać wartości właściwości ze składnika w module:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}/modules/{moduleName}/components/{componentName}/properties?api-version=2022-07-31

Wywołanie poleceń

Interfejs API REST umożliwia wywoływanie poleceń urządzenia i pobieranie historii poleceń.

Użyj następującego żądania, aby wywołać polecenie na urządzeniu, które nie używa składników. W tym przykładzie urządzenie jest wywoływane thermostat-01 , a polecenie nosi nazwę getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

Treść żądania wygląda podobnie do następującego przykładu:

{
  "request": "2021-03-24T12:55:20.789Z"
}

Odpowiedź na to żądanie wygląda następująco:

{
  "response": {
    "maxTemp": 21.002000799562367,
    "minTemp": 73.09674605264892,
    "avgTemp": 59.54553991653756,
    "startTime": "2022-02-28T15:02:56.789Z",
    "endTime": "2021-05-05T03:50:56.412Z"
  },
  "responseCode": 200
}

Aby wyświetlić historię tego polecenia, użyj następującego żądania:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/thermostat-01/commands/getMaxMinReport?api-version=2022-07-31

Odpowiedź na to żądanie wygląda następująco:

{
  "value": [
    {
      "response": {
        "maxTemp": 71.43744908819954,
        "minTemp": 51.29986610160005,
        "avgTemp": 39.577384387771744,
        "startTime": "2021-06-20T00:38:17.620Z",
        "endTime": "2022-01-07T22:30:41.104Z"
      },
      "responseCode": 200
    }
  ]
}

Użyj następującego żądania, aby wywołać polecenie na urządzeniu, które używa składników. W tym przykładzie urządzenie nosi nazwę temperature-controller-01, składnik nosi nazwę thermostat2, a polecenie nosi nazwę getMaxMinReport:

POST https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Formaty ładunku żądania i odpowiedzi są takie same jak w przypadku urządzenia, które nie używa składników.

Aby wyświetlić historię tego polecenia, użyj następującego żądania:

GET https://{your app subdomain}.azureiotcentral.com/api/devices/temperature-controller-01/components/thermostat2/commands/getMaxMinReport?api-version=2022-07-31

Napiwek

Aby wywołać polecenia w składniku w module, użyj polecenia /devices/{deviceId}/modules/{moduleName}/components/{componentName}/commands/{commandName}.

Następne kroki

Teraz, gdy wiesz już, jak kontrolować urządzenia za pomocą interfejsu API REST, sugerowanym następnym krokiem jest nauczenie się , jak używać interfejsu API REST usługi IoT Central do tworzenia zadań i zarządzania nimi.