Azure Web PubSub tarafından desteklenen protobuf WebSocket altprotocol

Bu belgede altprotocol açıklanmaktadır protobuf.webpubsub.azure.v1.

İstemci bu altprotokolü kullandığında, hem giden hem de gelen veri çerçevelerinin protokol arabellekleri (protobuf) yükleri olması beklenir.

Genel bakış

Altprotocol protobuf.webpubsub.azure.v1 , istemciyi yukarı akış sunucusuna gidiş dönüş yapmak yerine doğrudan yayımlama-abone olma (PubSub) gerçekleştirmesini sağlar. Altprotocol ile protobuf.webpubsub.azure.v1 WebSocket bağlantısı PubSub WebSocket istemcisi olarak adlandırılır.

Örneğin, JavaScript'te aşağıdakileri kullanarak protobuf altprotokolü ile 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');

Basit bir WebSocket istemcisi için sunucu, istemcilerden gelen olayları işlemek için gerekli role sahiptir. Basit bir WebSocket bağlantısı her zaman ileti gönderdiğinde bir message olayı tetikler ve iletileri işlemek ve diğer işlemleri yapmak için her zaman sunucu tarafına dayanır. Altprotocol'un protobuf.webpubsub.azure.v1 yardımıyla, yetkili bir istemci birleştirme isteklerini kullanarak bir gruba katılabilir ve doğrudan yayımlama isteklerini kullanarak iletileri bir gruba yayımlayabilir. İstemci ayrıca, iletinin ait olduğu olayı özelleştirmek için olay isteklerini kullanarak iletileri çeşitli yukarı akış olay işleyicilerine yönlendirebilir.

Not

Şu anda Web PubSub hizmeti yalnızca proto3'i destekler.

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

Not

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

Tüm istek iletileri aşağıdaki protobuf biçimine uyar:

syntax = "proto3";

import "google/protobuf/any.proto";

message UpstreamMessage {
    oneof message {
        SendToGroupMessage send_to_group_message = 1;
        EventMessage event_message = 5;
        JoinGroupMessage join_group_message = 6;
        LeaveGroupMessage leave_group_message = 7;
        SequenceAckMessage sequence_ack_message = 8;
        PingMessage ping_message = 9;
    }

    message SendToGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
        MessageData data = 3;
    }

    message EventMessage {
        string event = 1;
        MessageData data = 2;
        optional uint64 ack_id = 3;
    }
    
    message JoinGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
    }

    message LeaveGroupMessage {
        string group = 1;
        optional uint64 ack_id = 2;
    }

    message PingMessage {
    }
}

message MessageData {
    oneof data {
        string text_data = 1;
        bytes binary_data = 2;
        google.protobuf.Any protobuf_data = 3;
    }
}

Grupları birleştirme

Biçim:

Grup adına ayarlayın join_group_message.group .

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. Daha fazla ayrıntı AckId ve Ack Yanıtı'nda bulunabilir

Grup bırakma

Biçim:

Grup adına ayarlayın leave_group_message.group .

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. Daha fazla ayrıntı AckId ve Ack Yanıtı'nda bulunabilir

İletileri yayımlama

Biçim:

ackId: Her isteğin benzersiz kimliği. Hizmet, isteğin işlem sonucunu bildirmek için bir hata yanıtı iletisi gönderir. Daha fazla ayrıntı AckId ve Ack Yanıtı'nda bulunabilir
dataType: , veya protobuf içindekine bağlı textbinary olarak veri dataMessageDatabiçimi. Alıcı istemciler, içeriği doğru şekilde işlemek için kullanabilir dataType .
protobuf: ayarladığınızda send_to_group_message.data.protobuf_dataörtük dataType değeridir protobuf. protobuf_dataherhangi bir ileti türünde olabilir. Diğer tüm istemciler protobuf sdk'sı tarafından seri durumdan çıkarılabilen protobuf kodlu bir ikili dosya alır. Yalnızca metin tabanlı içeriği destekleyen istemciler (örneğin, json.webpubsub.azure.v1) Base64 ile kodlanmış bir ikili alır.
text: ayarladığınızda send_to_group_message.data.text_dataörtük dataType değeridir text. text_data bir dize olmalıdır. Diğer protokollere sahip tüm istemciler UTF-8 ile kodlanmış bir dize alır.
binary: ayarladığınızda send_to_group_message.data.binary_dataörtük dataType değeridir binary. binary_data bir bayt dizisi olmalıdır. Diğer protokollere sahip tüm istemciler, protobuf kodlaması olmadan bir ham ikili alır. Yalnızca metin tabanlı içeriği destekleyen istemciler (örneğin, json.webpubsub.azure.v1) Base64 ile kodlanmış bir ikili alır.

Olay 1: Metin verilerini yayımlama

olarak send_to_group_message.groupayarlayın group ve olarak send_to_group_message.data.text_dataayarlayın"text data".

Gruptaki group protobuf altprotocol istemcisi ikili çerçeveyi alır ve seri durumdan çıkarmak için DownstreamMessage kullanabilir.

içindeki JSON altprotocol istemcileri group :

{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "text",
    "data" : "text data"
}

içindeki basit WebSocket istemcileri group dizesini text dataalır.

Olay 2: Protobuf verilerini yayımlama

Özel bir iletiniz olduğunu varsayalım:

message MyMessage {
    int32 value = 1;
}

ile send_to_group_message.groupolarak group ve send_to_group_message.data.protobuf_data olarak Any.pack(MyMessage) ayarlayınvalue = 1.

içindeki group protobuf altprotocol istemcileri ikili çerçeveyi alır ve seri durumdan çıkarmak için DownstreamMessage kullanabilir.

içindeki group altprotocol istemcisi şu değerleri alır:

{
    "type": "message",
    "from": "group",
    "group": "G",
    "dataType" : "protobuf",
    "data" : "Ci90eXBlLmdvb2dsZWFwaXMuY29tL2F6dXJlLndlYnB1YnN1Yi5UZXN0TWVzc2FnZRICCAE=" // Base64-encoded bytes
}

Not

Veriler Base64 kodlanmış, seri durumdan çıkarılabilir bir protobuf ikili dosyasıdır.

Aşağıdaki protobuf tanımını kullanabilir ve seri durumdan çıkarmak için kullanabilirsiniz Any.unpack() :

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

içindeki group basit WebSocket istemcileri ikili çerçeveyi alır:

# Show in hexadecimal
0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01

Olay 3: İkili verileri yayımlama

olarak send_to_group_message.groupayarlayın group ve olarak send_to_group_message.data.binary_dataayarlayın[1, 2, 3].

Gruptaki group protobuf altprotocol istemcisi ikili çerçeveyi alır ve seri durumdan çıkarmak için DownstreamMessage kullanabilir.
Gruptaki group JSON altprotocol istemcisi aşağıdakileri alır:
```
{
    "type": "message",
    "from": "group",
    "group": "group",
    "dataType" : "binary",
    "data" : "AQID", // Base64-encoded [1,2,3]
}
```
JSON altprotocol istemcisi yalnızca metin tabanlı mesajlaşmayı desteklediğinden, ikili her zaman Base64 kodludur.
içindeki group basit WebSocket istemcileri ikili çerçevedeki ikili verileri alır:
```
# Show in hexadecimal
01 02 03
```

Özel olaylar gönderme

Ayarladığınıza bağlı olarak dataType , protobufveya textolabilir binaryörtük dataTypebir vardır. Alıcı istemcileri, içeriği doğru şekilde işlemek için kullanabilir dataType .

protobuf: ayarladığınızda event_message.data.protobuf_dataörtük dataType değeridir protobuf. Değer protobuf_data desteklenen herhangi bir protobuf türü olabilir. Olay işleyicisi, herhangi bir protobuf SDK'sı tarafından seri durumdan çıkarılabilen protobuf kodlu ikili dosyasını alır.
text: ayarladığınızda event_message.data.text_dataörtük dataType değeridir text. Değer text_data bir dize olmalıdır. Olay işleyicisi UTF-8 kodlu bir dize alır.
binary: ayarladığınızda event_message.data.binary_dataörtük dataType değeridir binary. Değer binary_data bir bayt dizisi olmalıdır. Olay işleyicisi ham ikili çerçeveyi alır.

1. Olay: Metin verileriyle olay gönderme

event_message.data.text_data seçeneğini "text data" olarak ayarlayın.

Yukarı akış olay işleyicisi şuna benzer bir istek 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 , burada şeklindedirtext/plaindataType=text.

Olay 2: Protobuf verileriyle olay gönderme

Aşağıdaki müşteri iletisini aldığınızı varsayın:

message MyMessage {
    int32 value = 1;
}

ile olarak event_message.data.protobuf_data ayarlayın any.pack(MyMessage)value = 1

Yukarı akış olay işleyicisi şuna benzer bir istek 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>

// Just show in hexadecimal; read it as binary
0A 2F 74 79 70 65 2E 67 6F 6F 67 6C 65 61 70 69 73 2E 63 6F 6D 2F 61 7A 75 72 65 2E 77 65 62 70 75 62 73 75 62 2E 54 65 73 74 4D 65 73 73 61 67 65 12 02 08 01

Content-Type CloudEvents HTTP isteği için , burada şeklindedirapplication/x-protobufdataType=protobuf.

Veriler geçerli bir protobuf ikili dosyasıdır. Seri durumdan çıkarmak için aşağıdakileri proto ve any.unpack() kullanabilirsiniz:

syntax = "proto3";

message MyMessage {
    int32 value = 1;
}

Olay 3: İkili verilerle olay gönderme

send_to_group_message.binary_data seçeneğini [1, 2, 3] olarak ayarlayın.

Yukarı akış olay işleyicisi şuna benzer bir istek 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>

// Just show in hexadecimal; you need to read it as binary
01 02 03

dataType için=binaryContent-Type, CloudEvents HTTP isteği için şeklindedir.application/octet-stream WebSocket çerçevesi, metin iletisi çerçeveleri text için biçiminde veya ileti çerçeveleri için UTF-8 kodlu ikililer biçiminde binary olabilir.

İleti belirtilen biçimle eşleşmiyorsa hizmet istemciyi reddeder.

Ping

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

Yanıtlar

Tüm yanıt iletileri aşağıdaki protobuf biçimine uyar:

message DownstreamMessage {
    oneof message {
        AckMessage ack_message = 1;
        DataMessage data_message = 2;
        SystemMessage system_message = 3;
        PongMessage pong_message = 4;
    }
    
    message AckMessage {
        uint64 ack_id = 1;
        bool success = 2;
        optional ErrorMessage error = 3;
    
        message ErrorMessage {
            string name = 1;
            string message = 2;
        }
    }

    message DataMessage {
        string from = 1;
        optional string group = 2;
        MessageData data = 3;
    }

    message SystemMessage {
        oneof message {
            ConnectedMessage connected_message = 1;
            DisconnectedMessage disconnected_message = 2;
        }
    
        message ConnectedMessage {
            string connection_id = 1;
            string user_id = 2;
        }

        message DisconnectedMessage {
            string reason = 2;
        }
    }

    message PongMessage {
    }
}

İstemci tarafından alınan iletiler şu üç türden birinde olabilir: ack, messageveya systempong.

Ack yanıtı

İstek içeriyorsa ackId, hizmet bu istek için bir hata yanıtı döndürür. İstemci uygulaması aşağıdakiler dahil olmak üzere bu ack mekanizmasını işlemelidir:

İşlem asyncawait için ack yanıtı bekleniyor.
Belirli bir süre boyunca ack yanıtının alınmadığında zaman aşımı denetimi yapılması.

İstemci uygulaması her zaman önce durumunun successtrue veya falseolup olmadığını denetlemelidir. success durum olduğundafalse, istemci hata ayrıntıları için özelliğinden error okuyabilir.

İleti yanıtı

İstemciler, istemcinin katıldığı bir gruptan yayımlanan iletileri alabilir. Ya da sunucu belirli bir istemciye veya belirli bir kullanıcıya ileti gönderdiğinde sunucu yönetim rolünden iletiler alabilirler.

Aşağıdaki senaryolarda her zaman bir DownstreamMessage.DataMessage ileti alırsınız:

İleti bir gruptan olduğunda, from şeklindedir group. İleti sunucudan olduğunda, from şeklindedir server.
İleti bir gruptan geldiğinde, group grup adıdır.

Gönderenler dataType aşağıdaki iletilerden birinin gönderilmesine neden olur:

ise dataTypetextkullanın message_response_message.data.text_data.
ise dataTypebinarykullanın message_response_message.data.binary_data.
ise dataTypeprotobufkullanın message_response_message.data.protobuf_data.
ise dataTypejsonkullanın message_response_message.data.text_datave içerik serileştirilmiş bir JSON dizesidir.

Sistem yanıtı

Web PubSub hizmeti, istemciye sistemle ilgili yanıtlar da gönderebilir.

Bağlandı

İstemci hizmete bağlandığında bir DownstreamMessage.SystemMessage.ConnectedMessage ileti alırsınız.

Bağlantı kesildi

Sunucu bağlantıyı kapattığında veya hizmet istemciyi reddettiyse bir DownstreamMessage.SystemMessage.DisconnectedMessage ileti alırsınız.

Pong yanıtı

Web PubSub hizmeti, istemciden bir PongMessage aldığında istemciye bir PingMessage gönderir.

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 protobuf WebSocket altprotocol

Genel bakış

İzinler

İstekler

Grupları birleştirme

Grup bırakma

İletileri yayımlama

Olay 1: Metin verilerini yayımlama

Olay 2: Protobuf verilerini yayımlama

Olay 3: İkili verileri yayımlama

Özel olaylar gönderme

1. Olay: Metin verileriyle olay gönderme

Olay 2: Protobuf verileriyle olay gönderme

Olay 3: İkili verilerle olay gönderme

Ping

Yanıtlar

Ack yanıtı

İleti yanıtı

Sistem yanıtı

Bağlandı

Bağlantı kesildi

Pong yanıtı

Sonraki adımlar

Geri Bildirim

Ek kaynaklar