IoT Hub REST

  • Artykuł

Interfejsy API REST dla IoT Hub oferują programowy dostęp do urządzenia, obsługi komunikatów i usług zadań, a także dostawcy zasobów w IoT Hub. Możesz uzyskać dostęp do usług obsługi wiadomości z usługi IoT działającej na platformie Azure bezpośrednio przez Internet z dowolnej aplikacji, która może wysyłać żądanie protokołu HTTPS i odbierać odpowiedź protokołu HTTPS.

Usługa

  • Ten interfejs API służy do zarządzania bliźniaczymi reprezentacjami urządzeń IoT Hub. Właściwości bliźniaczej reprezentacji urządzenia można pobierać i aktualizować oraz wywoływać metody bezpośrednie na urządzeniach.
  • Te interfejsy API umożliwiają zarządzanie tożsamościami urządzeń w rejestrze tożsamości centrum IoT.
  • Użyj tego interfejsu API do zarządzania zadaniami w IoT Hub. Możesz zaplanować, anulować lub pobrać zadanie.

Wszystkie operacje zadań są zgodne ze specyfikacją protokołu HTTP/1.1, a każda operacja zwraca x-ms-request-id nagłówek, którego można użyć do uzyskania informacji o żądaniu. Musisz się upewnić, że żądania wysyłane do tych zasobów są bezpieczne. Aby uzyskać więcej informacji, zobacz IoT Hub Developer Guide — Security for the specifics on how to create security tokens (Przewodnik dla deweloperów — zabezpieczenia dotyczące tworzenia tokenów zabezpieczających).

Obsługa komunikatów urządzenia

Te interfejsy API z urządzenia umożliwiają wysyłanie komunikatów z urządzenia do chmury do centrum IoT i odbieranie komunikatów z chmury do urządzenia z centrum IoT Hub. Wszystkie operacje zadań są zgodne ze specyfikacją protokołu HTTP/1.1. Musisz się upewnić, że żądania wysyłane do tych zasobów są bezpieczne. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów IoT Hub — zabezpieczenia, aby uzyskać szczegółowe informacje na temat tworzenia tokenów zabezpieczających.

Dostawca zasobów

Te interfejsy API umożliwiają zarządzanie wdrażaniem zasobów IoT Hub. Aby uzyskać informacje na temat zabezpieczania tych żądań, zobacz Dokumentacja interfejsu API REST platformy Azure.

Typowe parametry i nagłówki

Następujące informacje są wspólne dla wszystkich zadań związanych z IoT Hub:

  • Zastąp ciąg {api-version} ciągiem "2018-06-30" w identyfikatorze URI.

  • Zastąp ciąg {subscription-id} identyfikatorem subskrypcji w identyfikatorze URI.

  • Zastąp ciąg {resourceGroupName} nazwą grupy zasobów zawierającą (lub będzie zawierać) centrum IoT.

  • Zastąp element {IoTHubName} nazwą centrum IoT Hub.

  • Ustaw nagłówek Content-Type na wartość application/json.

  • Ustaw nagłówek autoryzacji na token SAS utworzony zgodnie z opisem w sekcji Tokeny zabezpieczające w sekcji Używanie tokenów zabezpieczających IoT Hub.

  • Nagłówek Etag jest zwracany we wszystkich żądaniach w zakresie pojedynczej tożsamości urządzenia zgodnie z RFC7232.

  • Wszystkie operacje PUT/PATCH wymagają określenia następujących nagłówków: If-Match = [*|<etag from get>]

  • Operacje USUWANIA mogą zawierać następujący nagłówek: If-Match = [*|<etag from get>]

Poniżej przedstawiono zachowanie elementów ETag:

PUT Zasób nie istnieje Zasób istnieje
If-Match = "" / nieobecny Utworzono 201 200 OK
If-Match = "*" 412 Warunek wstępny nie powiódł się 200 OK
If-Match = "xyz" 412 Warunek wstępny nie powiódł się 200 OK / 412 Warunek wstępny nie powiodło się
If-None-Match = "*" Utworzono 201 412 Warunek wstępny nie powiódł się
DELETE Zasób nie istnieje Zasób istnieje
If-Match = "" / nieobecny 204 Brak zawartości 200 OK
If-Match = "*" 204 Brak zawartości 200 OK
If-Match = "xyz" 204 Brak zawartości 200 OK / 412 Warunek wstępny nie powiodło się

W przypadku wywołań asynchronicznych:

  • Put odpowiada za pomocą polecenia 201 Utworzone z nagłówkiem Azure-AsyncOperation dla wszystkich operacji, które są asynchroniczne. Wszystkie operacje synchroniczne (aktualizacje) zwracają 200 OK.

  • Funkcja DELETE zwraca wartość 202 Akceptowana z nagłówkami Location i Retry-After, a także Azure-AsyncOperation nagłówkiem zasobów, które istnieją.

  • Nagłówek location zawiera adres URL wyniku operacji

  • nagłówek Retry-After zawiera odpowiedni interwał ponawiania prób w sekundach

  • nagłówek Azure-AsyncOperation zawiera adres URL stanu wyniku operacji asynchronicznych

  • Po zakończeniu adres URL wyniku operacji GET generuje dokładnie taki sam wynik, jak wtedy, gdy oryginalna operacja została ukończona synchronicznie