Azure SignalR Service を使用した Azure Functions の開発と構成

クラスベースのモデルは、より優れたプログラミング エクスペリエンスを提供し、これにより SignalR の入力と出力のバインディングを次の機能に置き換えることができます。

• より柔軟なネゴシエーション、メッセージの送信、グループエクスペリエンスの管理。
• 接続の終了や、接続やユーザーまたはグループが存在することの確認など、さらに多くの管理機能もサポートされています。
• 厳密に型付けされた XML
• 統合ハブ名と接続文字列の設定は、1 つの場所で行ないます。

次のコードで、クラス ベースのモデルでの SignalR バインディングの記述方法を示します。

まず、クラス ServerlessHub から派生したハブを定義します。

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub
{
    private const string HubName = nameof(Functions); // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("negotiate")]
    public async Task<HttpResponseData> Negotiate([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
    {
        var negotiateResponse = await NegotiateAsync(new() { UserId = req.Headers.GetValues("userId").FirstOrDefault() });
        var response = req.CreateResponse();
        response.WriteBytes(negotiateResponse.ToArray());
        return response;
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.SendAsync("newMessage", new NewMessage(invocationContext, message));
    }

    [Function("JoinGroup")]
    public Task JoinGroup([SignalRTrigger(HubName, "messages", "JoinGroup", "connectionId", "groupName")] SignalRInvocationContext invocationContext, string connectionId, string groupName)
    {
        return Groups.AddToGroupAsync(connectionId, groupName);
    }
}

Program.cs ファイルの中で、サーバーレス ハブを登録します。

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(b => b.Services
        .AddServerlessHub<Functions>())
    .Build();

クラス ベース モデルでのネゴシエーション エクスペリエンス

SignalR の入力バインド [SignalRConnectionInfoInput] を使う代わりに、クラス ベース モデルのネゴシエーションを使うといっそう柔軟になります。 基底クラス ServerlessHub にはメソッド NegotiateAsync があり、これにより userId、claims などのネゴシエーション オプションをカスタマイズすることができます。

Task<BinaryData> NegotiateAsync(NegotiationOptions? options = null)

クラス ベースのモデルにおけるメッセージの送信とエクスペリエンスの管理

基底クラス ServerlessHub によって提供されるメンバーにアクセスして、メッセージの送信、グループの管理、クライアントの管理を行うことができます。

• クライアントへのメッセージ送信用の ServerlessHub.Clients。
• グループへの接続の追加、グループからの接続の削除など、グループとの接続を管理するためのServerlessHub.Groups。
• グループへのユーザーの追加、グループからのユーザーの削除など、グループとユーザーを管理するための ServerlessHub.UserGroups。
• 接続の存在の確認、接続の終了、その他を行なうための ServerlessHub.ClientManager。

厳密に型指定されたハブ

厳密に型指定されたハブにより、クライアントにメッセージを送信するときに、厳密に型指定されたメソッドを使用できるようになります。 クラス ベース モデルで厳密に型指定されたハブを使用するには、クライアント メソッドをインターフェイス T に抽出し、ハブ クラスを ServerlessHub<T> から派生させます。

次のコードは、クライアント メソッドでのインターフェイスのサンプルです。

public interface IChatClient
{
    Task newMessage(NewMessage message);
}

その後、厳密に型指定されたメソッドを次のように使用できます。

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub<IChatClient>
{
    private const string HubName = nameof(Functions);  // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.newMessage(new NewMessage(invocationContext, message));
    }
}

1 つの場所で統合ハブ名と接続文字列を設定

• サーバーレス ハブのクラス名は、自動的に HubNameとして使用されます。
• サーバーレス ハブ クラスで、SignalRConnection 属性が次のように使用されていることも意識してください。

  [SignalRConnection("AzureSignalRConnectionString")]
  public class Functions : ServerlessHub<IChatClient>
  

  これにより、サーバーレス ハブの接続文字列を置く場所をカスタマイズできます。 これが見つからない場合は、既定値の AzureSignalRConnectionString が使用されます。

クラス ベース モデルは、一貫性のある SignalR サーバー側プログラミング エクスペリエンスを提供し、次の機能を備えています。

• 少ない構成作業: クラス名は HubName として使用され、メソッド名は Event として使用され、Category はメソッド名にしたがって自動的に決定されます。
• 自動パラメーター バインド: ParameterNames と属性 [SignalRParameter] は必要ありません。 パラメーターは、Azure Functions メソッドの引数に順番に自動的にバインドされます。
• 便利な出力とネゴシエーション エクスペリエンス。

次のコードはこれらの機能を示したものです。

public class HubName1 : ServerlessHub
{
    [FunctionName("negotiate")]
    public SignalRConnectionInfo Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req)
    {
        return Negotiate(req.Headers["x-ms-signalr-user-id"], GetClaims(req.Headers["Authorization"]));
    }

    [FunctionName(nameof(OnConnected))]
    public async Task OnConnected([SignalRTrigger]InvocationContext invocationContext, ILogger logger)
    {
        await Clients.All.SendAsync(NewConnectionTarget, new NewConnection(invocationContext.ConnectionId));
        logger.LogInformation($"{invocationContext.ConnectionId} has connected");
    }

    [FunctionName(nameof(Broadcast))]
    public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        await Clients.All.SendAsync(NewMessageTarget, new NewMessage(invocationContext, message));
        logger.LogInformation($"{invocationContext.ConnectionId} broadcast {message}");
    }

    [FunctionName(nameof(OnDisconnected))]
    public void OnDisconnected([SignalRTrigger]InvocationContext invocationContext)
    {
    }
}

クラス ベース モデルを使うすべての関数は、ServerlessHub から継承するクラスのメソッドである必要があります。 サンプルのクラス名 HubName1 はハブ名です。

ハブ メソッドを定義する

すべてのハブ メソッドは、[SignalRTrigger] 属性で装飾された InvocationContext の引数を持ち、パラメーターなしのコンストラクターを使用する必要があります。 その場合、メソッド名は、パラメーター イベントとして扱われます。

既定では、メソッド名以外の category=messages は次のいずれかの名前になります。

• OnConnected: category=connections, event=connected として扱われます
• OnDisconnected: category=connections, event=disconnected として扱われます

パラメーター バインディング エクスペリエンス

クラス ベース モデルでは、次の状況を除き、すべての引数は既定で [SignalRParameter] としてマークされるため、[SignalRParameter] は必要ありません。

• 引数が、バインド属性によって修飾されている
• 引数の型が ILogger または CancellationToken である。
• 引数が属性 [SignalRIgnore] によって修飾されている。

クラス ベース モデルでのネゴシエーション エクスペリエンス

SignalR の入力バインド [SignalR] を使う代わりに、クラス ベース モデルのネゴシエーションを使うといっそう柔軟になります。 基底クラス ServerlessHub には次のメソッドがあります。

SignalRConnectionInfo Negotiate(string userId = null, IList<Claim> claims = null, TimeSpan? lifeTime = null)

この機能により、関数の実行中にユーザーが userId または claims をカスタマイズできるようになります。

SignalRFilterAttribute を使用します

ユーザーは、抽象クラス SignalRFilterAttribute を継承して実装できます。 FilterAsync で例外がスローされると、403 Forbidden がクライアントに返されます。

次のサンプルは、admin が broadcast を呼び出すことだけが許可される顧客フィルターを実装する方法を示しています。

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
internal class FunctionAuthorizeAttribute: SignalRFilterAttribute
{
    private const string AdminKey = "admin";

    public override Task FilterAsync(InvocationContext invocationContext, CancellationToken cancellationToken)
    {
        if (invocationContext.Claims.TryGetValue(AdminKey, out var value) &&
            bool.TryParse(value, out var isAdmin) &&
            isAdmin)
        {
            return Task.CompletedTask;
        }

        throw new Exception($"{invocationContext.ConnectionId} doesn't have admin role");
    }
}

属性を使って関数を承認します。

[FunctionAuthorize]
[FunctionName(nameof(Broadcast))]
public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
{
}