Udostępnij za pomocą

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

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 reprezentacji bliźniaczej urządzenia, do różnych punktów końcowych. Możesz również zastosować zaawansowane zapytania do tych danych, zanim zostaną przekierowane, aby otrzymać istotne dane. 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 wiadomości z chmury do urządzenia, bliźniacze reprezentacje urządzeń i zarządzanie urządzeniami, są dostępne tylko w standardowej wersji 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 i rozmiaru usługi IoT Hub dla rozwiązania.

Routing komunikatów umożliwia wykonywanie zapytań dotyczących właściwości i treści komunikatów, a także tagów i właściwości bliźniaczych modeli urządzeń. Jeśli treść komunikatu nie jest w formacie JSON, możliwe jest nadal przekierowanie wiadomości, ale zapytania nie mogą być stosowane do treści wiadomości. Zapytania są opisywane jako wyrażenia logiczne, w których, jeśli jest prawdziwe, zapytanie zakończy się sukcesem i kieruje wszystkie dane przychodzące; w przeciwnym razie nie powiedzie się i dane nie są kierowane. Jeśli wyrażenie zwróci wartość null lub niezdefiniowaną, jest traktowane jako wartość logiczna fałszywa i generuje błąd w dziennikach zasobów routingu 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.

Uwaga

Zalecamy używanie unikatowych nazw właściwości, ponieważ przesyłanie komunikatów z urządzenia do chmury w usłudze IoT Hub jest niewrażliwe na wielkość 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ść Typ Opis
typ treści ciąg 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.
kodowanie zawartości ciąg 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-16i UTF-32.
identyfikator-urządzenia-połączenia-iothub ciąg Usługa IoT Hub ustawia tę wartość, która identyfikuje identyfikator urządzenia. Aby wysłać zapytanie, użyj polecenia $connectionDeviceId.
Identyfikator modułu połączenia iothub ciąg Usługa IoT Hub ustawia tę wartość, która identyfikuje identyfikator modułu brzegowego. Aby wysłać zapytanie, użyj polecenia $connectionModuleId.
iothub-enqueuedtime ciąg Usługa IoT Hub ustawia tę wartość, która reprezentuje rzeczywisty czas kolejkowania komunikatu w formacie UTC. Aby wysłać zapytanie, użyj polecenia $enqueuedTime.
dt-schemat danych ciąg IoT Hub ustawia tę wartość na wiadomościach z urządzenia do chmury. Zawiera identyfikator modelu urządzenia ustawiony w połączeniu urządzenia. Aby wysłać zapytanie, użyj polecenia $dt-dataschema.
dt-subject ciąg 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 zapytań dotyczące 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 właściwości systemowej contentEncoding:

$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 warunkiję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 to ten sam, którego użyto w samouczku 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 wiadomości

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 undefined:

$body[0] = 'Feb'

Aby filtrować ładunek powiadomienia o bliźniaczym stanie na podstawie tego, co się zmieniło, uruchom zapytanie w treści wiadomości. Na przykład, aby filtrować, gdy nastąpi zmiana żądanej właściwości na sendFrequency, 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

Trasowanie wiadomości umożliwia wykonywanie zapytań dotyczących tagów i właściwości bliźniaka urządzenia lub bliźniaka modułu, które są obiektami JSON. Poniższy przykład ilustruje cyfrowego bliźniaka 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 z odpowiadających urządzeń. Zapytania typu bliźniaczego dla komunikatów z modułów urządzenia (na przykład z modułów IoT Edge) kierują zapytania do modułu bliźniaczego, a nie odpowiadającego urządzenia typu bliźniaczego.

Bliźniacze wyrażenia zapytań

Zapytanie dotyczące bliźniaka urządzenia lub bliźniaka modułu musi być poprzedzone prefiksem $twin. Wyrażenie zapytania może również połączyć tag bliźniaczy lub odwołanie do właściwości z odwołaniem do treści, odwołaniem do właściwości komunikatów systemowych lub odwołaniem do właściwości aplikacji komunikatów. 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

Uwaga

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źniaków urządzeń, jak i bliźniaków modułów. Należy również unikać używania twin, $twin, body lub $body jako nazw właściwości.

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 bliźniaczej ścieżce urządzenia/modułu: ()<>@,;:\"/?={}.

Następne kroki

  • Last updated on