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.
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.

Ö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.

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 `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 (application/json ) ile sarmalanmış bir JSON dizesi "Hello World"" 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.

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-04-01

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:

Ö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 Hello World 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

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 `Hello World` 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`