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

  • Artykuł

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 danych, które są dla Ciebie ważne. W tym artykule opisano język zapytań IoT Hub routingu komunikatów i przedstawiono kilka typowych wzorców 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 IoT Hub. Aby uzyskać więcej informacji o warstwach podstawowa i Standardowa/Bezpłatna IoT Hub, zobacz Wybieranie odpowiedniej warstwy 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źniaczej reprezentacji urządzenia. Jeśli treść komunikatu nie jest w formacie JSON, routing komunikatów nadal może kierować komunikat, ale nie można zastosować zapytań do treści komunikatu. Zapytania są opisywane jako wyrażenia logiczne, gdzie, jeśli wartość true, zapytanie powiedzie się i przekierowuje 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 IoT Hub trasy. Składnia zapytania musi być poprawna, aby trasa została zapisana i obliczona.

Zapytanie na podstawie właściwości komunikatu

IoT Hub definiuje wspólny format dla wszystkich komunikatów z urządzenia do chmury na potrzeby współdziałania między protokołami. IoT Hub przyjmuje następującą reprezentację komunikatu w formacie JSON. Właściwości systemowe 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ż IoT Hub obsługa komunikatów z urządzenia do chmury nie uwzględnia wielkości liter. Jeśli na przykład masz wiele właściwości o tej samej nazwie, IoT Hub wyśle 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
Contenttype ciąg Użytkownik określa typ zawartości wiadomości. Aby zezwolić na wykonywanie zapytań w treści komunikatu, ta wartość powinna być ustawiona na application/JSONwartość .
contentEncoding ciąg Użytkownik określa typ kodowania komunikatu. Jeśli właściwość contentType jest ustawiona na application/JSONwartość , dozwolone wartości to UTF-8, UTF-16i UTF-32.
iothub-connection-device-id ciąg Ta wartość jest ustawiana przez IoT Hub i identyfikuje identyfikator urządzenia. Aby wysłać zapytanie, użyj polecenia $connectionDeviceId.
iothub-connection-module-id ciąg Ta wartość jest ustawiana przez IoT Hub i identyfikuje identyfikator modułu brzegowego. Aby wysłać zapytanie, użyj polecenia $connectionModuleId.
iothub-enqueuedtime ciąg Ta wartość jest ustawiana przez IoT Hub i reprezentuje rzeczywisty czas kolejkowania komunikatu w formacie UTC. Aby wysłać zapytanie, użyj polecenia $enqueuedTime.
dt-dataschema ciąg Ta wartość jest ustawiana przez 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 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 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 mieć prefiks z 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 $, IoT Hub najpierw wyszuka ją we właściwościach systemu, a jeśli nie zostanie znaleziona, wyszuka 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 wysłać zapytanie dotyczące zawartości właściwości systemowejEncoding:

$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żeń i warunkówjęzyka zapytań 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ść systemowa contentType musi mieć wartość application/JSON. Właściwość systemowa contentEncoding 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 zostaną określone, IoT Hub nie oceni 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 uzyskać przykład kodowania komunikatów w języku C#, zobacz HubRoutingSample podany w zestawie SDK usługi Microsoft Azure IoT dla platformy .NET. Ten przykład jest taki sam, jak 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 zapytania treści komunikatu

Zapytanie dotyczące treści komunikatu musi mieć prefiks $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 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. Aby na przykład filtrować, gdy istnieje żądana zmiana sendFrequency 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)

Wykonywanie zapytań na podstawie bliźniaczej reprezentacji urządzenia lub modułu

Routing komunikatów umożliwia wykonywanie zapytań dotyczących bliźniaczej reprezentacji urządzenia lub tagów bliźniaczej reprezentacji modułu i właściwości, które są obiektami JSON. Poniższy przykład ilustruje bliźniaczą 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 IoT Edge) względem bliźniaczej reprezentacji modułu, a nie odpowiadającej im bliźniaczej reprezentacji urządzenia.

Wyrażenia zapytań bliźniaczych reprezentacji

Zapytanie dotyczące bliźniaczej reprezentacji urządzenia lub bliźniaczej reprezentacji modułu musi mieć prefiks $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 bliźniaczych reprezentacji urządzeń i bliźniaczych reprezentacji modułów. Zalecamy również unikanie używania twinnazw właściwości , $twin, bodylub $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 dotyczące 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