Azure Web PubSub tarafından desteklenen JSON WebSocket altprotocol

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:

birleştirme isteklerini kullanarak bir gruba katılma.
yayımlama isteklerini kullanarak iletileri doğrudan bir gruba yayımlayın.
Mesajları doğrudan bir gruba akış isteği ile akın.
olay isteklerini kullanarak iletileri farklı yukarı akış olay işleyicilerine yönlendirin.

Ö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.
`webpubsub.joinLeaveGroups.<pattern>`	İstemci adı eşleşen `<pattern>` herhangi bir gruba katılabilir/gruptan ayrılabilir (bkz. Joker karakter grubu rol desenleri).
`webpubsub.sendToGroups.<pattern>`	İstemci, adı eşleşen `<pattern>` herhangi bir gruba ileti yayımlayabilir (bkz. Joker karakter grubu rol desenleri).

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

Uyarı

Joker karakter rolleri (örn. webpubsub.sendToGroups.<pattern>) çalışma zamanı sırasında REST API'lerinde veya sunucu SDK'larında henüz desteklenmemektedir.

İstekler

Grupları birleştirme

Biçim:

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

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ı

Grup bırakma

Biçim:

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

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ı

İ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 jsontextolarak binaryayarlanabilir:
- 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.

Mesaj yayınına başla

Grup akışı başlatmak için, mülk stream ile bir sendToGroup talep gönderin. Bir yayın başlatma talebi , dataType, veya ackId. içermezdata.

Biçim:

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

stream.streamId mantıksal akışın tanımlayıcısıdır. Boş olmayan bir dizi olmalı ve aynı istemci bağlantısındaki aktif akışlar arasında benzersiz olmalıdır. İstemci kütüphaneleri, GUID veya UUID gibi küresel benzersiz bir değer üretmeleri için önerilir.
stream.idleTimeoutMs isteğe bağlıdır. Belirtilmişse, daha büyük olmalıdır 0. Eğer atlanırsa, hizmet varsayılan olarak milisaniyelerdir 300000 . Değer boşta bir zaman aşımıdır, toplam akış ömrü değil. Yayın verisi gönderin, yayın keepalive gönderin veya bu zaman aşımından önce yayını durdurun, uygulama yayını açık tutması gerektiğinde bu süre bitmeden.
noEcho isteğe bağlıdır. Doğru olarak ayarlanırsa, akış mesajları aynı bağlantıya geri yankılmaz. Ayarlanmadıysa varsayılan değer false olur.

Akış kabul edildiğinde, istemci 'ye ayarlanmış 1bir akış ack yanıtıexpectedSequenceId alır.

Akış verisi gönder

Akış verisini göndermek için, , , , ve dataile bir streamData talep streamIdgönderin. dataTypestreamSequenceId

Biçim:

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

streamId aynı istemci bağlantısında aktif bir akış tespit eder.
streamSequenceId pozitif bir uint64 sayısıdır. Bir akıştaki ilk veri parçası , kullanır 1ve aynı streamId şey için her sonraki veri parçası tam 1olarak artar .
dataType yayınlama mesajlarıyla aynı veri kodlama kurallarıyla , text, veya binary, olarak ayarlanabilirjson.

Bir yayını abonelere veri teslim etmeden aktif tutmak için, sadece type ve streamIdile bir streamData talep gönderin.

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

Yayın mesajlarını sonlandır

Bir yayını bitirmek için bir streamEnd istek gönderin.

Biçim:

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

Bir akışı uygulama tanımlı bir hata ile bitirmek için isteğe error bağlı özelliği ekleyin.

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

error.message isteğe bağlı bir insan tarafından okunabilir bir hata mesajıdır.
error.userErrorCode isteğe bağlı bir uygulama tanımlı hata kodudur.

Akış kapandığında, yayıncı bir akış kapalı yanıtı 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 
}

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ı

dataType, textveya binarytürlerinden jsonbiri 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/plaindataTypetext.

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/jsondataType 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-streamdataTypebinary. 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.

Ping

Biçim:

{
    "type": "ping",
}

İstemci, Web PubSub hizmetinin istemcinin canlılığını algılamasını sağlamak için hizmete bir ping ileti gönderebilir.

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.
pong - İletiye ping verilen yanıt.
streamAck - Kabul edilen akış verilerini onaylayan ve bir sonraki beklenen akış dizisi ID'sini bildiren yanıt.
streamNack - Denenebilir bir akış hatası için verilen yanıt.
streamClosed - Terminal yayıncı tarafı akış kapatma için verilen yanıt.

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 asyncawait 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 truefalse olmadığını denetlemeli, ardından yalnızca olduğunda successfalsehatayı 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.

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

İ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 `Merhaba Dünya` gönderme `Content-Type`=`text/plain`

Basit bir WebSocket istemcisi, veri içeren bir Metin WebSocket çerçevesi alır: Merhaba Dünya;

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 Merhaba Dünya gönderiyorsa, basit WebSocket istemcisi çift tırnak (application/json ) ile sarmalanmış bir JSON dizesi "Merhaba Dünya"" 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>"
}

Akış mesajı yanıtı

Bir mesaj bir akışa ait olduğunda, grup mesajı bir stream özellik içerir.

{
    "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 mantıksal akış tanımlayıcısıdır.
stream.streamSequenceId akıştaki mesajın dizi numarasıdır.
stream.endOfStream isteğe bağlıdır. Ayarlandığında true, mesaj akışın son mesajıdır.
stream.error isteğe bağlıdır ve yalnızca akış bir hata ile sona erdiğinde mevcuttur. userErrorCode sadece için UserErrormevcuttur.

Akış ack tepkisi

Hizmet, kabul edilen akış verilerini onaylamak ve beklediği bir sonraki akış dizisi ID'sini bildirmek için bir streamAck yanıt gönderir.

Biçim:

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

Stream nack tepkisi

Hizmet, denenebilir bir akış hatası için yanıt streamNack gönderir.

Biçim:

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

Akış kapalı yanıt

Yayıncı tarafı yayın yayını kapandığında hizmet yanıt streamClosed gönderir.

Biçim:

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

error Bu özellik, dere normal şekilde kapalıyken atlanır.

Sistem yanıtı

Web PubSub hizmeti istemcilere sistemle ilgili iletiler gönderir.

Pong yanıtı

Web PubSub hizmeti, istemciden bir pong ileti aldığında istemciye bir ping ileti gönderir.

Biçim:

{
    "type": "pong",
}

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

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-06-17

Azure Web PubSub tarafından desteklenen JSON WebSocket altprotocol

Genel bakış

İzinler

İstekler

Grupları birleştirme

Grup bırakma

İletileri yayımlama

Olay 1: metin verilerini yayımlama:

Olay 2: JSON verilerini yayımlama:

Olay 3: ikili verileri yayımlama:

Mesaj yayınına başla

Akış verisi gönder

Yayın mesajlarını sonlandır

Özel olaylar gönderme

Olay 1: metin verileriyle olay gönderme:

Olay 2: JSON verileriyle olay gönderme:

Olay 3: ikili verilerle olay gönderme:

Ping

Yanıtlar

Ack yanıtı

İleti yanıtı

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

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

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

Akış mesajı yanıtı

Akış ack tepkisi

Stream nack tepkisi

Akış kapalı yanıt

Sistem yanıtı

Pong yanıtı

Bağlandı

Bağlantı kesildi

Sonraki adımlar

Geri Bildirim

Ek kaynaklar

Olay 1: ILE REST API aracılığıyla bağlantıya veri `Merhaba Dünya` gönderme `Content-Type`=`text/plain`

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

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