Azure Web PubSub için WebSocket istemci protokolleri

İstemciler standart WebSocket protokolunu kullanarak Azure Web PubSub'a bağlanır.

Hizmet uç noktaları

Web PubSub hizmeti, istemcilerin bağlanması için iki tür uç nokta sağlar:

/client/hubs/{hub}
/client/?hub={hub}

{hub} , çeşitli uygulamalar için yalıtım işlevi gören zorunlu bir parametredir. Bunu yolda veya sorguda ayarlayabilirsiniz.

Yetkilendirme

İstemciler hizmete bir JSON Web Belirteci (JWT) ile bağlanır. Belirteç, ya /client/?hub={hub}&access_token={token} sorgu dizesinde ya da Authorization üst bilgisinde Authorization: Bearer {token} olabilir.

Genel yetkilendirme iş akışı aşağıdadır:

İstemci, uygulama sunucunuzla anlaşma sağlar. Uygulama sunucusu, istemci isteğini işleyen ve istemcinin hizmete bağlanması için bir JWT imzalayan yetkilendirme ara yazılımını içerir.
Uygulama sunucusu JWT'yi ve hizmet URL'sini istemciye döndürür.
İstemci, URL'yi ve uygulama sunucusundan döndürülen JWT'yi kullanarak Web PubSub hizmetine bağlanmaya çalışır.

Desteklenen talepler

JWT içinde özel talepler belirterek erişim belirtecini oluştururken istemci bağlantısının özelliklerini de yapılandırabilirsiniz:

Açıklama	Talep türü	Talep değeri	Notes
`userId` İstemci bağlantısı için	`sub`	kullanıcıId	Yalnızca bir `sub` talepe izin verilir.
Belirtecin ömrü	`exp`	son kullanma zamanı	`exp` (süre sonu) talebi, belirtecin bu süre veya sonrasında işleme kabul edilmemesi gereken süre sonunu tanımlar.
İstemci bağlantısının başlangıçta sahip olduğu izinler	`role`	izinlerde tanımlanan rol değeri	İstemcinin birden çok izne sahip olması durumunda, birden çok `role` talep belirtin.
İstemci bağlantısının Azure Web PubSub'a bağlandıktan sonra katıldığı ilk gruplar	`webpubsub.group`	katılacağınız grup	İstemci birden fazla `webpubsub.group` gruba katıldığı takdirde, birden fazla talep belirtin.

Erişim belirtecine özel talepler de ekleyebilir ve bu değerler claims içindeki özelliği olarak korunur.

Sunucu SDK'ları , istemciler için erişim belirtecini oluşturmak üzere API'ler sağlar.

Basit WebSocket istemcisi

Adlandırmanın da belirttiği gibi basit bir WebSocket istemcisi basit bir WebSocket bağlantısıdır. Ayrıca kendi özel alt protokolüne de sahip olabilir.

Örneğin, JavaScript'te aşağıdaki kodu kullanarak basit bir WebSocket istemcisi oluşturabilirsiniz:

// simple WebSocket client1
var client1 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// simple WebSocket client2 with some custom subprotocol
var client2 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1', 'custom.subprotocol')

Basit WebSocket istemcisinin iki modu vardır: sendEvent ve sendToGroup. Mod, bağlantı kurulduktan sonra belirlenir ve daha sonra değiştirilemez.

sendEvent , basit WebSocket istemcisi için varsayılan moddur. Modda sendEvent , istemcinin gönderdiği her WebSocket çerçevesi bir message olay olarak kabul edilir. Kullanıcılar bu olayları işlemek için olay işleyicilerini veya message yapılandırabilir.

// Every data frame is considered as a `message` event
var client3 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1');

// Or explicitly set the mode
var client4 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendEvent');

Modda sendToGroup , istemcinin gönderdiği her WebSocket çerçevesi belirli bir gruba yayımlanacak bir ileti olarak kabul edilir. group bu modda gerekli bir sorgu parametresidir ve yalnızca tek bir değere izin verilir. Bağlantının hedef gruba ileti göndermek için ilgili izinleri de olmalıdır. Her iki webpubsub.sendToGroup.<group> ve webpubsub.sendToGroup rolü bunun için çalışır.

Örneğin, JavaScript'te sendToGroup modda group=group1 kullanarak aşağıdaki kod ile basit bir WebSocket istemcisi oluşturabilirsiniz:

var client5 = new WebSocket('wss://test.webpubsub.azure.com/client/hubs/hub1?webpubsub_mode=sendToGroup&group=group1');

PubSub WebSocket istemcisi

PubSub WebSocket istemcisi, Azure Web PubSub hizmeti tarafından tanımlanan alt protokolleri kullanan WebSocket istemcisidir:

json.webpubsub.azure.v1
protobuf.webpubsub.azure.v1

Hizmet tarafından desteklenen altprotocol ile PubSub WebSocket istemcisi, izinlere sahip olduklarında iletileri doğrudan gruplara yayımlayabilir.

Altprotocol `json.webpubsub.azure.v1`

JSON altprotokolü için buraya ayrıntılı olarak bakın.

PubSub WebSocket istemcisi oluşturma

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

Bir gruba doğrudan istemciden katıl

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'joinGroup',
        group: 'group1',
        ackId: ++ackId
    }));

İstemciden doğrudan bir gruba ileti gönderme

let ackId = 0;
pubsubClient.send(
    JSON.stringify({
        type: 'sendToGroup',
        group: 'group1',
        ackId: ++ackId,
        dataType: "json",
        data: {
            "hello": "world"
        }
    }));

Altprotocol `protobuf.webpubsub.azure.v1`

Protokol arabellekleri (protobuf), ikili veri göndermeyi kolaylaştıran dilden bağımsız, platformdan bağımsız, ikili tabanlı bir protokoldür. Protobuf Java, Python, Objective-C, C# ve C++ gibi birçok dil için istemci oluşturmaya yönelik araçlar sağlar. protobuf hakkında daha fazla bilgi edinin.

Örneğin, JavaScript'te aşağıdaki kodu kullanarak protobuf altprotocol'u olan bir PubSub WebSocket istemcisi oluşturabilirsiniz:

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

Protobuf altprotokolü için buraya ayrıntılı olarak bakın.

AckId ve Ack Yanıtı

PubSub WebSocket İstemcisi özelliğini ackId, joinGroup, leaveGroup ve sendToGroup iletileri için destekler. ackId kullanırken, isteğiniz işlendiğinde bir onay yanıt mesajı alabilirsiniz. Yangın ve unut senaryolarında ackId öğesini göz ardı etmeyi seçebilirsiniz. Makalede, ackId belirterek veya belirtmeyerek davranış farklılıklarının nasıl olduğunu açıklamaktayız.

`ackId` belirtilmediğinde davranış

Belirtilmezse ackId, bu işlem ateşle ve unut tekniğine göre yapılır. İletileri aracılık ederken hatalar olsa bile bildirim almanıza imkan yoktur.

`ackId` belirtildiğinde davranış

İdempotent yayımlama

ackId bir uint64 numarasıdır ve aynı bağlantı kimliğine sahip bir istemci içinde benzersiz olmalıdır. Web PubSub Hizmeti ackId ve aynı ackId olan iletileri kaydeder ve bunları aynı mesaj olarak değerlendirir. Hizmet aynı iletiye birden çok kez aracılık etmeyi reddeder ve yinelenen iletileri önlemek için yeniden denemede yararlı olur. Örneğin, bir istemci ackId=5 ile bir ileti gönderirse ve ackId=5 ile bir onay yanıtı alamazsa, istemci aynı iletiyi tekrar dener ve gönderir. Bazı durumlarda, ileti zaten aracılıdır ve bir nedenle onay yanıtı kaybolur. Hizmet, yeniden denemeyi reddeder ve Duplicate nedeni ile bir onay yanıtı verir.

Ack Yanıtı

Web PubSub Hizmeti, her istek için ackId ile bir ack yanıtı gönderir.

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

ackId isteği ilişkilendirir.
success bir bool değeridir ve isteğin hizmet tarafından başarıyla işlenip işlenmediğini gösterir. Eğer false ise, istemcilerin error'yi denetlemesi gerekir.
error yalnızca success olduğunda false ve istemcilerin farklı name için farklı mantığı olmalıdır. Gelecekte name türlerinin daha fazla olabileceğini düşünmelisiniz.
- Forbidden: İstemcinin istek için izni yok. İstemciye ilgili rollerin eklenmesi gerekiyor.
- InternalServerError: Hizmette bir iç hata oluştu. Yeniden deneme gereklidir.
- Duplicate: Aynı ileti ackId hizmet tarafından zaten işlenmiştir.

İzinler

Daha önceki PubSub WebSocket istemci açıklamasında büyük olasılıkla fark ettiğiniz gibi, bir istemci diğer istemcilere yalnızca yetkilendirildiğinde yayımlayabilir. Bir istemcinin izinleri, bağlantı kurulduğunda veya bağlantının ömrü boyunca verilebilir.

Rol	İzin
Belirtilmemiş	İstemci olay istekleri gönderebilir.
`webpubsub.joinLeaveGroup`	İstemci herhangi bir gruba katılabilir veya gruptan ayrılabilir.
`webpubsub.sendToGroup`	İstemci, iletileri herhangi bir gruba yayımlayabilir.
`webpubsub.joinLeaveGroup.<group>`	İstemci grubuna katılabilir veya gruptan `<group>`ayrılabilir.
`webpubsub.sendToGroup.<group>`	İstemci, `<group>` grubuna da ileti yayımlayabilir.
`webpubsub.joinLeaveGroups.<pattern>`	İstemci, adı `<pattern>` ile eşleşen herhangi bir gruba katılabilir veya gruptan ayrılabilir (bkz. Genel grup rolü desenleri).
`webpubsub.sendToGroups.<pattern>`	İstemci, adı eşleşen `<pattern>` herhangi bir gruba ileti yayımlayabilir (bkz. Joker karakter grubu rol desenleri).

bir istemcinin izni çeşitli yollarla verilebilir:

1. Erişim belirtecini oluştururken rolü istemciye atayın

İstemci bir JWT kullanarak hizmete bağlanabilir. Belirteç yükü, istemcininki role gibi bilgileri taşıyabilir. JWT'yi istemciye imzalarken, istemciye özel roller vererek istemciye izin vekleyebilirsiniz.

Örneğin, group1 ve group2 öğelerine ileti gönderme iznine sahip bir JWT imzalayalım:

let token = await serviceClient.getClientAccessToken({
    roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
});

2. Rolü olay işleyicisi ile istemciye atayın `connect`

İstemcilerin rolleri, olay işleyicisi kaydedildiğinde ayarlanabilir ve yukarı akış olay işleyicisi, connect olaylarını işlerken istemcinin roles verilerini Web PubSub hizmetine döndürebilir.

Örneğin, JavaScript'te olayı bunu yapacak şekilde yapılandırabilirsiniz handleConnect :

let handler = new WebPubSubEventHandler("hub1", {
  handleConnect: (req, res) => {
    // auth the connection and set the userId of the connection
    res.success({
      roles: [ "webpubsub.sendToGroup.group1", "webpubsub.sendToGroup.group2" ]
    });
  },
});

3. Çalışma zamanı sırasında REST API'leri veya sunucu SDK'ları aracılığıyla rolü istemciye atayın

let service = new WebPubSubServiceClient("<your_connection_string>", "test-hub");
await service.grantPermission("<connection_id>", "joinLeaveGroup", { targetName: "group1" });

Uyarı

REST API'leri veya sunucu SDK'ları aracılığıyla joker karakter rollerinin (örn webpubsub.sendToGroups.<pattern>. ) atanması henüz desteklenmemektedir. Bu özellik gelecekteki bir güncelleştirmede desteklenecektir.

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

Kılavuz: İstemci akışı için hizmet tarafından desteklenen bir alt protokol kullanma

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

Kılavuz: Olay dinleyicisini yapılandırma

Canlı demoları deneyin

Diğer Azure Web PubSub örneklerini keşfedin

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-01