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ç olarak /client/?hub={hub}&access_token={token}sorgu dizesinde veya üst bilgisinde Authorization olabilir Authorization: Bearer {token}.

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

1. İ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.
2. Uygulama sunucusu JWT'yi ve hizmet URL'sini istemciye döndürür.
3. İstemci, URL'yi ve uygulama sunucusundan döndürülen JWT belirtecini kullanarak Web PubSub hizmetine bağlanmaya çalışır.

Desteklenen talepler

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

Erişim belirtecine özel talepler de ekleyebilirsiniz ve bu değerler yukarı akış isteği gövdesine claimsbağlanma ö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 makrosna da 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')

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');

İstemciden bir gruba doğrudan katılma

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 , leaveGroupsendToGroup ve event iletileri için joinGroupözelliğini desteklerackId. kullanırken ackId, isteğiniz işlendiğinde bir yanıt iletisi alabilirsiniz. Yangın ve unut senaryolarında atlayabilirsiniz ackId . Makalede belirtme veya belirtme ackId arasındaki davranış farkları açıklanmaktadır.

No ackId belirtildiğinde davranış

Belirtilmezse ackId , bu ateş ve unutmadır. İletileri aracılık ederken hatalar olsa bile bildirim almanıza imkan yoktur.

Belirtildiğinde ackId davranış

Bir kez etkili 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 iletilerini kaydeder ve aynı ackId ileti olarak değerlendirilir. 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 ile ackId=5 bir ileti gönderirse ve ile ackId=5bir hata yanıtı alamazsa, istemci aynı iletiyi yeniden dener ve gönderir. Bazı durumlarda, ileti zaten aracılı ve bir nedenle ack yanıt kaybolur. Hizmet yeniden denemeyi reddeder ve bir hata yanıtını nedenle Duplicate yanıtlar.

Ack Yanıtı

Web PubSub Hizmeti ile ackIdher istek için 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>"
    }
}

• isteği ackId ilişkilendirir.

• success bir bool değeridir ve isteğin hizmet tarafından başarıyla işlenip işlenmediğini gösterir. buysa false, istemcilerin öğesini denetlemesi errorgerekir.

• erroryalnızca is false olduğunda success ve istemcilerin farklı nameiçin farklı mantığı olmalıdır. Gelecekte daha fazla türü name olabileceğini düşünmelisiniz.

  • Forbidden: İstemcinin istek için izni yok. İstemcinin ilgili roller eklenmesi gerekir.
  • 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.

bir istemcinin izni çeşitli yollarla verilebilir:

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

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

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

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

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

olay işleyicisi kaydedildiğinde ve yukarı akış olay işleyicisi olayları işlerken connect istemcinin Web PubSub hizmetine döndürebileceği roles durumlarda da istemcilerin connect rolleri ayarlanabilir.

Ö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" });

Sonraki adımlar

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