Azure Web PubSub tarafından desteklenen JSON WebSocket altprotocol

  • Makale

JSON WebSocket altprotocol, json.webpubsub.azure.v1yukarı akış sunucusuna gidiş dönüş olmadan hizmet aracılığıyla istemciler arasında yayımlama/abone olma iletilerinin değişimini sağlar. Altprotocol kullanan json.webpubsub.azure.v1 bir WebSocket bağlantısı, PubSub WebSocket istemcisi olarak adlandırılır.

Genel bakış

Basit bir WebSocket bağlantısı, iletileri gönderdiğinde bir message olayı tetikler ve iletileri işlemek ve diğer işlemleri yapmak için sunucu tarafına dayanır.

json.webpubsub.azure.v1 Altprotocol ile şunları yapabilecek PubSub WebSocket istemcileri oluşturabilirsiniz:

Örneğin, aşağıdaki JavaScript koduyla bir PubSub WebSocket istemcisi oluşturabilirsiniz:

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

Bu belgede alt protokol json.webpubsub.azure.v1 istekleri ve yanıtları açıklanmaktadır. Hem gelen hem de giden veri çerçeveleri JSON yükleri içermelidir.

İzinler

PubSub WebSocket istemcisi yalnızca yetkili olduğunda diğer istemcilere yayımlayabilir. roles İstemciye atanan, istemciye verilen izinleri belirler:

Role İzin
Belirtilmemiş İstemci olay istekleri gönderebilir.
webpubsub.joinLeaveGroup İstemci herhangi bir gruba katılabilir/gruptan ayrılabilir.
webpubsub.sendToGroup İstemci, iletileri herhangi bir gruba yayımlayabilir.
webpubsub.joinLeaveGroup.<group> İstemci gruba katılabilir/gruptan <group>ayrılabilir.
webpubsub.sendToGroup.<group> İstemci, grubuna <group>ileti yayımlayabilir.

Sunucu REST API'leri veya sunucu SDK'ları aracılığıyla istemci izinlerini dinamik olarak verebilir veya iptal edebilir.

İstekler

Grupları birleştirme

Biçim:

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

Grup bırakma

Biçim:

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

İletileri yayımlama

Biçim:

{
    "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 her isteğin kimliğidir ve benzersiz olmalıdır. Hizmet, isteğin işlem sonucunu bildirmek için bir hata yanıtı iletisi gönderir. Ayrıntılar için bkz . AckId ve Ack Yanıtı
  • noEcho isteğe bağlıdır. True olarak ayarlanırsa, bu ileti aynı bağlantıya geri döndürülemez. Ayarlanmadıysa varsayılan değer false olur.
  • dataType, veya textbinaryolarak jsonayarlanabilir:
    • json: data JSON'un desteklediği ve olduğu gibi yayımlanacak herhangi bir tür olabilir; Belirtilmezse dataType , varsayılan olarak olur json.
    • text: data dize biçiminde olmalıdır ve dize verileri yayımlanacaktır;
    • binary: data base64 biçiminde olmalı ve ikili veriler yayımlanacaktır;

Olay 1: metin verilerini yayımlama:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "text",
    "data": "text data",
    "ackId": 1
}
  • içindeki alt protokol istemcileri <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "text",
    "data" : "text data"
}
  • içindeki <group_name> basit WebSocket istemcileri dizesini text dataalır.

Olay 2: JSON verilerini yayımlama:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    }
}
  • içindeki alt protokol istemcileri <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "json",
    "data" : {
        "hello": "world"
    }
}
  • içindeki <group_name> basit WebSocket istemcileri serileştirilmiş dizesini {"hello": "world"}alır.

Olay 3: ikili verileri yayımlama:

{
    "type": "sendToGroup",
    "group": "<group_name>",
    "dataType" : "binary",
    "data": "<base64_binary>",
    "ackId": 1
}
  • içindeki alt protokol istemcileri <group_name> :
{
    "type": "message",
    "from": "group",
    "group": "<group_name>",
    "dataType" : "binary",
    "data" : "<base64_binary>", 
}
  • içindeki <group_name> basit WebSocket istemcileri ikili çerçevedeki ikili verileri alır.

Özel olaylar gönderme

Biçim:

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

dataType, binaryveya jsontürlerinden textbiri olabilir:

  • json: veriler json'un desteklediği herhangi bir tür olabilir ve olduğu gibi yayımlanır; Varsayılan değerdir json.
  • text: veriler dize biçimindedir ve dize verileri yayımlanır;
  • binary: veriler base64 biçimindedir ve ikili veriler yayımlanır;

Olay 1: metin verileriyle olay gönderme:

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

Yukarı akış olay işleyicisi şuna benzer verileri alır:

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

Content-Type CloudEvents HTTP isteği için olduğunda değeridir text/plain dataType text.

Olay 2: JSON verileriyle olay gönderme:

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

Yukarı akış olay işleyicisi şuna benzer verileri alır:

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

Content-Type CloudEvents HTTP isteği application/json dataType içinjson

Olay 3: ikili verilerle olay gönderme:

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

Yukarı akış olay işleyicisi şuna benzer verileri alır:

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

Content-Type CloudEvents HTTP isteği için olduğunda değeridir application/octet-stream dataType binary. WebSocket çerçevesi, metin iletisi çerçeveleri için biçimlendirilebilir text veya ileti çerçeveleri için binary UTF8 kodlanmış ikili dosyaları olabilir.

Web PubSub hizmeti, ileti açıklanan biçimle eşleşmiyorsa istemciyi reddeder.

Yanıtlar

İstemci tarafından alınan ileti türleri:

  • ack - içeren ackIdbir isteğe verilen yanıt.
  • message - Gruptan veya sunucudan gelen iletiler.
  • system - Web PubSub hizmetinden gelen iletiler.

Ack yanıtı

İstemci isteği içerdiğinde ackId, hizmet istek için bir hata yanıtı döndürür. İstemci, ack yanıtını bir işlemle bekleyerek ve belirli bir async await süre içinde ack yanıtı alınmadığında zaman aşımı işlemi kullanarak ack mekanizmasını işlemelidir.

Biçim:

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

İstemci uygulaması her zaman öğesinin success veya önce olup true false olmadığını denetlemeli, ardından yalnızca olduğunda success falsehatayı okumalıdır.

İleti yanıtı

İstemciler, istemcinin katıldığı bir gruptan veya sunucu yönetim rolünde çalışan, belirli istemcilere veya kullanıcılara ileti gönderen sunucudan yayımlanan iletileri alabilir.

  1. İleti bir gruptan geldiğinde

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

  2. İleti sunucudan geldiğinde.

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

Olay 1: ILE REST API aracılığıyla bağlantıya veri Hello World gönderme Content-Type=text/plain

  • Basit bir WebSocket istemcisi, veri içeren bir Metin WebSocket çerçevesi alır: Hello World;

  • PubSub WebSocket istemcisi şu işlemleri alır:

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

Olay 2: ILE REST API aracılığıyla bağlantıya veri { "Hello" : "World"} gönderme Content-Type=application/json

  • Basit bir WebSocket istemcisi, dize verileri içeren bir metin WebSocket çerçevesi alır: { "Hello" : "World"}.

  • PubSub WebSocket istemcisi şu işlemleri alır:

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

REST API içerik türünü kullanarak bir dize Hello World gönderiyorsa, basit WebSocket istemcisi çift tırnak (" ) ile sarmalanmış bir JSON dizesi "Hello World" application/json alır.

Olay 3: ile REST API aracılığıyla bağlantıya ikili veri gönderme Content-Type=application/octet-stream

  • Basit bir WebSocket istemcisi, ikili verileri içeren bir ikili WebSocket çerçevesi alır.

  • PubSub WebSocket istemcisi şu işlemleri alır:

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

Sistem yanıtı

Web PubSub hizmeti istemcilere sistemle ilgili iletiler gönderir.

Bağlandı

İstemci başarıyla bağlandığında istemciye gönderilen ileti:

{
    "type": "system",
    "event": "connected",
    "userId": "user1",
    "connectionId": "abcdefghijklmnop",
}

Bağlantı kesildi

Sunucu bağlantıyı kapattığında veya hizmet istemciyi reddettiyse istemciye gönderilen ileti.

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

Sonraki adımlar

Kendi uygulamanızı oluşturmaya başlamak için şu kaynakları kullanın:

Öğretici: Azure Web PubSub'da iletileri yayımlama ve iletilere abone olma

Öğretici: Azure Web PubSub ile basit bir sohbet odası oluşturma

Öğretici: İstemci akışı için hizmet tarafından desteklenen bir alt protokol kullanma

Öğretici: Azure İşlevleri ve Web PubSub ile sunucusuz sohbet oluşturma

Öğretici: Olay dinleyicisi yapılandırma

Canlı tanıtımlarla oynama

Diğer Azure Web PubSub örneklerini keşfedin