Składnia zapytania dotyczącego routingu komunikatów usługi IoT Hub

Artykuł
06/13/2024

Routing komunikatów umożliwia użytkownikom kierowanie różnych typów danych, w tym komunikatów telemetrycznych urządzenia, zdarzeń cyklu życia urządzenia i zdarzeń zmiany bliźniaczej reprezentacji urządzenia, do różnych punktów końcowych. Możesz również zastosować zaawansowane zapytania do tych danych, zanim rozsyłają je w celu odebrania ważnych danych. W tym artykule opisano język zapytań routingu komunikatów usługi IoT Hub i przedstawiono niektóre typowe wzorce zapytań.

Uwaga

Niektóre funkcje wymienione w tym artykule, takie jak obsługa komunikatów w chmurze, bliźniacze reprezentacje urządzeń i zarządzanie urządzeniami, są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy usługi IoT Hub dla rozwiązania.

Routing komunikatów umożliwia wykonywanie zapytań dotyczących właściwości komunikatów i treści komunikatów, a także tagów bliźniaczej reprezentacji urządzenia i właściwości bliźniaczych reprezentacji urządzenia. Jeśli treść komunikatu nie jest w formacie JSON, routing komunikatów nadal może kierować komunikat, ale zapytania nie mogą być stosowane do treści komunikatu. Zapytania są opisywane jako wyrażenia logiczne, w których, jeśli prawda, zapytanie powiedzie się i kieruje wszystkie dane przychodzące; w przeciwnym razie zapytanie kończy się niepowodzeniem i dane przychodzące nie są kierowane. Jeśli wyrażenie zwróci wartość null lub niezdefiniowaną, jest traktowane jako wartość logiczna false i generuje błąd w dziennikach zasobów usługi IoT Hub. Składnia zapytania musi być poprawna, aby trasa została zapisana i obliczona.

Zapytanie na podstawie właściwości komunikatu

Usługa IoT Hub definiuje wspólny format dla wszystkich komunikatów z urządzenia do chmury na potrzeby współdziałania między protokołami. Usługa IoT Hub zakłada następującą reprezentację komunikatu w formacie JSON. Właściwości systemu są dodawane dla wszystkich użytkowników i identyfikują zawartość komunikatu. Użytkownicy mogą selektywnie dodawać właściwości aplikacji do komunikatu. Zalecamy używanie unikatowych nazw właściwości, ponieważ obsługa komunikatów z urządzenia do chmury w usłudze IoT Hub nie uwzględnia wielkości liter. Jeśli na przykład masz wiele właściwości o tej samej nazwie, usługa IoT Hub wysyła tylko jedną z właściwości.

{ 
  "message": { 
    "systemProperties": { 
      "contentType": "application/json", 
      "contentEncoding": "UTF-8", 
      "iothub-message-source": "deviceMessages", 
      "iothub-enqueuedtime": "2017-05-08T18:55:31.8514657Z" 
    }, 
    "appProperties": { 
      "processingPath": "{cold | warm | hot}", 
      "verbose": "{true, false}", 
      "severity": 1-5, 
      "testDevice": "{true | false}" 
    }, 
    "body": "{\"Weather\":{\"Temperature\":50}}" 
  } 
}

Właściwości systemu

Właściwości systemu pomagają zidentyfikować zawartość i źródło komunikatów, z których niektóre zostały opisane w poniższej tabeli:

Właściwość	Type	Opis
contentType	string	Użytkownik określa typ zawartości komunikatu. Aby zezwolić na wykonywanie zapytań w treści komunikatu, ta wartość powinna być ustawiona na `application/JSON`wartość .
contentEncoding	string	Użytkownik określa typ kodowania komunikatu. Jeśli właściwość contentType jest ustawiona na `application/JSON`, dozwolone wartości to `UTF-8`, `UTF-16`i `UTF-32`.
iothub-connection-device-id	string	Ta wartość jest ustawiana przez usługę IoT Hub i identyfikuje identyfikator urządzenia. Aby wysłać zapytanie, użyj polecenia `$connectionDeviceId`.
iothub-connection-module-id	string	Ta wartość jest ustawiana przez usługę IoT Hub i identyfikuje identyfikator modułu brzegowego. Aby wysłać zapytanie, użyj polecenia `$connectionModuleId`.
iothub-enqueuedtime	string	Ta wartość jest ustawiana przez usługę IoT Hub i reprezentuje rzeczywisty czas kolejkowania komunikatu w formacie UTC. Aby wysłać zapytanie, użyj polecenia `$enqueuedTime`.
dt-dataschema	string	Ta wartość jest ustawiana przez usługę IoT Hub w komunikatach urządzenie-chmura. Zawiera identyfikator modelu urządzenia ustawiony w połączeniu urządzenia. Aby wysłać zapytanie, użyj polecenia `$dt-dataschema`.
dt-subject	string	Nazwa składnika wysyłającego komunikaty z urządzenia do chmury. Aby wysłać zapytanie, użyj polecenia `$dt-subject`.

Aby uzyskać więcej informacji o innych dostępnych właściwościach systemu, zobacz Tworzenie i odczytywanie komunikatów usługi IoT Hub.

Właściwości aplikacji

Właściwości aplikacji to ciągi zdefiniowane przez użytkownika, które można dodać do komunikatu. Te pola są opcjonalne.

Wyrażenia zapytania właściwości komunikatu

Zapytanie dotyczące właściwości systemu komunikatów musi być poprzedzone symbolem $ . Dostęp do zapytań dotyczących właściwości aplikacji jest uzyskiwany przy użyciu ich nazwy i nie powinien być poprzedzony symbolem $. Jeśli nazwa właściwości aplikacji zaczyna się od $, usługa IoT Hub najpierw wyszukuje ją we właściwościach systemu, a jeśli nie zostanie znaleziona, wyszukaj ją we właściwościach aplikacji. W poniższych przykładach pokazano, jak wykonywać zapytania dotyczące właściwości systemu i właściwości aplikacji.

Aby wykonywać zapytania dotyczące zawartości właściwości systemuEncoding:

$contentEncoding = 'UTF-8'

Aby wysłać zapytanie dotyczące ścieżki przetwarzania właściwości aplikacji:

processingPath = 'hot'

Aby połączyć te zapytania, możesz użyć wyrażeń logicznych i funkcji:

$contentEncoding = 'UTF-8' AND processingPath = 'hot'

Pełna lista obsługiwanych operatorów i funkcji znajduje się w sekcji wyrażenia i warunków języka zapytań usługi IoT Hub dla bliźniaczych reprezentacji urządzeń i modułów, zadań i routingu komunikatów.

Zapytanie oparte na treści komunikatu

Aby włączyć wykonywanie zapytań w treści komunikatu, komunikat powinien być w formacie JSON i zakodowany w formacie UTF-8, UTF-16 lub UTF-32. Właściwość contentType systemowa musi mieć wartość application/JSON. Właściwość contentEncoding systemowa musi być jedną z wartości kodowania UTF obsługiwanych przez tę właściwość systemowa. Jeśli te właściwości systemowe nie są określone, usługa IoT Hub nie ocenia wyrażenia zapytania w treści komunikatu.

W poniższym przykładzie języka JavaScript pokazano, jak utworzyć komunikat z prawidłowo sformułowaną i zakodowaną treścią JSON:

var messageBody = JSON.stringify(Object.assign({}, {
    "Weather": {
        "Temperature": 50,
        "Time": "2017-03-09T00:00:00.000Z",
        "PrevTemperatures": [
            20,
            30,
            40
        ],
        "IsEnabled": true,
        "Location": {
            "Street": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA"
        },
        "HistoricalData": [
            {
                "Month": "Feb",
                "Temperature": 40
            },
            {
                "Month": "Jan",
                "Temperature": 30
            }
        ]
    }
}));

// Encode message body using UTF-8  
var messageBytes = Buffer.from(messageBody, "utf8");

var message = new Message(messageBytes);

// Set message body type and content encoding 
message.contentEncoding = "utf-8";
message.contentType = "application/json";

// Add other custom application properties   
message.properties.add("Status", "Active");

deviceClient.sendEvent(message, (err, res) => {
    if (err) console.log('error: ' + err.toString());
    if (res) console.log('status: ' + res.constructor.name);
});

Aby zapoznać się z przykładem kodowania komunikatów w języku C#, zobacz hubRoutingSample podany w zestawie MICROSOFT Azure IoT SDK dla platformy .NET. Ten przykład jest taki sam, który jest używany w samouczku dotyczącym routingu komunikatów. Plik Program.cs ma również metodę o nazwie ReadOneRowFromFile, która odczytuje jeden z zakodowanych plików, dekoduje go i zapisuje go z powrotem jako ASCII, aby można było go odczytać.

Wyrażenia zapytań treści komunikatów

Kwerenda w treści komunikatu musi być poprzedzona prefiksem $body. W wyrażeniu zapytania można użyć odwołania do treści, odwołania do tablicy treści lub wielu odwołań do treści. Wyrażenie zapytania może również połączyć odwołanie do treści z odwołaniem do właściwości systemu komunikatów lub odwołaniem do właściwości aplikacji komunikatu. Na przykład wszystkie prawidłowe wyrażenia zapytania to na przykład następujące przykłady:

$body.Weather.HistoricalData[0].Month = 'Feb'

$body.Weather.Temperature = 50 AND $body.Weather.IsEnabled

length($body.Weather.Location.State) = 2

$body.Weather.Temperature = 50 AND processingPath = 'hot'

Zapytania i funkcje można uruchamiać tylko na właściwościach w odwołaniu do treści. Nie można uruchamiać zapytań ani funkcji w całym odwołaniu do treści. Na przykład następujące zapytanie nie jest obsługiwane i zwraca wartość undefined:

$body[0] = 'Feb'

Aby filtrować ładunek powiadomienia bliźniaczej reprezentacji na podstawie tego, co się zmieniło, uruchom zapytanie w treści komunikatu. Na przykład, aby filtrować, gdy nastąpiła zmiana sendFrequency żądanej właściwości, a wartość jest większa niż 10:

$body.properties.desired.telemetryConfig.sendFrequency > 10

Aby filtrować komunikaty zawierające zmianę właściwości, niezależnie od wartości właściwości, można użyć is_defined() funkcji (gdy wartość jest typem pierwotnym):

is_defined($body.properties.desired.telemetryConfig.sendFrequency)

Zapytanie oparte na bliźniaczej reprezentacji urządzenia lub modułu

Routing komunikatów umożliwia wykonywanie zapytań dotyczących tagów bliźniaczej reprezentacji urządzenia lub tagów bliźniaczych reprezentacji modułu, które są obiektami JSON. Poniższy przykład ilustruje bliźniacze reprezentację urządzenia z tagami i właściwościami:

{
    "tags": { 
        "deploymentLocation": { 
            "building": "43", 
            "floor": "1" 
        } 
    }, 
    "properties": { 
        "desired": { 
            "telemetryConfig": { 
                "sendFrequency": "5m" 
            }, 
            "$metadata" : {...}, 
            "$version": 1 
        }, 
        "reported": { 
            "telemetryConfig": { 
                "sendFrequency": "5m", 
                "status": "success" 
            },
            "batteryLevel": 55, 
            "$metadata" : {...}, 
            "$version": 4 
        } 
    } 
}

Uwaga

Moduły nie dziedziczą tagów bliźniaczych reprezentacji z odpowiednich urządzeń. Zapytania bliźniaczej reprezentacji dla komunikatów pochodzących z modułów urządzenia (na przykład z modułów usługi IoT Edge) wysyłają zapytania względem bliźniaczej reprezentacji modułu, a nie odpowiadającej im bliźniaczej reprezentacji urządzenia.

Wyrażenia zapytania reprezentacji bliźniaczej

Zapytanie dotyczące bliźniaczej reprezentacji urządzenia lub bliźniaczej reprezentacji modułu musi być poprzedzone prefiksem $twin. Wyrażenie zapytania może również połączyć tag bliźniaczej reprezentacji lub odwołanie do właściwości z odwołaniem do treści, odwołaniem do właściwości systemu komunikatów lub odwołaniem do właściwości aplikacji komunikatu. Zalecamy używanie unikatowych nazw w tagach i właściwościach, ponieważ zapytanie nie uwzględnia wielkości liter. To zalecenie dotyczy zarówno bliźniaczych reprezentacji urządzeń, jak i bliźniaczych reprezentacji modułów. Zalecamy również unikanie używania twinnazw właściwości , , $twinbodylub $body . Na przykład wszystkie prawidłowe wyrażenia zapytania to na przykład następujące przykłady:

$twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$body.Weather.Temperature = 50 AND $twin.properties.desired.telemetryConfig.sendFrequency = '5m'

$twin.tags.deploymentLocation.floor = 1

Ograniczenia

Zapytania routingu nie obsługują używania białych znaków ani żadnego z następujących znaków w nazwach właściwości, ścieżce treści komunikatu ani ścieżce bliźniaczej reprezentacji urządzenia/modułu: ()<>@,;:\"/?={}.

Następne kroki

Dowiedz się więcej o routingu komunikatów.
Wypróbuj samouczek dotyczący routingu komunikatów.

Udostępnij za pośrednictwem