Ekstensi CloudEvents untuk penanganan aktivitas Azure Web PubSub dengan protokol HTTP

Layanan Web PubSub mengirimkan peristiwa klien ke webhook upstream menggunakan pengikatan protokol HTTP CloudEvents.

Data yang dikirim dari layanan Web PubSub ke server selalu dalam format CloudEvents binary .

• Validasi Webhook
• Ekstensi atribut Web PubSub CloudEvents
• Peristiwa
  • Memblokir peristiwa
    • Peristiwa sistemconnect
    • Peristiwa pengguna
  • Membuka blokir peristiwa
    • Peristiwa sistemconnected
    • Peristiwa sistemdisconnected

Validasi Webhook

Validasi Webhook mengikuti CloudEvents. Permintaan selalu berisi WebHook-Request-Origin: xxx.webpubsub.azure.com di header.

Jika dan hanya jika target pengiriman mengizinkan pengiriman peristiwa, itu HARUS membalas permintaan dengan menyertakan header WebHook-Allowed-Origin, misalnya:

WebHook-Allowed-Origin: *

Atau:

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

Untuk saat ini, WebHook-Request-Rate dan WebHook-Request-Callback tidak didukung.

Ekstensi atribut Web PubSub CloudEvents

Juga dicatat bahwa spesifikasi HTTP sekarang mengikuti pola yang sama dengan tidak lagi menyarankan bahwa header HTTP ekstensi diawali dengan X-.

Ekstensi ini mendefinisikan atribut yang digunakan oleh Web PubSub untuk setiap peristiwa yang dibuat.

Atribut

Nama	Tipe	Deskripsi	Contoh
userId	string	Pengguna koneksi authed
hub	string	Hub tempat koneksi berada
connectionId	string	ConnectionId unik untuk koneksi klien
eventName	string	Nama peristiwa tanpa awalan
subprotocol	string	Subprotokol yang digunakan klien jika ada
connectionState	string	Mendefinisikan status untuk koneksi. Anda dapat menggunakan header respons yang sama untuk mengatur ulang nilai status. Beberapa connectionState header tidak diperbolehkan. Lakukan base64 mengodekan nilai string jika berisi karakter kompleks di dalamnya, misalnya, base64(jsonString) untuk meneruskan objek kompleks menggunakan atribut ini.
signature	string	Tanda tangan untuk webhook upstram untuk memvalidasi apakah permintaan yang masuk berasal dari asal yang diharapkan. Layanan menghitung nilai menggunakan kunci akses utama dan kunci akses sekunder sebagai HMAC kunci: Hex_encoded(HMAC_SHA256(accessKey, connectionId)). Upstram harus memeriksa apakah permintaan itu valid sebelum memprosesnya.

Peristiwa

Ada dua jenis peristiwa. Salah satunya adalah memblokir peristiwa bahwa layanan menunggu respons acara berlanjut. Satu membuka blokir peristiwa yang respons peristiwa tersebut tidak ditunggu oleh layanan sebelum memproses pesan berikutnya.

• Memblokir peristiwa
  • Peristiwa sistemconnect
  • Peristiwa pengguna
• Membuka blokir peristiwa
  • Peristiwa sistemconnected
  • Peristiwa sistemdisconnected

Peristiwa connect sistem

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

Format permintaan:

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": "ABC"
        }
    ]
}

Format respons keberhasilan:

• Header ce-connectionState: Jika header ini ada, status koneksi dari koneksi ini akan diperbarui ke nilai header. Hanya peristiwa pemblokiran yang dapat memperbarui status koneksi. Sampel di bawah ini menggunakan string JSON yang dikodekan base64 untuk menyimpan status kompleks untuk koneksi.

• Kode status:

  • 204: Sukses, tanpa konten.
  • 200: Berhasil, konten HARUS berupa format JSON, dengan properti berikut diizinkan:

    • subprotocols

      Peristiwa connect meneruskan informasi subprotokol dan autentikasi ke Upstram dari klien. Layanan Web PubSub menggunakan kode status untuk menentukan apakah permintaan akan ditingkatkan ke protokol WebSocket.

      Jika permintaan berisi properti subprotocols, server harus menampilkan satu subprotokol yang didukungnya. Jika server tidak ingin menggunakan subprotokol apa pun, server seharusnya tidak mengirim properti subprotocol sebagai respons. Mengirim header kosong tidak valid.

    • userId: {auth-ed user ID}

      Karena layanan ini memungkinkan koneksi anonim, ini adalah tanggung jawab peristiwa connect untuk memberi tahu layanan ID pengguna koneksi klien. Layanan membaca ID pengguna dari payload userId respons jika ada. Koneksi dihilangkan jika ID pengguna tidak dapat dibaca dari klaim permintaan atau connect payload respons peristiwa.

    • groups: {groups to join}

      Properti ini menyediakan cara yang nyaman bagi pengguna untuk menambahkan koneksi ini ke satu atau beberapa grup. Dengan cara ini, tidak perlu memiliki panggilan lain untuk menambahkan koneksi ini ke beberapa grup.

    • roles: {roles the client has}

      Properti menyediakan cara bagi Webhook hulu untuk mengotorisasi klien. Ada berbagai peran untuk memberikan izin awal untuk klien WebSocket PubSub. Detail tentang izin dijelaskan dalam Izin klien.

HTTP/1.1 200 OK
ce-connectionState: eyJrZXkiOiJhIn0=

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

Format respons kesalahan:

• 4xx: Kesalahan, respons dari Upstram akan ditampilkan sebagai respons atas permintaan klien.

HTTP/1.1 401 Unauthorized

Peristiwa connected sistem

Layanan ini memanggil Upstram saat klien menyelesaikan jabat tangan WebSocket dan berhasil terhubung.

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

Badan permintaan adalah JSON kosong.

Format permintaan:

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=

{}

Format respons:

2xx: respons berhasil.

connected adalah peristiwa asinkron, ketika kode status respons tidak berhasil, layanan mencatat kesalahan.

HTTP/1.1 200 OK

Peristiwa disconnected sistem

Peristiwa disconnectedselalu dipicu saat permintaan klien selesai jika peristiwa sambungkan menampilkan kode status 2xx.

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

Format permintaan:

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 menjelaskan alasan koneksi klien terputus.

Format respons:

2xx: respons berhasil.

disconnected adalah peristiwa asinkron, ketika kode status respons tidak berhasil, layanan mencatat kesalahan.

HTTP/1.1 200 OK

Peristiwa pengguna message untuk klien WebSocket sederhana

Layanan ini memanggil upstram penanganan peristiwa untuk setiap bingkai pesan WebSocket.

• ce-type: azure.webpubsub.user.message
• Content-Type: application/octet-stream untuk bingkai biner; text/plain untuk bingkai teks;

UserPayload adalah apa yang dikirim klien.

Format permintaan:

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

Format respons keberhasilan

• Kode status
  • 204: Sukses, tanpa konten.
  • 200: Sukses, format UserResponsePayload bergantung pada Content-Type respons.
• Content-Type: application/octet-stream untuk bingkai biner; text/plain untuk bingkai teks;
• Header Content-Type: application/octet-stream untuk bingkai biner; text/plain untuk bingkai teks;
• Header ce-connectionState: Jika header ini ada, status koneksi dari koneksi ini akan diperbarui ke nilai header. Hanya peristiwa pemblokiran yang dapat memperbarui status koneksi. Sampel di bawah ini menggunakan untaian JSON dikodekan base64 untuk menyimpan status kompleks untuk koneksi.

Saat Content-Type adalah application/octet-stream, layanan mengirimkan UserResponsePayload ke klien menggunakan binary bingkai WebSocket. Saat Content-Type adalah text/plain, layanan mengirimkan UserResponsePayload ke klien menggunakan text bingkai WebSocket.

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

Format respons kesalahan

Ketika kode status tidak berhasil, kode tersebut dianggap sebagai respons kesalahan. Koneksi akan diputuskan jika message kode status respons tidak berhasil.

Peristiwa kustom pengguna {custom_event} untuk klien PubSub WebSocket

Layanan ini memanggil webhook penanganan peristiwa untuk setiap pesan peristiwa kustom yang valid.

Kasus 1: mengirim peristiwa dengan data teks:

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

Apa yang diterima oleh penanganan aktivitas upstream seperti di bawah ini, Content-Type untuk permintaan HTTP CloudEvents adalah text/plain untuk 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

Kasus 2: mengirim peristiwa dengan data JSON:

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

Apa yang diterima oleh penanganan aktivitas upstream seperti di bawah ini, Content-Type untuk permintaan HTTP CloudEvents adalah application/json untuk 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"
}

Kasus 3: mengirim peristiwa dengan data biner:

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

Apa yang diterima oleh penanganan aktivitas upstream seperti di bawah ini, Content-Type untuk permintaan HTTP CloudEvents adalah application/octet-stream untuk 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>

Format respons keberhasilan

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

UserResponsePayload

• Kode status
  • 204: Sukses, tanpa konten.
  • 200: Keberhasilan, pengiriman data ke klien PubSub WebSocket tergantung pada Content-Type;
• Header ce-connectionState: Jika header ini ada, status koneksi dari koneksi ini akan diperbarui ke nilai header. Hanya peristiwa pemblokiran yang dapat memperbarui status koneksi. Sampel di bawah ini menggunakan string JSON yang dikodekan base64 untuk menyimpan status kompleks untuk koneksi.
• Jika Header Content-Type adalah application/octet-stream, layanan akan mengirim UserResponsePayload kembali ke klien menggunakan dataType sebagai binary dengan payload base64 dienkode. Contoh respons:

  {
      "type": "message",
      "from": "server",
      "dataType": "binary",
      "data" : "aGVsbG8gd29ybGQ="
  }
  

• Content-Type Ketika adalah text/plain, layanan mengirim UserResponsePayload ke klien menggunakan dataType sebagai text dengan string payload.
• Saat Content-Type adalah application/json, layanan mengirimkan UserResponsePayload ke klien menggunakan dataType=json dengan token nilai data sebagai badan payload respons.

Format respons kesalahan

Ketika kode status tidak berhasil, kode tersebut dianggap sebagai respons kesalahan. Koneksi akan diputuskan jika {custom_event} kode status respons tidak berhasil.

Langkah berikutnya

Gunakan sumber daya ini untuk mulai membangun aplikasi Anda sendiri:

Tutorial: Menerbitkan dan berlangganan pesan di Azure Web PubSub

Tutorial: Membuat ruang obrolan sederhana dengan Azure Web PubSub

Tutorial: Menggunakan subprotokola yang didukung layanan untuk streaming klien

Tutorial: Bangun obrolan tanpa server dengan Azure Functions dan Web PubSub

Tutorial: Mengonfigurasi pendengar peristiwa

Bermain dengan demo langsung

Jelajahi sampel Azure Web PubSub lainnya