Rozszerzenie CloudEvents dla programu obsługi zdarzeń usługi Azure Web PubSub z protokołem HTTP

Artykuł
03/13/2024

Usługa Web PubSub dostarcza zdarzenia klienta do nadrzędnego elementu webhook przy użyciu powiązania protokołu HTTP CloudEvents.

Dane wysyłane z usługi Web PubSub do serwera są zawsze w formacie CloudEvents binary .

Walidacja elementu webhook
Rozszerzenie atrybutu Web PubSub CloudEvents
Wydarzenia
- Blokowanie zdarzeń
  - Zdarzenie systemowe connect
  - Zdarzenia użytkownika
- Odblokowywanie zdarzeń
  - Zdarzenie systemowe connected
  - Zdarzenie systemowe disconnected

Walidacja elementu webhook

Walidacja elementu webhook jest zgodna z usługą CloudEvents. Żądanie zawsze znajduje się WebHook-Request-Origin: xxx.webpubsub.azure.com w nagłówku.

Jeśli i tylko wtedy, gdy element docelowy dostarczania zezwala na dostarczanie zdarzeń, MUSI odpowiedzieć na żądanie, dołączając WebHook-Allowed-Origin nagłówek, na przykład:

WebHook-Allowed-Origin: *

Lub:

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

Na razie element WebHook-Request-Rate i element WebHook-Request-Callback nie są obsługiwane.

Rozszerzenie atrybutu Web PubSub CloudEvents

Zauważono również, że specyfikacja HTTP jest teraz podąża za podobnym wzorcem, nie sugerując już, aby nagłówki HTTP rozszerzenia były poprzedzone prefiksem X-.

To rozszerzenie definiuje atrybuty używane przez usługę Web PubSub dla każdego generowanego zdarzenia.

Atrybuty

Nazwisko	Pisz	Opis
`userId`	`string`	Użytkownik, z uwierzytelnianiem połączenia
`hub`	`string`	Koncentrator, do którego należy połączenie
`connectionId`	`string`	Identyfikator connectionId jest unikatowy dla połączenia klienta
`eventName`	`string`	Nazwa zdarzenia bez prefiksu
`subprotocol`	`string`	Podprotocol klienta jest używany, jeśli istnieje
`connectionState`	`string`	Definiuje stan połączenia. Możesz użyć tego samego nagłówka odpowiedzi, aby zresetować wartość stanu. Wiele `connectionState` nagłówków nie jest dozwolonych. Czy base64 koduje wartość ciągu, jeśli zawiera znaki złożone wewnątrz, na przykład, `base64(jsonString)` aby przekazać obiekt złożony przy użyciu tego atrybutu.
`signature`	`string`	Podpis nadrzędnego elementu webhook w celu sprawdzenia, czy żądanie przychodzące pochodzi z oczekiwanego źródła. Usługa oblicza wartość przy użyciu zarówno podstawowego klucza dostępu, jak i pomocniczego `HMAC` klucza dostępu jako klucza: `Hex_encoded(HMAC_SHA256(accessKey, connectionId))`. Nadrzędny element powinien sprawdzić, czy żądanie jest prawidłowe przed jego przetworzeniem.

Zdarzenia

Istnieją dwa typy zdarzeń. Jednym z nich jest blokowanie zdarzeń, które usługa czeka na kontynuowanie odpowiedzi zdarzenia. Jednym z nich jest odblokowanie zdarzeń, które usługa nie czeka na odpowiedź takiego zdarzenia przed przetworzeniem następnego komunikatu.

Blokowanie zdarzeń
- Zdarzenie systemowe connect
- Zdarzenia użytkownika
Odblokowywanie zdarzeń
- Zdarzenie systemowe connected
- Zdarzenie systemowe disconnected

Zdarzenie systemowe `connect`

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

Format żądania:

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

Format odpowiedzi powodzenia:

Nagłówek : jeśli ten nagłówek ce-connectionStateistnieje, stan połączenia tego połączenia zostanie zaktualizowany do wartości nagłówka. Tylko zdarzenia blokujące mogą aktualizować stan połączenia. Poniższy przykład używa parametrów JSON zakodowanych w formacie base64 do przechowywania stanu złożonego dla połączenia.
Kod stanu:
- 204: Powodzenie, bez zawartości.
- 200: Powodzenie, zawartość POWINNA być formatem JSON z następującymi właściwościami dozwolonymi:
  - subprotocols
    
    Zdarzenie connect przekazuje informacje dotyczące podprotocol i uwierzytelniania do nadrzędnego strumienia z klienta. Usługa Web PubSub używa kodu stanu, aby określić, czy żądanie zostanie uaktualnione do protokołu WebSocket.
    
    Jeśli żądanie zawiera subprotocols właściwość, serwer powinien zwrócić jeden podprotocol, który obsługuje. Jeśli serwer nie chce używać żadnych podprotocols, nie powinien wysyłać subprotocol właściwości w odpowiedzi. Wysyłanie pustego nagłówka jest nieprawidłowe.
  - userId: {auth-ed user ID}
    
    Ponieważ usługa zezwala na połączenia anonimowe, to zdarzenie odpowiada connect za przekazywanie usłudze identyfikatora użytkownika połączenia klienta. Usługa odczytuje identyfikator użytkownika z ładunku userId odpowiedzi, jeśli istnieje. Połączenie zostanie porzucone, jeśli identyfikator użytkownika nie może zostać odczytany z oświadczeń żądania ani connect ładunku odpowiedzi zdarzenia.
  - groups: {groups to join}
    
    Właściwość zapewnia wygodny sposób dodawania tego połączenia do jednej lub wielu grup przez użytkownika. W ten sposób nie trzeba mieć innego wywołania, aby dodać to połączenie do jakiejś grupy.
  - roles: {roles the client has}
    
    Właściwość zapewnia sposób autoryzowania klienta przez nadrzędny element webhook. Istnieją różne role, które umożliwiają udzielanie początkowych uprawnień klientom PubSub WebSocket. Szczegółowe informacje o uprawnieniach zostały opisane w temacie Uprawnienia klienta.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

Format odpowiedzi błędu:

4xx: Błąd, odpowiedź z nadrzędnego strumienia zostanie zwrócona jako odpowiedź dla żądania klienta.

HTTP/1.1 401 Unauthorized

Zdarzenie systemowe `connected`

Usługa wywołuje element nadrzędny, gdy klient ukończy uzgadnianie protokołu WebSocket i zostanie pomyślnie nawiązane połączenie.

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

Treść żądania jest pusta w formacie JSON.

Format żądania:

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=

{}

Format odpowiedzi:

2xx: odpowiedź na powodzenie.

connected jest zdarzeniem asynchronicznym, gdy kod stanu odpowiedzi nie zostanie pomyślnie wyświetlony, usługa rejestruje błąd.

HTTP/1.1 200 OK

Zdarzenie systemowe `disconnected`

disconnected zdarzenie jest zawsze wyzwalane po zakończeniu żądania klienta, jeśli zdarzenie connect zwraca 2xx kod stanu.

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

Format żądania:

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

Opisuje reason przyczynę rozłączenia klienta.

Format odpowiedzi:

2xx: odpowiedź na powodzenie.

disconnected jest zdarzeniem asynchronicznym, gdy kod stanu odpowiedzi nie zostanie pomyślnie wyświetlony, usługa rejestruje błąd.

HTTP/1.1 200 OK

Zdarzenie `message` użytkownika dla prostych klientów protokołu WebSocket

Usługa wywołuje nadrzędną procedurę obsługi zdarzeń dla każdej ramki komunikatów protokołu WebSocket.

ce-type: azure.webpubsub.user.message
Content-Type: application/octet-stream dla ramki binarnej; text/plain dla ramki tekstowej;

UserPayload jest tym, co wysyła klient.

Format żądania:

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

Format odpowiedzi powodzenia

Kod stanu
- 204: Powodzenie, bez zawartości.
- 200: Powodzenie, format UserResponsePayload odpowiedzi zależy od Content-Type .
Content-Type: application/octet-stream dla ramki binarnej; text/plain dla ramki tekstowej;
Nagłówek Content-Type: application/octet-stream dla ramki binarnej; text/plain dla ramki tekstowej;
Nagłówek : jeśli ten nagłówek ce-connectionStateistnieje, stan połączenia tego połączenia zostanie zaktualizowany do wartości nagłówka. Tylko zdarzenia blokujące mogą aktualizować stan połączenia. Poniższy przykład używa parametrów JSON zakodowanych w formacie base64 do przechowywania złożonego stanu połączenia.

Content-Type Gdy parametr ma application/octet-streamwartość , usługa wysyła UserResponsePayload do klienta przy użyciu binary ramki Protokołu WebSocket. Content-Type Gdy parametr ma text/plainwartość , usługa wysyła UserResponsePayload do klienta przy użyciu text ramki Protokołu WebSocket.

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

Format odpowiedzi na błędy

Jeśli kod stanu nie jest pomyślny, jest uważany za odpowiedź na błąd. Połączenie zostanie porzucone , jeśli kod stanu odpowiedzi nie zakończy się powodzeniem message .

Zdarzenie `{custom_event}` niestandardowe użytkownika dla klientów Protokołu WebSocket usługi PubSub

Usługa wywołuje element webhook procedury obsługi zdarzeń dla każdego prawidłowego niestandardowego komunikatu zdarzenia.

Przypadek 1: wysyłanie zdarzenia z danymi tekstowymi:

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

Jaka procedura obsługi zdarzeń nadrzędnych jest odbierana w następujący sposób, Content-Type dla żądania HTTP CloudEvents jest text/plain dla 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

Przypadek 2: wysyłanie zdarzenia z danymi JSON:

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

Jaka procedura obsługi zdarzeń nadrzędnych jest odbierana w następujący sposób, Content-Type dla żądania HTTP CloudEvents jest application/json dla 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"
}

Przypadek 3: wysyłanie zdarzenia z danymi binarnymi:

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

Jaka procedura obsługi zdarzeń nadrzędnych jest odbierana w następujący sposób, Content-Type dla żądania HTTP CloudEvents jest application/octet-stream dla 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>

Format odpowiedzi powodzenia

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

UserResponsePayload

Kod stanu
- 204: Powodzenie, bez zawartości.
- 200: Powodzenie, dane wysyłane do klienta PubSub WebSocket zależą od Content-Type;
Nagłówek : jeśli ten nagłówek ce-connectionStateistnieje, stan połączenia tego połączenia zostanie zaktualizowany do wartości nagłówka. Tylko zdarzenia blokujące mogą aktualizować stan połączenia. Poniższy przykład używa parametrów JSON zakodowanych w formacie base64 do przechowywania stanu złożonego dla połączenia.
Gdy nagłówek Content-Type to application/octet-stream, usługa wysyła z UserResponsePayload powrotem do klienta przy użyciu polecenia dataType z binary ładunkiem base64 zakodowanym. Przykładowa odpowiedź:
```
{
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
```
Gdy parametr Content-Type ma text/plainwartość , usługa wysyła UserResponsePayload do klienta przy użyciu polecenia dataType as text z ciągiem ładunku.
Gdy Content-Type parametr to application/json, usługa wysyła UserResponsePayload do klienta przy użyciujson dataType=data tokenu wartości jako treść ładunku odpowiedzi.

Format odpowiedzi na błędy

Jeśli kod stanu nie jest pomyślny, jest uważany za odpowiedź na błąd. Połączenie zostanie porzucone , jeśli kod stanu odpowiedzi nie zakończy się powodzeniem {custom_event} .

Następne kroki

Użyj tych zasobów, aby rozpocząć tworzenie własnej aplikacji:

Samouczek: publikowanie i subskrybowanie komunikatów w usłudze Azure Web PubSub

Samouczek: tworzenie prostego czatroomu za pomocą usługi Azure Web PubSub

Samouczek: używanie podprotokolu obsługiwanego przez usługę na potrzeby przesyłania strumieniowego klienta

Samouczek: tworzenie czatu bezserwerowego za pomocą usług Azure Functions i Web PubSub

Samouczek: konfigurowanie odbiornika zdarzeń

Odtwarzanie z pokazami na żywo

Zapoznaj się z więcej przykładów usługi Azure Web PubSub

Udostępnij za pośrednictwem

Rozszerzenie CloudEvents dla programu obsługi zdarzeń usługi Azure Web PubSub z protokołem HTTP

Walidacja elementu webhook

Rozszerzenie atrybutu Web PubSub CloudEvents

Atrybuty

Zdarzenia

Zdarzenie systemowe `connect`

Format żądania:

Format odpowiedzi powodzenia:

Format odpowiedzi błędu:

Zdarzenie systemowe `connected`

Format żądania:

Format odpowiedzi:

Zdarzenie systemowe `disconnected`

Format żądania:

Format odpowiedzi:

Zdarzenie `message` użytkownika dla prostych klientów protokołu WebSocket

Format żądania:

Format odpowiedzi powodzenia

Format odpowiedzi na błędy

Zdarzenie `{custom_event}` niestandardowe użytkownika dla klientów Protokołu WebSocket usługi PubSub

Przypadek 1: wysyłanie zdarzenia z danymi tekstowymi:

Przypadek 2: wysyłanie zdarzenia z danymi JSON:

Przypadek 3: wysyłanie zdarzenia z danymi binarnymi:

Format odpowiedzi powodzenia

Format odpowiedzi na błędy

Następne kroki

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Rozszerzenie CloudEvents dla programu obsługi zdarzeń usługi Azure Web PubSub z protokołem HTTP

Walidacja elementu webhook

Rozszerzenie atrybutu Web PubSub CloudEvents

Atrybuty

Zdarzenia

Zdarzenie systemowe connect

Format żądania:

Format odpowiedzi powodzenia:

Format odpowiedzi błędu:

Zdarzenie systemowe connected

Format żądania:

Format odpowiedzi:

Zdarzenie systemowe disconnected

Format żądania:

Format odpowiedzi:

Zdarzenie message użytkownika dla prostych klientów protokołu WebSocket

Format żądania:

Format odpowiedzi powodzenia

Format odpowiedzi na błędy

Zdarzenie {custom_event} niestandardowe użytkownika dla klientów Protokołu WebSocket usługi PubSub

Przypadek 1: wysyłanie zdarzenia z danymi tekstowymi:

Przypadek 2: wysyłanie zdarzenia z danymi JSON:

Przypadek 3: wysyłanie zdarzenia z danymi binarnymi:

Format odpowiedzi powodzenia

Format odpowiedzi na błędy

Następne kroki

Opinia

Dodatkowe zasoby

Zdarzenie systemowe `connect`

Zdarzenie systemowe `connected`

Zdarzenie systemowe `disconnected`

Zdarzenie `message` użytkownika dla prostych klientów protokołu WebSocket

Zdarzenie `{custom_event}` niestandardowe użytkownika dla klientów Protokołu WebSocket usługi PubSub