Azure Web PubSub element podrzędny Reliable JSON WebSocket

Podprotokol json.reliable.webpubsub.azure.v1protokołu WebSocket w formacie JSON umożliwia wysoce niezawodną wymianę komunikatów publikowania/subskrybowania bezpośrednio między klientami za pośrednictwem usługi bez rundy na serwerze nadrzędnym.

W tym dokumencie opisano podprotocol json.reliable.webpubsub.azure.v1.

Gdy połączenia klienta protokołu WebSocket upuszczają się z powodu sporadycznych problemów z siecią, komunikaty mogą zostać utracone. W systemie pub/sub wydawcy są oddzieleni od subskrybentów i mogą nie wykrywać porzuconego połączenia lub utraty komunikatów subskrybentów.

Aby rozwiązać sporadyczne problemy z siecią i zachować niezawodne dostarczanie komunikatów, możesz użyć podprotocol usługi Azure WebPubSub, aby utworzyć json.reliable.webpubsub.azure.v1 Reliable PubSub WebSocket.

Klient Reliable PubSub WebSocket może:

• odzyskiwanie połączenia po sporadycznych problemach z siecią.
• odzyskiwanie po utracie komunikatów.
• dołącz do grupy przy użyciu żądań dołączenia.
• pozostaw grupę przy użyciu żądań urlopu.
• publikowanie komunikatów bezpośrednio w grupie przy użyciu żądań publikowania.
• przesyłaj wiadomości bezpośrednio do grupy za pomocą żądań streamingowych.
• kierowanie komunikatów bezpośrednio do programów obsługi zdarzeń nadrzędnych przy użyciu żądań zdarzeń.

Na przykład można utworzyć klienta Reliable PubSub WebSocket przy użyciu następującego kodu JavaScript:

var pubsub = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'json.reliable.webpubsub.azure.v1');

Zobacz How to create reliable clients to implement reconnection and message reliability for publisher and subscriber clients (Jak tworzyć niezawodnych klientów w celu zaimplementowania ponownego połączenia i niezawodności komunikatów dla klientów wydawcy i subskrybenta).

Gdy klient korzysta z tego subprotocol, zarówno ramki danych wychodzących, jak i przychodzących muszą zawierać ładunki JSON.

Uprawnienia

Klient protokołu WebSocket PubSub może publikować tylko na innych klientach, gdy jest autoryzowany. Przypisany roles do klienta określ uprawnienia przyznane klientowi:

Serwer może dynamicznie udzielać lub odwoływać uprawnienia klienta za pośrednictwem interfejsów API REST lub zestawów SDK serwera.

Żądania

Dołączanie grup

Format:

{
    "type": "joinGroup",
    "group": "<group_name>",
    "ackId" : 1
}

• ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

Pozostaw grupy

Format:

{
    "type": "leaveGroup",
    "group": "<group_name>",
    "ackId" : 1
}

• ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

Publikowanie komunikatów

Format:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "ackId" : 1,
    "noEcho": true|false,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

• ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response
• Element noEcho jest opcjonalny. Jeśli ustawiono wartość true, ten komunikat nie jest ponownie zwracany do tego samego połączenia. Jeśli nie zostanie ustawiona, wartość domyślna to false.
• dataType można ustawić na json, textlub binary:
  • json: data może być dowolnym typem, który obsługuje kod JSON i będzie publikowany jako to, co to jest; Jeśli dataType nie zostanie określony, wartość domyślna to json.
  • text: data powinien być w formacie ciągu, a dane ciągu zostaną opublikowane;
  • binary: data powinien być w formacie base64, a dane binarne zostaną opublikowane;

Przypadek 1: publikowanie danych tekstowych:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}

• Klienci subprotocol w <group_name> odbieraniu:

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}

• Prosti klienci protokołu WebSocket w <group_name> programie otrzymują ciąg text data.

Przypadek 2: publikowanie danych JSON:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}

• Klienci subprotocol w <group_name> odbieraniu:

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}

• Prosti klienci protokołu WebSocket w <group_name> programie otrzymują serializowany ciąg {"hello": "world"}.

Przypadek 3. Publikowanie danych binarnych:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}

• Klienci subprotocol w <group_name> odbieraniu:

{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}

• Prosti klienci protokołu WebSocket odbierają <group_name>dane binarne w ramce binarnej .

Rozpocznij przesyłanie wiadomości

Aby rozpocząć grupowy stream, wyślij sendToGroup zapytanie za pomocą własności stream . Żądanie uruchomienia strumienia nie zawiera data, dataType, ani ackId.

Format:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "noEcho": true|false,
    "stream": {
        "streamId": "<stream_id>",
        "idleTimeoutMs": 300000
    }
}

• stream.streamId jest identyfikatorem strumienia logicznego (LOG). Musi to być ciąg niepusty i unikalny między aktywnymi strumieniami na tym samym połączeniu klienta. Biblioteki klienckie są zalecane do generowania globalnie unikalnej wartości, takiej jak GUID lub UUID.
• Element stream.idleTimeoutMs jest opcjonalny. Jeśli jest to określone, musi być większe niż 0. Jeśli to pominiesz, domyślna wartość usługi to 300000 milisekundy. Wartość to czas bezczynności, a nie całkowity czas życia strumienia. Wyślij dane strumieniowe, wyślij stream keepalive lub zakończ stream przed upływem tego czasu, gdy aplikacja musi utrzymać strumień otwarty.
• Element noEcho jest opcjonalny. Jeśli ustawione na prawda, wiadomości strumieniowe nie są odbijane do tego samego połączenia. Jeśli nie zostanie ustawiona, wartość domyślna to false.

Gdy strumień zostanie zaakceptowany, klient otrzymuje odpowiedź strumienia ACK z expectedSequenceId ustawioną na .1

Wyślij dane strumieniowe

Aby przesłać dane strumieniowe, wyślij żądanie streamData z streamId, streamSequenceId, dataType, oraz data.

Format:

{
    "type": "streamData",
    "streamId": "<stream_id>",
    "streamSequenceId": 1,
    "dataType" : "json|text|binary",
    "data": {}
}

• streamId identyfikuje aktywny strumień na tym samym połączeniu klienckim.
• streamSequenceId jest dodatnim numerem uint64. Pierwszy fragment danych w strumieniu używa 1, a każdy kolejny fragment danych dla tego samego streamId zwiększa się dokładnie 1o .
• dataType można ustawić na json, text, lub binary, z tymi samymi regułami kodowania danych co komunikaty publikuj.

Aby utrzymać strumień aktywny bez dostarczania danych subskrybentom, wyślij żądanie streamData z używaniem tylko type i streamId.

{
    "type": "streamData",
    "streamId": "<stream_id>"
}

Zakończenie transmisji wiadomości

Aby zakończyć transmisję, wyślij prośbę streamEnd .

Format:

{
    "type": "streamEnd",
    "streamId": "<stream_id>"
}

Aby zakończyć strumień błędem zdefiniowanym przez aplikację, należy uwzględnić opcjonalną właściwość error .

{
    "type": "streamEnd",
    "streamId": "<stream_id>",
    "error": {
        "message": "<error_detail>",
        "userErrorCode": "<application_error_code>"
    }
}

• error.message jest opcjonalnym, czytelnym komunikatem o błędzie.
• error.userErrorCode jest opcjonalnym kodem błędu definiowanym przez aplikację.

Gdy strumień zostaje zamknięty, wydawca otrzymuje odpowiedź zamkniętą strumieniem.

Wysyłanie zdarzeń niestandardowych

Format:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "json|text|binary",
    "data": {}, // data can be string or valid json token depending on the dataType 
}

• ackId to tożsamość każdego żądania i powinna być unikatowa. Usługa wysyła komunikat odpowiedzi ack, aby powiadomić wynik procesu żądania. Aby uzyskać szczegółowe informacje, zobacz AckId i Ack Response

dataType może być jednym z textelementów , binarylub json:

• json: dane mogą być dowolnym typem obsługiwane w formacie JSON i będą publikowane jako to, co to jest; Wartość domyślna to json.
• text: dane są w formacie ciągu, a dane ciągu zostaną opublikowane;
• binary: dane są w formacie base64, a dane binarne zostaną opublikowane;

Przypadek 1: wysyłanie zdarzenia z danymi tekstowymi:

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

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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>

text data

Wartość Content-Type dla żądania HTTP cloudEvents to , gdy text/plain ma wartość dataTypetext.

Przypadek 2: wysyłanie zdarzenia z danymi JSON:

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

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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>

{
    "hello": "world"
}

Wartość Content-Type dla żądania HTTP cloudEvents to, gdy application/json jest dataTypejson

Przypadek 3: wysyłanie zdarzenia z danymi binarnymi:

{
    "type": "event",
    "event": "<event_name>",
    "ackId": 1,
    "dataType" : "binary",
    "data": "base64_binary", 
}

Program obsługi zdarzeń nadrzędnych odbiera dane podobne do następujących:

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>

binary

Wartość Content-Type dla żądania HTTP cloudEvents to , gdy application/octet-stream ma wartość dataTypebinary. Ramka Protokołu WebSocket może być text formatowana dla ramek wiadomości tekstowych lub plików binarnych zakodowanych w formacie UTF8 dla binary ramek komunikatów.

Usługa Web PubSub odrzuca klienta, jeśli komunikat nie jest zgodny z opisanym formatem.

Polecenie ping

Format:

{
    "type": "ping",
}

Klient może wysłać ping komunikat do usługi, aby umożliwić usłudze Web PubSub wykrywanie aktywności klienta.

Sekwencja Ack

Format:

{
    "type": "sequenceAck",
    "sequenceId": "<sequenceId>",
}

Klient Reliable PubSub WebSocket musi wysłać komunikat ack sekwencji po odebraniu komunikatu z usługi. Aby uzyskać więcej informacji, zobacz How to create reliable clients (Jak tworzyć niezawodnych klientów)

• sequenceId jest przyrostowym numerem uint64 z odebranego komunikatu.

Odpowiedzi

Wiadomości odbierane przez klienta mogą mieć kilka typów: ack, , systemmessage, pong, , streamAck, streamNackoraz streamClosed. Komunikaty z typem message mają sequenceId właściwość. Klient musi wysłać do usługi sekwencję Ack po odebraniu komunikatu.

Odpowiedź Ack

Gdy żądanie zawiera ackIdelement , usługa zwróci odpowiedź ack dla tego żądania. Implementacja klienta powinna obsługiwać ten mechanizm ack, w tym oczekiwanie na odpowiedź ack przy użyciu asyncawait operacji i mieć procedurę obsługi przekroczenia limitu czasu, gdy odpowiedź ack nie zostanie odebrana w określonym okresie.

Format:

{
    "type": "ack",
    "ackId": 1, // The ack id for the request to ack
    "success": false, // true or false
    "error": {
        "name": "Forbidden|InternalServerError|Duplicate",
        "message": "<error_detail>"
    }
}

Implementacja klienta POWINNA zawsze sprawdzać, czy success element jest true czy false pierwszy. Tylko wtedy, gdy successfalse klient odczytuje z errorprogramu .

Odpowiedź na komunikat

Klienci mogą odbierać komunikaty publikowane z grupy, do której klient dołączył lub z serwera, który działa w roli zarządzania serwerem, wysyła komunikaty do określonych klientów lub użytkowników.

1. Komunikat odpowiedzi z grupy:

   {
       "sequenceId": 1,
       "type": "message",
       "from": "group",
       "group": "<group_name>",
       "dataType": "json|text|binary",
       "data" : {} // The data format is based on the dataType
       "fromUserId": "abc"
   }
   

2. Komunikat odpowiedzi z serwera:

   {
       "sequenceId": 1,
       "type": "message",
       "from": "server",
       "dataType": "json|text|binary",
       "data" : {} // The data format is based on the dataType
   }
   

Przypadek 1: Wysyłanie danych Hello world do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=text/plain

• Prosty klient protokołu WebSocket otrzymuje tekstową ramkę protokołu WebSocket z danymi: Hello world;

• Klient protokołu WebSocket pubSub odbiera komunikat w formacie JSON:

  {
      "sequenceId": 1,
      "type": "message",
      "from": "server",
      "dataType" : "text",
      "data": "Hello World", 
  }
  

Przypadek 2: Wysyłanie danych { "Hello" : "World"} do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=application/json

• Prosty klient protokołu WebSocket otrzymuje tekstową ramkę protokołu WebSocket z danymi ciągowymi: { "Hello" : "World"};

• Klient protokołu WebSocket pubSub odbiera komunikat w formacie JSON:

  {
      "sequenceId": 1,
      "type": "message",
      "from": "server",
      "dataType" : "json",
      "data": {
          "Hello": "World"
      }
  }
  

Jeśli interfejs API REST wysyła ciąg Hello world przy użyciu application/json typu zawartości, prosty klient protokołu WebSocket otrzymuje ciąg "Hello world" JSON opakowany w ."

Przypadek 3. Wysyłanie danych binarnych do połączenia za pośrednictwem interfejsu API REST za pomocą polecenia Content-Type=application/octet-stream

• Prosty klient protokołu WebSocket otrzymuje binarną ramkę protokołu WebSocket z danymi binarnymi.

• Klient protokołu WebSocket pubSub odbiera komunikat w formacie JSON:

  {
      "sequenceId": 1,
      "type": "message",
      "from": "server",
      "dataType" : "binary",
      "data": "<base64_binary>"
  }
  

Odpowiedź na wiadomości strumieniowe

Gdy wiadomość należy do strumienia, wiadomość grupowa zawiera właściwość stream . Niezawodny sequenceId pozostaje powiązany i różni się od stream.streamSequenceId.

{
    "sequenceId": 1,
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType": "json|text|binary",
    "data": {},
    "fromUserId": "abc",
    "stream": {
        "streamId": "<stream_id>",
        "streamSequenceId": 1,
        "endOfStream": true,
        "error": {
            "name": "IdleTimeout|InternalServerError|Forbidden|Cancelled|UserError",
            "message": "<error_detail>",
            "userErrorCode": "<application_error_code>"
        }
    }
}

• stream.streamId jest logicznym identyfikatorem strumienia.
• stream.streamSequenceId to numer sekwencyjny wiadomości w strumieniu.
• Element stream.endOfStream jest opcjonalny. Po ustawieniu na true, wiadomość jest wiadomością końcową strumienia.
• stream.error jest opcjonalna i występuje tylko wtedy, gdy strumień kończy się błędem. userErrorCode jest obecna tylko dla UserError.

Odpowiedź strumienia ACK

Usługa wysyła streamAck odpowiedź potwierdzającą zaakceptowane dane strumieniowe oraz raportującą kolejną sekwencję strumienia, której się spodziewa.

Format:

{
    "type": "streamAck",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2
}

Odpowiedź strumienia nack

Usługa wysyła streamNack odpowiedź na błąd strumienia do odzyskania.

Format:

{
    "type": "streamNack",
    "streamId": "<stream_id>",
    "expectedSequenceId": 2,
    "name": "InvalidSequenceId|TransientError",
    "message": "<error_detail>"
}

Reakcja zamknięta w strumieniu

Usługa wysyła odpowiedź, streamClosed gdy strumień po stronie wydawcy zostanie zamknięty.

Format:

{
    "type": "streamClosed",
    "streamId": "<stream_id>",
    "error": {
        "name": "StreamNotFound|Forbidden|BadRequest|InternalServerError|IdleTimeout",
        "message": "<error_detail>"
    }
}

Właściwość jest error pomijana, gdy strumień jest normalnie zamknięty.

Odpowiedź systemu

Usługa Web PubSub może zwracać odpowiedzi związane z systemem do klienta.

Odpowiedź na ponga

Usługa Web PubSub wysyła pong komunikat do klienta po odebraniu ping komunikatu z klienta.

Format:

{
    "type": "pong",
}

Połączono

Odpowiedź na żądanie połączenia klienta:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
    "reconnectionToken": "<token>"
}

connectionId i reconnectionToken są używane do ponownego nawiązywania połączenia. Utwórz żądanie połączenia za pomocą identyfikatora URI w celu ponownego nawiązania połączenia:

wss://<service-endpoint>/client/hubs/<hub>?awps_connection_id=<connectionId>&awps_reconnection_token=<reconnectionToken>

Więcej szczegółów można znaleźć w temacie Odzyskiwanie połączenia

Odłączony

Odpowiedź, gdy serwer zamknie połączenie lub gdy usługa odrzuci połączenie klienta:

{
    "type": "system",
    "event": "disconnected",
    "message": "reason"
}

Następne kroki

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