CloudEvents-tillägg för Azure Web PubSub-händelsehanterare med HTTP-protokoll

Web PubSub-tjänsten levererar klienthändelser till den överordnade webhooken med hjälp av HTTP-protokollbindningen CloudEvents.

Data som skickas från Web PubSub-tjänsten till servern är alltid i CloudEvents-format binary .

• Webhook-validering
• Attributtillägget Web PubSub CloudEvents
• Händelser
  • Blockera händelser
    • Systemhändelse connect
    • Användarhändelser
  • Avblockera händelser
    • Systemhändelse connected
    • Systemhändelse disconnected

Webhook-validering

Webhook-valideringen följer CloudEvents. Begäran innehåller WebHook-Request-Origin: xxx.webpubsub.azure.com alltid i rubriken.

Om och endast om leveransmålet tillåter leverans av händelserna måste det svara på begäran genom att inkludera WebHook-Allowed-Origin huvudet, till exempel:

WebHook-Allowed-Origin: *

Eller:

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

För tillfället stöds inte WebHook-Request-Rate och WebHook-Request-Callback .

Web PubSub CloudEvents-attributtillägg

Det noterades också att HTTP-specifikationen nu följer ett liknande mönster genom att inte längre föreslå att tilläggets HTTP-huvuden ska prefixeras med X-.

Det här tillägget definierar attribut som används av Web PubSub för varje händelse som skapas.

Attribut

Namn	Type	Beskrivning	Exempel
userId	string	Användaren som anslutningen autentiseras
hub	string	Hubben som anslutningen tillhör
connectionId	string	ConnectionId är unikt för klientanslutningen
eventName	string	Namnet på händelsen utan prefix
subprotocol	string	Den delprotokol som klienten använder om någon
connectionState	string	Definierar tillståndet för anslutningen. Du kan använda samma svarshuvud för att återställa värdet för tillståndet. Flera connectionState rubriker tillåts inte. Do base64 encode the string value if it contains complex characters inside, for example, base64(jsonString) to pass complex object using this attribute.
signature	string	Signaturen för den överordnade webhooken för att verifiera om den inkommande begäran kommer från det förväntade ursprunget. Tjänsten beräknar värdet med både primär åtkomstnyckel och sekundär åtkomstnyckel som HMAC nyckel: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). Uppströms bör kontrollera om begäran är giltig innan den bearbetas.

Händelser

Det finns två typer av händelser. Den ena blockerar händelser som tjänsten väntar på att svaret på händelsen ska fortsätta. Det ena är att avblockera händelser som tjänsten inte väntar på svaret på en sådan händelse innan nästa meddelande bearbetas.

• Blockera händelser
  • Systemhändelse connect
  • Användarhändelser
• Avblockera händelser
  • Systemhändelse connected
  • Systemhändelse disconnected

Systemhändelse connect

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

Format för begäran:

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/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

Svarsformat för lyckad åtgärd:

• Rubrik ce-connectionState: Om det här huvudet finns uppdateras anslutningstillståndet för den här anslutningen till värdet för huvudet. Endast blockerande händelser kan uppdatera anslutningstillståndet. Exemplet nedan använder base64-kodad JSON-sträng för att lagra det komplexa tillståndet för anslutningen.

• Statuskod:

  • 204: Lyckades, utan innehåll.
  • 200: Lyckades, innehållet SKA vara ett JSON-format med följande egenskaper tillåtna:

    • subprotocols

      Händelsen connect vidarebefordrar delprotokol- och autentiseringsinformationen till Uppströms från klienten. Web PubSub-tjänsten använder statuskoden för att avgöra om begäran kommer att uppgraderas till WebSocket-protokollet.

      Om begäran innehåller subprotocols egenskapen ska servern returnera en delprotokol som den stöder. Om servern inte vill använda några underprotokoler bör den subprotocol inte skicka egenskapen som svar. Det är ogiltigt att skicka ett tomt sidhuvud.

    • userId: {auth-ed user ID}

      Eftersom tjänsten tillåter anonyma anslutningar är connect det händelsens ansvar att meddela tjänsten användar-ID för klientanslutningen. Tjänsten läser användar-ID:t från svarsnyttolasten userId om det finns. Anslutningen tas bort om användar-ID:t inte kan läsas från begärandeanspråken connect eller händelsens svarsnyttolast.

    • groups: {groups to join}

      Egenskapen är ett bekvämt sätt för användaren att lägga till den här anslutningen i en eller flera grupper. På så sätt behöver du inte ha ett nytt anrop för att lägga till den här anslutningen i någon grupp.

    • roles: {roles the client has}

      Egenskapen är ett sätt för den överordnade Webhook att auktorisera klienten. Det finns olika roller för att bevilja inledande behörigheter för PubSub WebSocket-klienter. Information om behörigheterna beskrivs i Klientbehörigheter.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

Felsvarsformat:

• 4xx: Felet är att svaret från Upstream returneras som svar på klientbegäran.

HTTP/1.1 401 Unauthorized

Systemhändelse connected

Tjänsten anropar Upstream när klienten slutför WebSocket-handskakningen och är ansluten.

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

Begärandetexten är tom JSON.

Format för begäran:

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/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

Svarsformat:

2xx: lyckat svar.

connected är en asynkron händelse, när svarsstatuskoden inte lyckas loggar tjänsten ett fel.

HTTP/1.1 200 OK

Systemhändelse disconnected

disconnectedhändelsen utlöses alltid när klientbegäran slutförs om anslutningshändelsen returnerar 2xx statuskoden.

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

Format för begäran:

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/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

• reason

  Beskriver reason orsaken till att klienten kopplas från.

Svarsformat:

2xx: lyckat svar.

disconnected är en asynkron händelse, när svarsstatuskoden inte lyckas loggar tjänsten ett fel.

HTTP/1.1 200 OK

Användarhändelse message för enkla WebSocket-klienter

Tjänsten anropar händelsehanteraren uppströms för varje WebSocket-meddelanderam.

• ce-type: azure.webpubsub.user.message
• Content-Type: application/octet-stream för binär ram; text/plain för textram;

UserPayload är vad klienten skickar.

Format för begäran:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

Svarsformat för lyckad åtgärd

• Statuskod
  • 204: Lyckades, utan innehåll.
  • 200: Om det lyckas beror formatet UserResponsePayload på Content-Type svaret.
• Content-Type: application/octet-stream för binär ram; text/plain för textram;
• Rubrik Content-Type: application/octet-stream för binär ram; text/plain för textram;
• Rubrik ce-connectionState: Om det här huvudet finns uppdateras anslutningstillståndet för den här anslutningen till värdet för huvudet. Endast blockerande händelser kan uppdatera anslutningstillståndet. Exemplet nedan använder base64-kodad JSON-sträng för att lagra komplext tillstånd för anslutningen.

Content-Type När är application/octet-streamskickar UserResponsePayload tjänsten till klienten med hjälp av binary WebSocket-ramen. Content-Type När är text/plainskickar UserResponsePayload tjänsten till klienten med hjälp av text WebSocket-ramen.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

Felsvarsformat

När statuskoden inte lyckas anses den vara ett felsvar. Anslutningen skulle tas bort om message svarsstatuskoden inte lyckas.

Användaranpassad händelse {custom_event} för PubSub WebSocket-klienter

Tjänsten anropar händelsehanterarwebbhooken för varje giltigt anpassat händelsemeddelande.

Fall 1: Skicka händelse med textdata:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "text",
    "data": "text data"
}

Vad den överordnade händelsehanteraren tar emot som nedan Content-Type gäller text/plain http-begäran för CloudEvents för dataType=text

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: text/plain
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

Fall 2: Skicka händelse med JSON-data:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    },
}

Vad den överordnade händelsehanteraren tar emot som nedan Content-Type gäller application/json http-begäran för CloudEvents för dataType=json

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

Fall 3: Skicka händelse med binära data:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Vad den överordnade händelsehanteraren tar emot som nedan Content-Type gäller application/octet-stream http-begäran för CloudEvents för dataType=binary

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.<event_name>
ce-source: /client/{connectionId}
ce-id: {eventId}
ce-time: 2021-01-01T00:00:00Z
ce-signature: sha256={connection-id-hash-primary},sha256={connection-id-hash-secondary}
ce-userId: {userId}
ce-connectionId: {connectionId}
ce-hub: {hub_name}
ce-eventName: <event_name>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

Svarsformat för lyckad åtgärd

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload

• Statuskod
  • 204: Lyckades, utan innehåll.
  • 200: Lyckades, data som skickas till PubSub WebSocket-klienten beror på Content-Type;
• Rubrik ce-connectionState: Om det här huvudet finns uppdateras anslutningstillståndet för den här anslutningen till värdet för huvudet. Endast blockerande händelser kan uppdatera anslutningstillståndet. Exemplet nedan använder base64-kodad JSON-sträng för att lagra det komplexa tillståndet för anslutningen.
• När Huvudet Content-Type är application/octet-streamskickar UserResponsePayload tjänsten tillbaka till klienten med hjälp av dataType som binary med nyttolasten base64 kodad. Ett exempelsvar:

  {
      "type": "message",
      "from": "server",
      "dataType": "binary",
      "data" : "aGVsbG8gd29ybGQ="
  }
  

• Content-Type När är text/plainskickar UserResponsePayload tjänsten till klienten med hjälp av dataType som text med nyttolaststräng.
• Content-Type När är application/jsonskickar UserResponsePayload tjänsten till klienten med värdetokenjson dataType=data som svarsnyttolasttext.

Felsvarsformat

När statuskoden inte lyckas anses den vara ett felsvar. Anslutningen skulle tas bort om {custom_event} svarsstatuskoden inte lyckas.

Nästa steg

Använd dessa resurser för att börja skapa ett eget program:

Självstudie: Publicera och prenumerera på meddelanden i Azure Web PubSub

Självstudie: Skapa ett enkelt chattrum med Azure Web PubSub

Självstudie: Använda en underprotokol som stöds av tjänsten för klientströmning

Självstudie: Skapa serverlös chatt med Azure Functions och Web PubSub

Självstudie: Konfigurera en händelselyssnare

Spela upp med livedemonstrationer

Utforska fler Azure Web PubSub-exempel