HTTP protokolü ile Azure Web PubSub olay işleyicisi için CloudEvents uzantısı

  • Makale

Web PubSub hizmeti, CloudEvents HTTP protokol bağlamasını kullanarak istemci olaylarını yukarı akış web kancasına teslim eder.

Web PubSub hizmetinden sunucuya gönderilen veriler her zaman CloudEvents binary biçimindedir.

Web kancası doğrulaması

Web kancası doğrulaması CloudEvents'i izler. İstek her zaman üst bilgide yer alır WebHook-Request-Origin: xxx.webpubsub.azure.com .

Yalnızca teslim hedefi olayların teslimine izin verirse ve ise, üst bilgiyi ekleyerek WebHook-Allowed-Origin isteği yanıtlamaSı GEREKİR, örneğin:

WebHook-Allowed-Origin: *

Veya:

WebHook-Allowed-Origin: xxx.webpubsub.azure.com

Şimdilik WebHook-Request-Rate ve WebHook-Request-Callback desteklenmez.

Web PubSub CloudEvents öznitelik uzantısı

Http belirtiminin artık uzantı HTTP üst bilgilerinin X- ön ekiyle önekli olmasını önermeyerek benzer bir desen izlediği de belirtildi.

Bu uzantı, Ürettiği her olay için Web PubSub tarafından kullanılan öznitelikleri tanımlar.

Özellikler

Adı Tür Açıklama Örnek
userId string Bağlantının kimlik doğrulaması yapılan kullanıcı
hub string Bağlantının ait olduğu hub
connectionId string connectionId, istemci bağlantısı için benzersizdir
eventName string Ön ek olmadan olayın adı
subprotocol string varsa istemcinin kullandığı alt protokol
connectionState string Bağlantının durumunu tanımlar. Durumun değerini sıfırlamak için aynı yanıt üst bilgisini kullanabilirsiniz. Birden çok connectionState üst bilgi kullanılamaz. Örneğin, bu özniteliği kullanarak karmaşık bir nesne geçirmek için içinde karmaşık karakterler içeriyorsa, base64(jsonString) base64 dize değerini kodlayın.
signature string Gelen isteğin beklenen kaynaktan olup olmadığını doğrulamak için yukarı akış web kancasının imzası. Hizmet, hem birincil erişim anahtarını hem de ikincil erişim anahtarını anahtar olarak HMAC kullanarak değeri hesaplar: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). Yukarı akış, işlemeden önce isteğin geçerli olup olmadığını denetlemelidir.

Ekinlikler

İki tür olay vardır. Biri, hizmetin olayın yanıtının devam etmesi için beklediği olayları engelliyor . Bunlardan biri, hizmetin bir sonraki iletiyi işlemeden önce bu tür bir olayın yanıtını beklemediği olayların engelini kaldırmaktır.

Sistem connect olayı

  • ce-type: azure.webpubsub.sys.connect
  • Content-Type: application/json

İstek biçimi:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connect
ce-source: /hubs/{hub}/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}
ce-eventName: connect

{
    "claims": {},
    "query": {},
    "headers": {},
    "subprotocols": [],
    "clientCertificates": [
        {
            "thumbprint": "<certificate SHA-1 thumbprint>",
            "content": "-----BEGIN CERTIFICATE-----\r\n...\r\n-----END CERTIFICATE-----"
        }
    ]
}

Başarılı yanıt biçimi:

  • Üst bilgi ce-connectionState: Bu üst bilgi varsa, bu bağlantının bağlantı durumu üst bilginin değerine güncelleştirilir. Bağlantı durumunu yalnızca engelleme olayları güncelleştirebilir. Aşağıdaki örnek, bağlantının karmaşık durumunu depolamak için base64 kodlanmış JSON dizesini kullanır.

  • Durum kodu:

    • 204: İçerik olmadan başarı.
    • 200: Başarılı, içerik aşağıdaki özelliklere izin verilen bir JSON biçimi olmalıdır:

      • subprotocols

        Olay, connect alt protokol ve kimlik doğrulama bilgilerini istemciden Yukarı Akış'a iletir. Web PubSub hizmeti, isteğin WebSocket protokolüne yükseltilip yükseltilmediğini belirlemek için durum kodunu kullanır.

        İstek özelliğini içeriyorsa subprotocols , sunucunun desteklediği bir altprotocol döndürmesi gerekir. Sunucu herhangi bir alt protokol kullanmak istemiyorsa, özelliği yanıt olarak göndermemelidir subprotocol. Boş üst bilgi göndermek geçersiz.

      • userId: {auth-ed user ID}

        Hizmet anonim bağlantılara izin verdiğinden connect , hizmete istemci bağlantısının kullanıcı kimliğini bildirmek olayın sorumluluğundadır. Hizmet, varsa yanıt yükünden userId kullanıcı kimliğini okur. Kullanıcı kimliği istek taleplerinden veya connect olayın yanıt yükünden okunamıyorsa bağlantı bırakılır.

      • groups: {groups to join}

        özelliği, kullanıcının bu bağlantıyı bir veya birden çok gruba eklemesi için kullanışlı bir yol sağlar. Bu şekilde, bu bağlantıyı bir gruba eklemek için başka bir çağrıya gerek yoktur.

      • roles: {roles the client has}

        özelliği, yukarı akış Web kancasının istemciyi yetkilendirmesi için bir yol sağlar. PubSub WebSocket istemcileri için ilk izinleri vermek için farklı roller vardır. İzinlerle ilgili ayrıntılar İstemci izinleri bölümünde açıklanmıştır.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "groups": [],
    "userId": "",
    "roles": [],
    "subprotocol": ""
}

Hata yanıtı biçimi:

  • 4xx: Hata, yukarı akıştan gelen yanıt, istemci isteği için yanıt olarak döndürülür.
HTTP/1.1 401 Unauthorized

Sistem connected olayı

İstemci WebSocket el sıkışmasını tamamladığında ve başarıyla bağlandığında hizmet Yukarı Akışı çağırır.

  • ce-type: azure.webpubsub.sys.connected
  • Content-Type: application/json
  • ce-connectionState: eyJrZXkiOiJhIn0=

İstek gövdesi boş JSON.

İstek biçimi:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.connected
ce-source: /hubs/{hub}/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}
ce-eventName: connected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{}

Yanıt biçimi:

2xx: başarı yanıtı.

connected zaman uyumsuz bir olaydır, yanıt durum kodu başarılı olmadığında hizmet bir hata kaydeder.

HTTP/1.1 200 OK

Sistem disconnected olayı

disconnectedbağlantı olayı durum kodu döndürürse 2xx istemci isteği tamamlandığında olay her zaman tetikler.

  • ce-type: azure.webpubsub.sys.disconnected
  • Content-Type: application/json

İstek biçimi:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/json; charset=utf-8
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.sys.disconnected
ce-source: /hubs/{hub}/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}
ce-eventName: disconnected
ce-subprotocol: abc
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "reason": "{Reason}"
}

  • reason

    , reason istemcinin bağlantısını kesme nedenini açıklar.

Yanıt biçimi:

2xx: başarı yanıtı.

disconnected zaman uyumsuz bir olaydır, yanıt durum kodu başarılı olmadığında hizmet bir hata kaydeder.

HTTP/1.1 200 OK

Basit WebSocket istemcileri için kullanıcı olayı message

Hizmet, her WebSocket ileti çerçevesi için olay işleyici yukarı akışını çağırır.

  • ce-type: azure.webpubsub.user.message
  • Content-Type: application/octet-stream ikili çerçeve için; text/plain metin çerçevesi için;

İstemcinin gönderdiği UserPayload değeridir.

İstek biçimi:

POST /upstream HTTP/1.1
Host: xxxxxx
WebHook-Request-Origin: xxx.webpubsub.azure.com
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn
ce-specversion: 1.0
ce-type: azure.webpubsub.user.message
ce-source: /hubs/{hub}/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}
ce-eventName: message
ce-connectionState: eyJrZXkiOiJhIn0=

UserPayload

Başarılı yanıt biçimi

  • Durum kodu
    • 204: İçerik olmadan başarı.
    • 200: Başarı, biçimi UserResponsePayload yanıtın biçimine Content-Type bağlıdır.
  • Content-Type: application/octet-stream ikili çerçeve için; text/plain metin çerçevesi için;
  • Üst bilgi Content-Type: application/octet-stream ikili çerçeve için; text/plain metin çerçevesi için;
  • Üst bilgi ce-connectionState: Bu üst bilgi varsa, bu bağlantının bağlantı durumu üst bilginin değerine güncelleştirilir. Bağlantı durumunu yalnızca engelleme olayları güncelleştirebilir. Aşağıdaki örnek, bağlantının karmaşık durumunu depolamak için base64 kodlanmış JSON dizesini kullanır.

Content-Type olduğundaapplication/octet-stream, hizmet WebSocket çerçevesini kullanarak binary istemciye gönderirUserResponsePayload. Content-Type olduğundatext/plain, hizmet WebSocket çerçevesini kullanarak text istemciye gönderirUserResponsePayload.

HTTP/1.1 200 OK
Content-Type: application/octet-stream (for binary frame) or text/plain (for text frame)
Content-Length: nnnn
ce-connectionState: eyJrZXkiOiJhIn0=

UserResponsePayload

Hata yanıtı biçimi

Durum kodu başarılı olmadığında hata yanıtı olarak kabul edilir. Yanıt durum kodu başarılı olmazsa message bağlantı bırakılır.

PubSub WebSocket istemcileri için kullanıcı özel olayı {custom_event}

Hizmet, geçerli her özel olay iletisi için olay işleyici web kancasını çağırır.

Olay 1: metin verileriyle olay gönderme:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "text",
    "data": "text data"
}

Yukarı akış olay işleyicisinin aşağıdaki gibi aldığı şey, Content-Type CloudEvents HTTP isteği text/plain için dataType=text

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

text data

Olay 2: JSON verileriyle olay gönderme:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "json",
    "data": {
        "hello": "world"
    },
}

Yukarı akış olay işleyicisinin aşağıdaki gibi aldığı şey, Content-Type CloudEvents HTTP isteği application/json için dataType=json

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>
ce-subprotocol: json.webpubsub.azure.v1
ce-connectionState: eyJrZXkiOiJhIn0=

{
    "hello": "world"
}

Olay 3: ikili verilerle olay gönderme:

{
    "type": "event",
    "event": "<event_name>",
    "dataType" : "binary",
    "data": "aGVsbG8gd29ybGQ=" // base64 encoded binary
}

Yukarı akış olay işleyicisinin aşağıdaki gibi aldığı şey, Content-Type CloudEvents HTTP isteği application/octet-stream için dataType=binary

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>
ce-subprotocol: json.webpubsub.azure.v1

<binary data>

Başarılı yanıt biçimi

HTTP/1.1 200 OK
Content-Type: application/octet-stream | text/plain | application/json
Content-Length: nnnn

UserResponsePayload
  • Durum kodu
    • 204: İçerik olmadan başarı.
    • 200: Başarılı, PubSub WebSocket istemcisine Content-Typeveri gönderme;
  • Üst bilgi ce-connectionState: Bu üst bilgi varsa, bu bağlantının bağlantı durumu üst bilginin değerine güncelleştirilir. Bağlantı durumunu yalnızca engelleme olayları güncelleştirebilir. Aşağıdaki örnek, bağlantının karmaşık durumunu depolamak için base64 kodlanmış JSON dizesini kullanır.
  • Üst bilgi Content-Type olduğunda application/octet-streamhizmet, base64 kodlanmış yük ile olduğu gibi binary kullanarak dataType istemciye geri gönderirUserResponsePayload. Örnek yanıt: 
    {
    "type": "message",
    "from": "server",
    "dataType": "binary",
    "data" : "aGVsbG8gd29ybGQ="
}
  • Content-Type olduğundatext/plain, hizmet yük dizesinde olduğu gibi text kullanarak dataType istemciye gönderirUserResponsePayload.
  • Content-Type olduğundaapplication/json, hizmet yanıt yükü gövdesi olarak değer belirteci ile kullanarak dataTypedatajson=istemciye gönderir.UserResponsePayload

Hata yanıtı biçimi

Durum kodu başarılı olmadığında hata yanıtı olarak kabul edilir. Yanıt durum kodu başarılı olmazsa {custom_event} bağlantı bırakılır.

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