Bagikan melalui

Referensi REST API sarana data Azure SignalR Service

Selain pola klien/server klasik, Azure SignalR Service menyediakan serangkaian REST API untuk membantu Anda mengintegrasikan fungsionalitas real-time ke dalam arsitektur tanpa server Anda.

Catatan

Azure SignalR Service mendukung penggunaan REST API hanya untuk mengelola klien yang terhubung melalui ASP.NET Core SignalR. Klien yang terhubung melalui ASP.NET SignalR menggunakan protokol data berbeda yang saat ini tidak didukung.

Arsitektur tanpa server umum dengan Azure Functions

Diagram berikut menunjukkan arsitektur tanpa server khas yang menggunakan Azure SignalR Service dengan Azure Functions.

Diagram arsitektur tanpa server khas untuk Azure SignalR Service.

  • Fungsi ini negotiate mengembalikan respons negosiasi dan mengalihkan semua klien ke Azure SignalR Service.
  • Fungsi ini broadcast memanggil REST API untuk Azure SignalR Service. Azure SignalR Service menyiarkan pesan ke semua klien yang terhubung.

Dalam arsitektur tanpa server, klien memiliki koneksi persisten ke Azure SignalR Service. Karena tidak ada server aplikasi untuk menangani lalu lintas, klien dalam LISTEN mode. Dalam mode tersebut, klien dapat menerima pesan tetapi tidak dapat mengirim pesan. Azure SignalR Service memutuskan sambungan klien apa pun yang mengirim pesan karena merupakan operasi yang tidak valid.

Anda dapat menemukan sampel lengkap menggunakan Azure SignalR Service dengan Azure Functions di repositori GitHub ini.

Menerapkan titik akhir negosiasi

Anda harus menerapkan negotiate fungsi yang mengembalikan respons negosiasi pengalihan sehingga klien dapat terhubung ke layanan.

Respons negosiasi umum memiliki format ini:

{
  "url": "https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
  "accessToken": "<a typical JWT>"
}

Nilai accessToken dihasilkan melalui algoritma yang sama yang dijelaskan di bagian autentikasi. Satu-satunya perbedaan adalah bahwa aud klaim harus sama dengan url.

Anda harus menghosting API https://<hub_url>/negotiate negosiasi Anda sehingga Anda masih dapat menggunakan klien SignalR untuk terhubung ke URL hub. Baca selengkapnya tentang mengalihkan klien ke Azure SignalR Service di Koneksi klien.

Versi REST API

Tabel berikut menunjukkan semua versi REST API yang didukung. Ini juga menyediakan file Swagger untuk setiap versi API.

versi API Status Port Dokumentasi Spesifikasi
20220601 terbaru Standard Artikel File Swagger
1.0 Stabil Standard Artikel File Swagger
1.0-preview Kedaluwarsa Standard Artikel File Swagger

Tabel berikut mencantumkan API yang tersedia.

API Jalur
Menyiarkan pesan ke semua klien yang tersambung ke hub target POST /api/v1/hubs/{hub}
Menyiarkan pesan ke semua klien milik pengguna target POST /api/v1/hubs/{hub}/users/{id}
Mengirim pesan ke koneksi tertentu POST /api/v1/hubs/{hub}/connections/{connectionId}
Periksa apakah koneksi dengan connectionId yang diberikan ada GET /api/v1/hubs/{hub}/connections/{connectionId}
Tutup koneksi klien DELETE /api/v1/hubs/{hub}/connections/{connectionId}
Menyiarkan pesan ke semua klien dalam grup target POST /api/v1/hubs/{hub}/groups/{group}
Periksa apakah ada koneksi klien di dalam grup yang diberikan GET /api/v1/hubs/{hub}/groups/{group}
Periksa apakah ada koneksi klien yang tersambung untuk pengguna tertentu GET /api/v1/hubs/{hub}/users/{user}
Menambahkan koneksi ke grup target PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Menghapus koneksi dari grup target DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}
Memeriksa apakah pengguna ada di grup target GET /api/v1/hubs/{hub}/groups/{group}/users/{user}
Menambahkan pengguna ke grup target PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}
Menghapus pengguna dari grup target DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}
Hapus pengguna dari semua grup DELETE /api/v1/hubs/{hub}/users/{user}/groups

Menggunakan REST API

Autentikasi melalui AccessKey di Azure SignalR Service

Di setiap permintaan HTTP, header otorisasi dengan JSON Web Token (JWT) diperlukan untuk mengautentikasi dengan Azure SignalR Service.

Algoritma penandatanganan dan tanda tangan

HS256, yaitu HMAC-SHA256, digunakan sebagai algoritma penandatanganan.

AccessKey Gunakan nilai dalam string koneksi instans Azure SignalR Service untuk menandatangani JWT yang dihasilkan.

Klaim

Klaim berikut harus disertakan dalam JWT.

Jenis klaim Diperlukan Deskripsi
aud true Harus sama dengan URL permintaan HTTP Anda, tidak termasuk parameter garis miring dan kueri berikutnya. Misalnya, audiens permintaan siaran akan terlihat seperti: https://example.service.signalr.net/api/v1/hubs/myhub.
exp true Waktu epoch ketika token ini kedaluwarsa.

Autentikasi melalui token Microsoft Entra

Mirip dengan mengautentikasi melalui AccessKey, JWT diperlukan untuk mengautentikasi permintaan HTTP dengan menggunakan token Microsoft Entra.

Perbedaannya adalah bahwa dalam skenario ini, MICROSOFT Entra ID menghasilkan JWT. Untuk informasi selengkapnya, lihat Mempelajari cara membuat token Microsoft Entra.

Cakupan kredensial yang digunakan harus https://signalr.azure.com/.default.

Anda juga dapat menggunakan kontrol akses berbasis peran (RBAC) untuk mengotorisasi permintaan dari klien atau server Anda ke Azure SignalR Service. Untuk informasi selengkapnya, lihat Mengotorisasi akses dengan ID Microsoft Entra untuk Azure SignalR Service.

Untuk memanggil REST API terkait pengguna, masing-masing klien Anda harus mengidentifikasi diri mereka ke Azure SignalR Service. Jika tidak, Azure SignalR Service tidak dapat menemukan koneksi target dari ID pengguna.

Anda dapat mencapai identifikasi klien dengan menyertakan nameid klaim di JWT setiap klien saat terhubung ke Azure SignalR Service. Azure SignalR Service kemudian menggunakan nilai nameid klaim sebagai ID pengguna untuk setiap koneksi klien.

Sampel

Dalam repositori GitHub ini, Anda dapat menemukan aplikasi konsol lengkap untuk menunjukkan cara membuat permintaan HTTP REST API secara manual di Azure SignalR Service.

Anda juga dapat menggunakan Microsoft.Azure.SignalR.Management untuk menerbitkan pesan ke Azure SignalR Service dengan menggunakan antarmuka serupa dari IHubContext. Anda dapat menemukan sampel di repositori GitHub ini. Untuk informasi selengkapnya, lihat Azure SignalR Service Management SDK.

Batasan

Saat ini, permintaan REST API memiliki batasan berikut:

  • Ukuran header adalah maksimum 16 KB.
  • Ukuran tubuh maksimal 1 MB.

Jika Anda ingin mengirim pesan yang lebih besar dari 1 MB, gunakan SDK Manajemen Layanan dengan persistent mode.

  • Last updated on