Bagikan melalui

Pengikatan input SignalR Service untuk Azure Functions

Sebelum klien dapat terhubung ke Azure SignalR Service, klien harus mengambil URL titik akhir layanan dan token akses yang valid. Pengikatan input SignalRConnectionInfo menghasilkan URL titik akhir SignalR Service dan token valid yang digunakan untuk terhubung ke layanan. Token terbatas waktu dan dapat digunakan untuk mengautentikasi pengguna tertentu ke koneksi. Oleh karena itu, Anda tidak boleh menyimpan token atau membagikannya di antara klien. Biasanya Anda menggunakan SignalRConnectionInfo dengan pemicu HTTP bagi klien untuk mengambil informasi koneksi.

Untuk informasi selengkapnya tentang cara menggunakan pengikatan ini untuk membuat fungsi "negosiasi" yang kompatibel dengan SDK klien SignalR, lihat Pengembangan dan konfigurasi Azure Functions dengan Azure SignalR Service.

Ketika tidak dideklarasikan secara eksplisit, asumsikan bahwa contoh menggunakan nilai pengaturan koneksi default dari AzureSignalRConnectionString. Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.

Contoh

Anda dapat membuat fungsi C# dengan menggunakan salah satu mode C# berikut:

  • Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi dukungan jangka panjang (LTS) dan non-LTS untuk .NET dan .NET Framework.
  • Model dalam proses: Fungsi C# terkompilasi yang berjalan dalam proses yang sama dengan runtime Azure Functions.
  • Skrip C#: Digunakan terutama saat Anda membuat fungsi C# di portal Azure.

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

Contoh berikut menunjukkan fungsi C# yang memperoleh informasi koneksi SignalR menggunakan pengikatan input dan mengembalikannya melalui HTTP.

[Function(nameof(Negotiate))]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "serverless")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

Contoh berikut menunjukkan pengikatan input info koneksi SignalR pada file function.json dan fungsi yang menggunakan pengikatan untuk mengembalikan informasi koneksi.

Berikut contoh data pengikatan di file function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Berikut kode JavaScript:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

Contoh PowerShell lengkap sedang tertunda.

Contoh berikut menunjukkan input info koneksi SignalR yang mengikat pada file function.json dan fungsi Python yang menggunakan pengikatan untuk mengembalikan informasi koneksi.

Berikut adalah kode Python:

def main(req: func.HttpRequest, connectionInfoJson: str) -> func.HttpResponse:
    return func.HttpResponse(
        connectionInfoJson,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

Contoh berikut menunjukkan fungsi Java yang memperoleh informasi koneksi SignalR menggunakan pengikatan input dan mengembalikannya melalui HTTP.

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk menentukan fungsi. Sebagai gantinya, skrip C# menggunakan file konfigurasi function.json.

Tabel berikut menjelaskan properti atribut SignalRConnectionInfoInput:

Properti atribut Deskripsi
HubName Harus diisi. Nama hub.
ConnectionStringSetting Nama pengaturan aplikasi atau kumpulan pengaturan yang berisi string koneksi SignalR Service, yang default ke AzureSignalRConnectionString.
UserId Opsional. Pengidentifikasi pengguna koneksi SignalR. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
IdToken Opsional. JWT yang klaimnya akan ditambahkan ke klaim pengguna. Ini harus digunakan bersama dengan ClaimTypeList. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
ClaimTypeList Opsional. Daftar jenis klaim, yang memfilter klaim di IdToken .

Anotasi

Tabel berikut menjelaskan pengaturan yang didukung untuk anotasi SignalRConnectionInfoInput.

Pengaturan Deskripsi
nama Nama variabel yang digunakan dalam kode fungsi untuk objek info koneksi.
hubName Harus diisi. Nama hub.
connectionStringSetting Nama pengaturan aplikasi atau kumpulan pengaturan yang berisi string koneksi SignalR Service, yang default ke AzureSignalRConnectionString.
userId Opsional. Pengidentifikasi pengguna koneksi SignalR. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
idToken Opsional. JWT yang klaimnya akan ditambahkan ke klaim pengguna. Ini harus digunakan bersama dengan claimTypeList. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
claimTypeList Opsional. Daftar jenis klaim, yang memfilter klaim di idToken .

Anotasi

Tabel berikut menjelaskan pengaturan yang didukung untuk anotasi SignalRConnectionInfoInput.

Pengaturan Deskripsi
nama Nama variabel yang digunakan dalam kode fungsi untuk objek info koneksi.
hubName Harus diisi. Nama hub.
connectionStringSetting Nama pengaturan aplikasi atau kumpulan pengaturan yang berisi string koneksi SignalR Service, yang default ke AzureSignalRConnectionString.
userId Opsional. Pengidentifikasi pengguna koneksi SignalR. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
idToken Opsional. JWT yang klaimnya akan ditambahkan ke klaim pengguna. Ini harus digunakan bersama dengan claimTypeList. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
claimTypeList Opsional. Daftar jenis klaim, yang memfilter klaim di idToken .

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json Deskripsi
jenis Harus diatur ke signalRConnectionInfo.
arah Harus diatur ke in.
hubName Harus diisi. Nama hub.
connectionStringSetting Nama pengaturan aplikasi atau kumpulan pengaturan yang berisi string koneksi SignalR Service, yang default ke AzureSignalRConnectionString.
userId Opsional. Pengidentifikasi pengguna koneksi SignalR. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
idToken Opsional. JWT yang klaimnya akan ditambahkan ke klaim pengguna. Ini harus digunakan bersama dengan claimTypeList. Anda bisa menggunakan ekspresi pengikatan untuk mengikat nilai ke header permintaan HTTP atau kueri.
claimTypeList Opsional. Daftar jenis klaim, yang memfilter klaim di idToken .

Peringatan

Untuk kesederhanaan, kami menghilangkan bagian autentikasi dan otorisasi dalam sampel ini. Akibatnya, titik akhir ini dapat diakses secara publik tanpa batasan apa pun. Untuk memastikan keamanan titik akhir negosiasi Anda, Anda harus menerapkan mekanisme autentikasi dan otorisasi yang sesuai berdasarkan persyaratan spesifik Anda. Untuk panduan tentang melindungi titik akhir HTTP Anda, lihat artikel berikut ini:

Penggunaan

Koneksi berbasis identitas terkelola

Untuk keamanan yang optimal, aplikasi fungsi Anda harus menggunakan identitas terkelola saat menyambungkan ke layanan Azure SignalR alih-alih menggunakan string koneksi, yang berisi kunci rahasia bersama. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke sumber daya Azure SignalR Service dengan identitas terkelola Microsoft Entra.

token yang diautentikasi

Saat klien terautentikasi memicu fungsi, Anda dapat menambahkan klaim ID pengguna ke token yang dihasilkan. Anda dapat dengan mudah menambahkan autentikasi ke aplikasi fungsi menggunakan Autentikasi App Service.

Autentikasi App Service menetapkan header HTTP bernama x-ms-client-principal-id dan x-ms-client-principal-name yang berisi ID dan nama utama klien penggunanya masing-masing yang telah diautentikasi.

Anda dapat mengatur properti UserId pengikatan ke nilai dari salah satu header menggunakan ekspresi pengikatan: {headers.x-ms-client-principal-id} atau {headers.x-ms-client-principal-name}.

[Function("Negotiate")]
public static string Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
    [SignalRConnectionInfoInput(HubName = "hubName1", UserId = "{headers.x-ms-client-principal-id}")] string connectionInfo)
{
    // The serialization of the connection info object is done by the framework. It should be camel case. The SignalR client respects the camel case response only.
    return connectionInfo;
}

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST, HttpMethod.GET },
            authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(name = "connectionInfo", hubName = "hubName1", userId = "{headers.x-ms-signalr-userid}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Berikut data pengikatan dalam file function.json:

{
    "type": "signalRConnectionInfo",
    "name": "connectionInfo",
    "hubName": "hubName1",
    "userId": "{headers.x-ms-client-principal-id}",
    "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
    "direction": "in"
}

Berikut kode JavaScript:

const { app, input } = require('@azure/functions');

const inputSignalR = input.generic({
    type: 'signalRConnectionInfo',
    name: 'connectionInfo',
    hubName: 'hubName1',
    connectionStringSetting: 'AzureSignalRConnectionString',
    userId: '{headers.x-ms-client-principal-id}',
});

app.post('negotiate', {
    authLevel: 'function',
    handler: (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
    },
    route: 'negotiate',
    extraInputs: [inputSignalR],
});

Contoh PowerShell lengkap sedang tertunda.

Berikut adalah kode Python:

def main(req: func.HttpRequest, connectionInfo: str) -> func.HttpResponse:
    # connectionInfo contains an access key token with a name identifier
    # claim set to the authenticated user
    return func.HttpResponse(
        connectionInfo,
        status_code=200,
        headers={
            'Content-type': 'application/json'
        }
    )

@FunctionName("negotiate")
public SignalRConnectionInfo negotiate(
        @HttpTrigger(
            name = "req",
            methods = { HttpMethod.POST },
            authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> req,
        @SignalRConnectionInfoInput(
            name = "connectionInfo",
            HubName = "hubName1",
            userId = "{headers.x-ms-client-principal-id}") SignalRConnectionInfo connectionInfo) {
    return connectionInfo;
}

Ekspresi pengikatan untuk pemicu HTTP

Ini adalah skenario umum bahwa nilai beberapa atribut pengikatan input SignalR berasal dari permintaan HTTP. Oleh karena itu, kami menunjukkan cara mengikat nilai dari permintaan HTTP ke atribut pengikatan input SignalR melalui ekspresi pengikatan.

Jenis metadata HTTP Format ekspresi pengikatan Deskripsi Contoh
Kueri permintaan HTTP {query.QUERY_PARAMETER_NAME} Mengikat nilai parameter kueri terkait ke atribut {query.userName}
Tajuk permintaan HTTP {headers.HEADER_NAME} Mengikat nilai header ke atribut {headers.token}

Langkah berikutnya

  • Last updated on