Olvasás angol nyelven

Megosztás a következőn keresztül:

CloudEvents-bővítmény az Azure Web PubSub MQTT eseménykezelőhöz HTTP-protokollal

  • Cikk

A Web PubSub szolgáltatás a CloudEvents HTTP protokollkötésével kézbesíti az ügyféleseményeket a felsőbb rétegbeli webhooknak.

A Web PubSub szolgáltatásból a kiszolgálóra küldött adatok mindig CloudEvents formátumúak binary .

Webhook ellenőrzése

A webhook érvényesítése a CloudEventst követi. Minden webhookvégpontnak el kell fogadnia a fejlécben található WebHook-Request-Origin: xxx.webpubsub.azure.com HTTP OPTIONS-kéréseket, és a fejlécet is beleértve válaszolnia kell a WebHook-Allowed-Origin kérésre. Példa:

WebHook-Allowed-Origin: *

Or:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

A WebHook-Request-Rate és a WebHook-Request-Callback jelenleg nem támogatott.

Web PubSub CloudEvents attribútumbővítmény

Ez a bővítmény határozza meg a Web PubSub által minden általa létrehozott eseményhez használt attribútumokat.

Név Típus Leírás Példa
userId string A kapcsolat hitelesített felhasználói azonosítója.
hub string Az a központ, amelyhez a kapcsolat tartozik.
connectionId string Az ügyfél azonosítója az MQTT protokollban.
eventName string Az esemény neve előtag nélkül.
subprotocol string Mindig.mqtt
connectionState string Meghatározza a kapcsolat állapotát. Ugyanezzel a válaszfejléccel alaphelyzetbe állíthatja az állapot értékét. Több connectionState fejléc nem engedélyezett. A sztringérték kódolása a base64-ben, ha összetett karaktereket tartalmaz; Például összetett objektumok átadására használható base64(jsonString) ezzel az attribútummal.
signature string A felsőbb rétegbeli webhook aláírása annak ellenőrzéséhez, hogy a bejövő kérés a várt forrásból származik-e. A szolgáltatás az elsődleges és a másodlagos hozzáférési kulcsok használatával is kiszámítja az értéket HMAC-kulcsként: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). A felsőbb rétegnek ellenőriznie kell, hogy a kérés érvényes-e a feldolgozás előtt.
physicalConnectionId string A szolgáltatás által az egyes fizikai kapcsolatokhoz létrehozott egyedi azonosító. A formátuma változhat, ezért nem érdemes elemezni.
sessionId string A szolgáltatás által az egyes munkamenetekhez létrehozott egyedi azonosító. Nem létezik az connect eseményben. A formátuma változhat, ezért nem érdemes elemezni.

esemény

Kétféle esemény létezik: az események blokkolása , ahol a szolgáltatás megvárja az esemény válaszának folytatását, és feloldja az események blokkolását , ahol a szolgáltatás nem várja meg az esemény válaszát a következő üzenet feldolgozása előtt.

Események blokkolása

Események blokkolásának feloldása

Megjegyzés

  • A specifikáció TypeSpec-verziójával kapcsolatban lásd: TypeSpec. Érdemes lehet megnyitni a fájlt a TypeSpec Playground-ben a jobb olvasási élmény és a létrehozott Swagger felhasználói felület érdekében.
  • A specifikáció Swagger-verziójával kapcsolatban lásd: Swagger. Érdemes lehet megnyitni a fájlt a Swagger-szerkesztőben a jobb olvasási élmény és a létrehozott Swagger felhasználói felület érdekében.

Rendszeresemény connect

  • ce-type: azure.webpubsub.sys.connect
  • Content-Type: application/json

Kérelem formátuma

Minden alkalommal, amikor a szolgáltatások CONNECT-csomagot kapnak az ügyfelektől, kérést connect küld a felsőbb rétegnek.

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/client/{clientId}/{physicalConnectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-connectionId: {clientId}
ce-hub: {hub}
ce-eventName: connect
ce-physicalConnectionId: {physicalConnectionId}

{
  "mqtt": {
    "protocolVersion": 4,
    "cleanStart": true,
    "username": null,
    "password": null,
    "userProperties": null
  },
  "claims": {
    "type1": ["value1"]
  },
  "query": {
    "queryKey1": ["queryValue1"]
  },
  "headers": {
    "Connection": ["Upgrade"]
  },
  "subprotocols": ["mqtt"],
  "clientCertificates": [
    {
      "thumbprint": "3ce9b08a37566915dec4d1662cd2102121a99868",
      "content": "{string content of PEM format certificate}"
    }
  ]
}

  • mqtt.protocolVersion: {MQTT protocol version of the client} Egész szám; lehetséges értékek: 4 (MQTT 3.1.1) és 5 (MQTT 5.0).

  • mqtt.username: {Username field in the MQTT CONNECT packet} UTF-8 kódolású sztring. mqtt.username és mqtt.password használható az ügyfelek felsőbb rétegbeli webhook-hitelesítéséhez.

  • mqtt.password: {Password field in the MQTT CONNECT packet} Base64 kódolású bináris adatok. Az ügyfélhitelesítéshez használt felhasználónévvel kombinálva.

  • mqtt.userProperties: {User properties field in the MQTT CONNECT packet} A sztringkulcs-érték párok listája. További diagnosztikai vagy egyéb információk, amelyeket azok az ügyfelek nyújtanak, amelyek protokolljai támogatják a felhasználói tulajdonságokat. Jelenleg csak az MQTT 5.0 támogatja.

Sikeres válasz formátuma

  • Fejléc ce-connectionState: Ha ez az élőfej létezik, a kapcsolat állapota a fejléc értékére frissül. Vegye figyelembe, hogy csak a blokkoló események frissíthetik a kapcsolat állapotát. Az alábbi minta egy base64 kódolású JSON-sztringet használ a kapcsolat összetett állapotának tárolásához.

  • HTTP-állapotkód:

    • 204: Siker tartalom nélkül.
    • 200:Siker; A tartalomnak JSON formátumban kell lennie, és a következő tulajdonságok engedélyezettek:
HTTP/1.1 200 OK

{
  "groups": ["newGroup1"],
  "subProtocol": "mqtt",
  "userId": "userId1",
  "roles": ["webpubsub.sendToGroup", "webpubsub.joinLeaveGroup"],
  "mqtt": {
    "userProperties": [
      {
        "name": "name1",
        "value": "value1"
      }
    ]
  }
}

  • subprotocol: Mindig null értékűnek kell lennie mqtt . Null érték esetén alapértelmezés szerint a .mqtt

  • userId: {authenticated user ID} Mivel a szolgáltatás névtelen kapcsolatokat tesz lehetővé, az connect esemény felelőssége, hogy az ügyfélkapcsolat felhasználói azonosítóját adja meg a szolgáltatásnak. A szolgáltatás beolvassa a felhasználói azonosítót a válasz hasznos adataiból userId , ha létezik. Ez a tulajdonság csak akkor lép érvénybe, ha új munkamenet jön létre a fizikai kapcsolathoz. Ha a fizikai kapcsolat egy meglévő munkamenethez van csatlakoztatva, a rendszer figyelmen kívül hagyja ezt a tulajdonságot, és a rendszer a meglévő munkamenet felhasználói azonosítóját használja.

  • groups: {groups to join} Ezzel a tulajdonságtal kényelmesen hozzáadhatja a kapcsolatot egy vagy több csoporthoz. Az MQTT szempontjából egy vagy több előfizetést rendel hozzá alapértelmezett előfizetési lehetőségekkel az ügyfélhez, a csoportnevek pedig témakörszűrők. Ez a tulajdonság csak akkor lép érvénybe, ha új munkamenet jön létre a fizikai kapcsolathoz. Ha a fizikai kapcsolat egy meglévő munkamenethez csatlakozik, a rendszer figyelmen kívül hagyja ezt a tulajdonságot.

  • roles: {roles the client has} Ez a tulajdonság módot biztosít a felsőbb rétegbeli webhook számára az ügyfél engedélyezésére. A PubSub WebSocket-ügyfelek kezdeti engedélyeinek megadásához különböző szerepkörök tartoznak. Az engedélyekkel kapcsolatos részleteket az ügyfélengedélyek ismertetik. Ez a tulajdonság csak akkor lép érvénybe, ha új munkamenet jön létre a fizikai kapcsolathoz. Ha a fizikai kapcsolat egy meglévő munkamenethez csatlakozik, a rendszer figyelmen kívül hagyja ezt a tulajdonságot.

  • mqtt.userProperties: {user properties that will be sent to clients in the CONNACK packet} A sztringkulcs-érték párok listája. Ezeket a CONNACK felhasználói tulajdonságokká konvertálja, és elküldi azoknak az ügyfeleknek, akiknek a protokolljai támogatják a felhasználói tulajdonságokat. Jelenleg csak az MQTT 5.0 támogatja a felhasználói tulajdonságokat. A felsőbb rétegbeli webhook további diagnosztikai vagy egyéb információkhoz használhatja ezt a tulajdonságot.

Miután a szolgáltatás sikeres választ kap a felsőbb rétegtől, egy sikeres CONNACK-csomagot küld az ügyfélnek.

Hibaválasz formátuma

  • 4xx vagy 5xx: Hiba. A tartalomtípusnak a következőnek kell lennie application/json: . Miután a szolgáltatás hibaüzenetet kap, ennek megfelelően egy sikertelen CONNACK-csomagot küld az ügyfélnek.
HTTP/1.1 401 Unauthorized
{
  "mqtt": {
    "code": 138,  // The CONNACK return code / reason code
    "reason": "banned by server",  // The reason string
    "userProperties": [{ "name": "name1", "value": "value1" }]
  }
}

  • mqtt.code: {return code (MQTT 3.1.1) or reason code (MQTT 5.0) that will be sent to clients in the CONNACK packet} A hiba okát jelző egész szám. A CONNACK csomagban lévő ügyfeleknek visszaküldési kódként (MQTT 3.1.1) vagy okkódként (MQTT 5.0) küldi el. A felsőbb rétegbeli webhooknak ki kell választania egy érvényes egész számot, amelyet az MQTT-protokollok határoznak meg az ügyfelek protokollverzióinak megfelelően. Ha a felsőbb rétegbeli webhook érvénytelen értéket állít be, az ügyfelek "meghatározatlan hibát" kapnak a CONNACK-csomagban.

  • mqtt.reason: {failure reason string} A diagnosztika számára tervezett emberi olvasási hiba ok sztringje. A rendszer elküldi azoknak az ügyfeleknek, akiknek a protokolljai támogatják a CONNACK-csomagban található oksztringet. Jelenleg csak az MQTT 5.0 támogatja.

  • mqtt.userProperties: {user properties that will be sent to clients in the CONNACK packet} A sztringkulcs-érték párok listája. A rendszer a CONNACK-csomagban felhasználói tulajdonságokká alakítja őket, és elküldi őket azoknak az ügyfeleknek, akiknek a protokolljai támogatják a felhasználói tulajdonságokat. Jelenleg csak az MQTT 5.0 támogatja a felhasználói tulajdonságokat. A felsőbb rétegbeli webhook további diagnosztikai vagy egyéb információkhoz használhatja ezt a tulajdonságot.

Rendszeresemény connected

A szolgáltatás ezzel az eseménysel értesíti a felsőbb réteget egy új munkamenet létrejöttéről. Ha egy ügyfél egy meglévő munkamenethez csatlakozik, nincs felsőbb rétegbeli hívás. Az MQTT szempontjából a szolgáltatás akkor küldi el ezt az eseményt, ha 0 CONNACK-csomagot küld az ügyfeleknek.

  • ce-type: azure.webpubsub.sys.connected
  • Content-Type: application/json

A kérelem törzse üres JSON.

Kérelem formátuma

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/client/{clientId}/{physicalConnectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-connectionId: {clientId}
ce-hub: {hub}
ce-eventName: connected
ce-physicalConnectionId: {physicalConnectionId}
ce-sessionId: {sessionId}

{}

Az eseményhez képest az connect connected esemény tartalmaz egy új fejlécet ce-sessionId. Ez egy egyedi azonosító, amelyet a szolgáltatás hoz létre minden munkamenethez. A többi eseménytípus esetében a munkamenet-azonosító fejléce is szerepel.

Válaszformátum

  • 2xx: Sikeres válasz.

Az connected esemény aszinkron. Ha a válasz állapotkódja nem sikerül, a szolgáltatás hibát naplóz.

HTTP/1.1 200 OK

Rendszeresemény disconnected

A szolgáltatás ezzel az eseménysel értesíti a felsőbb réteget arról, hogy egy munkamenet lejárt vagy befejeződött.

  • ce-type: azure.webpubsub.sys.disconnected
  • Content-Type: application/json

Kérelem formátuma

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/client/{clientId}/{physicalConnectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-connectionId: {clientId}
ce-hub: {hub}
ce-eventName: disconnected
ce-physicalConnectionId: {physicalConnectionId}
ce-sessionId: {sessionId}

{
  "reason":"",
  "mqtt":{
    "initiatedByClient": true,
    "disconnectPacket":{
      "code": 0,
      "userProperties": [{ "name": "name1", "value": "value1" }]
    }
  }
}

  • reason: {nullable string of the disconnect reason} Egy emberi olvasásra alkalmas sztring, amely leírja, hogy miért szakadt meg az ügyfél. Ez null értékű lehet, ha ez egy normál kapcsolat bontása. Ha egy munkamenetben több kapcsolat is csatlakozik és megszakad, ez a tulajdonság az utolsó leválasztás oka. Ennek okát az ügyfelek vagy a szolgáltatás adja meg attól függően, hogy ki kezdeményezte a leválasztást. Az MQTT esetében ennek oka az MQTT 5.0-ügyfelektől vagy a szolgáltatástól származó, a DISCONNECT csomagban található oksztring lehet. Az MQTT 3.1.1 protokoll nem tartalmaz oksztringet a DISCONNECT csomagban, ezért az MQTT 3.1.1-ügyfelek ezen tulajdonsága null értékű lehet, vagy a szolgáltatás biztosítja.

  • mqtt.initiatedByClient: Logikai jelző, amely azt jelzi, hogy az ügyfél egy DISCONNECT csomag küldésével kezdeményezi-e a leválasztást. true Amikor az ügyfél egy DISCONNECT csomagot küld a kapcsolat befejezéséhez, ellenkező esetben azfalse.

  • mqtt.disconnectPacket: {nullable object containing properties of the last delivered DISCONNECT packet} Null értékű, ha a kapcsolat megszakad anélkül, hogy az ügyfél vagy a szolgáltatás egy DISCONNECT-csomagot küldene, például IO-hiba vagy hálózati hiba miatt. A felsőbb réteg képes mqtt.initiatedByClient meghatározni, hogy ki küldte a DISCONNECT csomagot.

  • mqtt.disconnectPacket.code: {integer reason code in the DISCONNECT packet} Az MQTT 3.1.1-ügyfelek esetében, mivel a DISCONNECT csomagban nincs okkód, ez a tulajdonság alapértelmezés szerint 0. Az MQTT 5.0 esetében ez az oka az ügyféltől vagy szolgáltatástól küldött DISCONNECT csomag kódjának.

  • mqtt.disconnectPacket.userProperties: {user properties in the DISCONNECT packet} A sztringkulcs-érték párok listája. Az ügyfelek ezen tulajdonság használatával további diagnosztikákat vagy egyéb információkat küldhetnek a felsőbb rétegnek. Ha a SZOLGÁLTATÁS elküldi a DISCONNECT csomagot, az null értékű.

Válaszformátum

  • 2xx: Sikeres válasz.

Az disconnected esemény aszinkron. Ha a válasz állapotkódja nem sikerül, a szolgáltatás hibát naplóz.

HTTP/1.1 200 OK

Felhasználói {custom_event} esemény

A szolgáltatás az MQTT-ügyfelek által közzétett üzeneteket HTTP-kérelmekké alakítja át a felsőbb rétegbeli webhookokra, és a felsőbb rétegből érkező válaszokat üzenetekké alakítja, és elküldi azokat az ügyfeleknek.

Triggerfeltételek

  • Az MQTT-ügyfél egy üzenetet tesz közzé egy témakörben a formátumban $webpubsub/server/events/{eventName}. {eventName} nem tartalmazhatja a karaktert / .
  • Az MQTT-ügyfél jogosult arra, hogy közzétegye az adott témakört.
  • Ha az ügyfél protokollja MQTT 5.0, és a PUBLISH csomag tartalmaz egy tartalomtípus-mezőt, akkor a tartalomtípus értékének érvényes MIME-típusnak kell lennie, mert az egy HTTP-kérés fejlécévé lesz konvertálva Content-Type .

Kérelem formátuma

MQTT-kérelemcsomag

Az alábbi táblázat egy MQTT-kérelemüzenet mezőinek használatát mutatja be.

MQTT-kérelemmezők Használat
Téma Azt jelzi, hogy az üzenet egy felsőbb rétegbe irányuló kérés, és megadja az esemény nevét.
Hasznos adat Legyen a HTTP-kérés törzse.
Tartalomtípus Legyen a HTTP-kérelem tartalomtípus-fejléce.
Korrelációs adatok Legyen a válaszüzenet korrelációs adatmezője, amelyet a feladó használ a válaszüzenet kérésének azonosítására.
QoS Legyen a kérések és a válaszüzenetek kézbesítésének megbízhatósági szintje.
Felhasználói tulajdonságok A HTTP-kérelmekben előtaggal ellátott mqtt- HTTP-fejlécek lesznek. További információt nyújt az ügyfelek és a felsőbb rétegbeli webhookok között.

Az alábbi kódblokk egy JSON formátumú MQTT PUBLISH-csomagot mutat be.

{
  "topic": "$webpubsub/server/events/{eventName}",
  "payload": "{mqtt-request-payload}",
  "content-type": "{request/MIME}",
  "correlation-data": "{correlation-data}",
  "QoS": "{qos}",
  "user-properties": [
    {
      "name": "{request-property-1}",
      "value": "{request-property-value1}"
    }
  ]
}

Az alábbi kódblokk az MQTT PUBLISH csomagból konvertált HTTP-kérést jeleníti meg.

HTTP-kérés
POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: {request/MIME}
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.{eventName}
ce-source: /hubs/{hub}/client/{clientId}/{physicalConnectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-connectionId: {clientId}
ce-hub: {hub}
ce-eventName: {eventName}
ce-physicalConnectionId: {physicalConnectionId}
ce-sessionId: {sessionId}
mqtt-{request-property-1}: {request-property-value1}

{mqtt-request-payload}

Válaszformátum

Az alábbi táblázat a HTTP-válasz különböző mezőinek használatát mutatja be.

HTTP-válaszmező Használat
Tartalomtípus Legyen a válasz MQTT-üzenetének tartalomtípus-mezője.
Törzs Legyen a válasz MQTT-üzenet hasznos adata.
Fejlécek előtaggal mqtt- Legyen felhasználói tulajdonságok a válasz MQTT üzenetében. További információt nyújt az ügyfelek és a felsőbb rétegbeli webhookok között.
Állapotkód Jelzi, hogy a kérés sikeres-e. Ha sikeres (2xx), a válasz témaköre egyébként $webpubsub/server/events/{eventName}/failed.$webpubsub/server/events/{eventName}/succeeded A válasz MQTT üzenetében elnevezett azure-status-code felhasználói tulajdonság is lesz.

Az alábbi kódblokk egy HTTP-mintaválaszt jelenít meg.

HTTP-válasz
HTTP/1.1 200 OK
Host: xxxxxx
Content-Type: {response/MIME}
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=
mqtt-response-property-1: response-property-value1

{mqtt-response-payload}
MQTT-válasz

Az alábbi kódblokk a HTTP-válaszból konvertált MQTT-válaszüzenet mintáját jeleníti meg.

{
  "topic": "$webpubsub/server/events/{eventName}/succeeded",
  "payload": "{mqtt-response-payload}",
  "content-type": "{response/MIME}",
  "correlation-data": "{correlation-data}",
  "QoS": "{qos}",
  "user-properties": [
    {
      "name": "{response-property-1}",
      "value": "{response-property-value1}"
    }
  ]
}

Következő lépések

Használja ezeket az erőforrásokat a saját alkalmazás létrehozásához:

Oktatóanyag: Üzenetek közzététele és feliratkozás az Azure Web PubSubban

Oktatóanyag: Egyszerű csevegőszoba létrehozása az Azure Web PubSub használatával

Oktatóanyag: Szolgáltatás által támogatott alprotocol használata az ügyfélstreameléshez

Oktatóanyag: Kiszolgáló nélküli csevegés létrehozása az Azure Functions és a Web PubSub használatával

Oktatóanyag: Eseményfigyelő konfigurálása

Élő bemutatók lejátszása

További Azure Web PubSub-minták felfedezése