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

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	Przykład
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": "ABC"
        }
    ]
}

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życiujsondataType=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