CloudEvents-extensie voor Azure Web PubSub-gebeurtenishandler met HTTP-protocol

Artikel
10/26/2023

De Web PubSub-service levert clientevenementen aan de upstream-webhook met behulp van de HTTP-protocolbinding van CloudEvents.

De gegevens die vanuit de Web PubSub-service naar de server worden verzonden, hebben altijd de indeling CloudEvents binary .

Webhookvalidatie
Kenmerkextensie Web PubSub CloudEvents
Gebeurtenissen
- Gebeurtenissen blokkeren
  - Systeem connect gebeurtenis
  - Gebruikersevenementen
- Blokkering van gebeurtenissen opheffen
  - Systeem connected gebeurtenis
  - Systeem disconnected gebeurtenis

Webhookvalidatie

De webhookvalidatie volgt CloudEvents. De aanvraag bevat WebHook-Request-Origin: xxx.webpubsub.azure.com altijd in de header.

Als en alleen als het leveringsdoel de levering van de gebeurtenissen toestaat, MOET deze reageren op de aanvraag door WebHook-Allowed-Origin bijvoorbeeld header op te geven:

WebHook-Allowed-Origin: *

Of:

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

Voorlopig worden WebHook-Request-Rate en WebHook-Request-Callback niet ondersteund.

Kenmerkextensie Web PubSub CloudEvents

Er is ook opgemerkt dat de HTTP-specificatie nu een vergelijkbaar patroon volgt door niet langer aan te geven dat extensie-HTTP-headers worden voorafgegaan door X-.

Deze extensie definieert kenmerken die door Web PubSub worden gebruikt voor elke gebeurtenis die wordt geproduceerd.

Kenmerken

Name	Type	Description
`userId`	`string`	De gebruiker die de verbinding heeft geverifieerd
`hub`	`string`	De hub waartoe de verbinding behoort
`connectionId`	`string`	De connectionId is uniek voor de clientverbinding
`eventName`	`string`	De naam van de gebeurtenis zonder voorvoegsel
`subprotocol`	`string`	Het subprotocol dat de client gebruikt, indien van toepassing
`connectionState`	`string`	Hiermee definieert u de status voor de verbinding. U kunt dezelfde antwoordheader gebruiken om de waarde van de status opnieuw in te stellen. Meerdere `connectionState` headers zijn niet toegestaan. Codeer de tekenreekswaarde met base64 als deze complexe tekens bevat, `base64(jsonString)` bijvoorbeeld om een complex object door te geven met behulp van dit kenmerk.
`signature`	`string`	De handtekening voor de upstream-webhook om te valideren of de binnenkomende aanvraag afkomstig is van de verwachte oorsprong. De service berekent de waarde met zowel de primaire toegangssleutel als de secundaire toegangssleutel als de `HMAC` sleutel: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))` De upstream moet controleren of de aanvraag geldig is voordat deze wordt verwerkt.

gebeurtenis

Er zijn twee soorten gebeurtenissen. Een is het blokkeren van gebeurtenissen die de service wacht tot het antwoord van de gebeurtenis wordt voortgezet. Een is het deblokkeren van gebeurtenissen die de service niet wacht op het antwoord van een dergelijke gebeurtenis voordat het volgende bericht wordt verwerkt.

Gebeurtenissen blokkeren
- Systeem connect gebeurtenis
- Gebruikersevenementen
Blokkering van gebeurtenissen opheffen
- Systeem connected gebeurtenis
- Systeem disconnected gebeurtenis

Systeem `connect` gebeurtenis

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

Aanvraagindeling:

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-----"
        }
    ]
}

Geslaagde antwoordindeling:

Header ce-connectionState: Als deze header bestaat, wordt de verbindingsstatus van deze verbinding bijgewerkt naar de waarde van de header. Alleen blokkerende gebeurtenissen kunnen de verbindingsstatus bijwerken. In het onderstaande voorbeeld wordt een met base64 gecodeerde JSON-tekenreeks gebruikt om de complexe status voor de verbinding op te slaan.
Statuscode:
- 204: Geslaagd, zonder inhoud.
- 200: Geslaagd, de inhoud moet een JSON-indeling zijn, waarbij de volgende eigenschappen zijn toegestaan:
  - subprotocols
    
    De connect gebeurtenis stuurt het subprotocol en de verificatiegegevens door naar Upstream vanaf de client. De Web PubSub-service gebruikt de statuscode om te bepalen of de aanvraag wordt bijgewerkt naar het WebSocket-protocol.
    
    Als de aanvraag de subprotocols eigenschap bevat, moet de server één subprotocol retourneren dat wordt ondersteund. Als de server geen subprotocollen wil gebruiken, mag deze de subprotocol eigenschap niet als antwoord verzenden. Het verzenden van een lege koptekst is ongeldig.
  - userId: {auth-ed user ID}
    
    Omdat de service anonieme verbindingen toestaat, is het de verantwoordelijkheid van de connect gebeurtenis om de service de gebruikers-id van de clientverbinding te vertellen. De service leest de gebruikers-id van de nettolading userId van het antwoord als deze bestaat. De verbinding wordt verbroken als de gebruikers-id niet kan worden gelezen uit de aanvraagclaims of de nettolading van de reactie van de connect gebeurtenis.
  - groups: {groups to join}
    
    De eigenschap biedt een handige manier voor de gebruiker om deze verbinding toe te voegen aan een of meer groepen. Op deze manier hoeft u geen andere aanroep te hebben om deze verbinding aan een bepaalde groep toe te voegen.
  - roles: {roles the client has}
    
    De eigenschap biedt een manier voor de upstream Webhook om de client te autoriseren. Er zijn verschillende rollen voor het verlenen van initiële machtigingen voor PubSub WebSocket-clients. Details over de machtigingen worden beschreven in clientmachtigingen.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

Foutreactie-indeling:

4xx: Fout: het antwoord van Upstream wordt geretourneerd als het antwoord voor de clientaanvraag.

HTTP/1.1 401 Unauthorized

Systeem `connected` gebeurtenis

De service roept de Upstream aan wanneer de client websocket handshake voltooit en is verbonden.

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

Aanvraagbody is lege JSON.

Aanvraagindeling:

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=

{}

Antwoordindeling:

2xx: geslaagd antwoord.

connected is een asynchrone gebeurtenis, wanneer de antwoordstatuscode niet is geslaagd, registreert de service een fout.

HTTP/1.1 200 OK

Systeem `disconnected` gebeurtenis

disconnected gebeurtenis wordt altijd geactiveerd wanneer de clientaanvraag is voltooid als de verbindingsgebeurtenis statuscode retourneert 2xx .

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

Aanvraagindeling:

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

De reason beschrijving van de reden waarom de client de verbinding verbreekt.

Antwoordindeling:

2xx: geslaagd antwoord.

disconnected is een asynchrone gebeurtenis, wanneer de antwoordstatuscode niet is geslaagd, registreert de service een fout.

HTTP/1.1 200 OK

Gebruikers gebeurtenis `message` voor de eenvoudige WebSocket-clients

De service roept de gebeurtenis-handler upstream aan voor elk WebSocket-berichtframe.

ce-type: azure.webpubsub.user.message
Content-Type: application/octet-stream voor binair frame; text/plain voor tekstframe;

UserPayload is wat de client verzendt.

Aanvraagindeling:

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

Geslaagde antwoordindeling

Statuscode
- 204: Geslaagd, zonder inhoud.
- 200: Geslaagd, de indeling van de UserResponsePayload is afhankelijk van het Content-Type antwoord.
Content-Type: application/octet-stream voor binair frame; text/plain voor tekstframe;
Koptekst Content-Type: application/octet-stream voor binair frame; text/plain voor tekstframe;
Header ce-connectionState: Als deze header bestaat, wordt de verbindingsstatus van deze verbinding bijgewerkt naar de waarde van de header. Alleen blokkerende gebeurtenissen kunnen de verbindingsstatus bijwerken. In het onderstaande voorbeeld wordt een met base64 gecodeerde JSON-tekenreeks gebruikt om complexe status voor de verbinding op te slaan.

Wanneer dit het Content-Type is, verzendt UserResponsePayload de service naar de client met behulp van binary WebSocket application/octet-streamFrame. Wanneer dit het Content-Type is, verzendt UserResponsePayload de service naar de client met behulp van text WebSocket text/plainFrame.

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

Foutreactie-indeling

Wanneer de statuscode niet is geslaagd, wordt deze beschouwd als een foutreactie. De verbinding wordt verbroken als de message antwoordstatuscode niet is geslaagd.

Aangepaste gebeurtenis `{custom_event}` van gebruiker voor PubSub WebSocket-clients

De service roept de webhook van de gebeurtenishandler aan voor elk geldig aangepast gebeurtenisbericht.

Case 1: gebeurtenis met tekstgegevens verzenden:

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

Wat de upstream-gebeurtenis-handler hieronder ontvangt, is text/plain de Content-Type http-aanvraag voor CloudEvents voordataType=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

Case 2: gebeurtenis verzenden met JSON-gegevens:

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

Wat de upstream-gebeurtenis-handler hieronder ontvangt, is application/json de Content-Type http-aanvraag voor CloudEvents voordataType=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"
}

Case 3: gebeurtenis verzenden met binaire gegevens:

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

Wat de upstream-gebeurtenis-handler hieronder ontvangt, is application/octet-stream de Content-Type http-aanvraag voor CloudEvents voordataType=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>

Geslaagde antwoordindeling

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

UserResponsePayload

Statuscode
- 204: Geslaagd, zonder inhoud.
- 200: Succes, gegevens die naar de PubSub WebSocket-client worden verzonden, zijn afhankelijk van de Content-Type;
Header ce-connectionState: Als deze header bestaat, wordt de verbindingsstatus van deze verbinding bijgewerkt naar de waarde van de header. Alleen blokkerende gebeurtenissen kunnen de verbindingsstatus bijwerken. In het onderstaande voorbeeld wordt een met base64 gecodeerde JSON-tekenreeks gebruikt om de complexe status voor de verbinding op te slaan.
Wanneer header Content-Type isapplication/octet-stream, stuurt UserResponsePayload de service terug naar de client met behulp binary van dataType nettolading base64 gecodeerd. Een voorbeeldantwoord:
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Wanneer dit het Content-Type is, verzendt UserResponsePayload de service naar de client met behulp van dataType een text nettoladingtekenreekstext/plain.
Wanneer dit het Content-Type is, verzendt UserResponsePayload de service naar de client met behulp van=dataTypejson een data waardetoken als hoofdtekst van de nettolading application/jsonvan het antwoord.

Foutreactie-indeling

Wanneer de statuscode niet is geslaagd, wordt deze beschouwd als een foutreactie. De verbinding wordt verbroken als de {custom_event} antwoordstatuscode niet is geslaagd.

Volgende stappen

Gebruik deze resources om te beginnen met het bouwen van uw eigen toepassing:

Zelfstudie: Berichten publiceren en abonneren op berichten in Azure Web PubSub

Zelfstudie: Een eenvoudige chatroom maken met Azure Web PubSub

Zelfstudie: Een door de service ondersteund subprotocol gebruiken voor clientstreaming

Zelfstudie: Serverloze chat bouwen met Azure Functions en Web PubSub

Zelfstudie: Een gebeurtenislistener configureren

Spelen met live demo's

Meer Voorbeelden van Azure Web PubSub verkennen

Delen via

CloudEvents-extensie voor Azure Web PubSub-gebeurtenishandler met HTTP-protocol

Webhookvalidatie

Kenmerkextensie Web PubSub CloudEvents

Kenmerken

gebeurtenis

Systeem `connect` gebeurtenis

Aanvraagindeling:

Geslaagde antwoordindeling:

Foutreactie-indeling:

Systeem `connected` gebeurtenis

Aanvraagindeling:

Antwoordindeling:

Systeem `disconnected` gebeurtenis

Aanvraagindeling:

Antwoordindeling:

Gebruikers gebeurtenis `message` voor de eenvoudige WebSocket-clients

Aanvraagindeling:

Geslaagde antwoordindeling

Foutreactie-indeling

Aangepaste gebeurtenis `{custom_event}` van gebruiker voor PubSub WebSocket-clients

Case 1: gebeurtenis met tekstgegevens verzenden:

Case 2: gebeurtenis verzenden met JSON-gegevens:

Case 3: gebeurtenis verzenden met binaire gegevens:

Geslaagde antwoordindeling

Foutreactie-indeling

Volgende stappen

Feedback

Aanvullende resources

Delen via

CloudEvents-extensie voor Azure Web PubSub-gebeurtenishandler met HTTP-protocol

Webhookvalidatie

Kenmerkextensie Web PubSub CloudEvents

Kenmerken

gebeurtenis

Systeem connect gebeurtenis

Aanvraagindeling:

Geslaagde antwoordindeling:

Foutreactie-indeling:

Systeem connected gebeurtenis

Aanvraagindeling:

Antwoordindeling:

Systeem disconnected gebeurtenis

Aanvraagindeling:

Antwoordindeling:

Gebruikers gebeurtenis message voor de eenvoudige WebSocket-clients

Aanvraagindeling:

Geslaagde antwoordindeling

Foutreactie-indeling

Aangepaste gebeurtenis {custom_event} van gebruiker voor PubSub WebSocket-clients

Case 1: gebeurtenis met tekstgegevens verzenden:

Case 2: gebeurtenis verzenden met JSON-gegevens:

Case 3: gebeurtenis verzenden met binaire gegevens:

Geslaagde antwoordindeling

Foutreactie-indeling

Volgende stappen

Feedback

Aanvullende resources

Systeem `connect` gebeurtenis

Systeem `connected` gebeurtenis

Systeem `disconnected` gebeurtenis

Gebruikers gebeurtenis `message` voor de eenvoudige WebSocket-clients

Aangepaste gebeurtenis `{custom_event}` van gebruiker voor PubSub WebSocket-clients