Azure Functions における SignalR サービスのバインドSignalR Service bindings for Azure Functions

この記事では、Azure Functions で SignalR Service のバインドを使用して、Azure SignalR Service に接続されたクライアントに対して認証を行い、リアルタイム メッセージを送信する方法を説明します。This article explains how to authenticate and send real-time messages to clients connected to Azure SignalR Service by using SignalR Service bindings in Azure Functions. Azure Functions は、SignalR Service の入力および出力バインドをサポートしています。Azure Functions supports input and output bindings for SignalR Service.

これは、Azure Functions の開発者向けリファレンス情報です。This is reference information for Azure Functions developers. Azure Functions を初めて使用する場合は、先に次のリソースを参照してください。If you're new to Azure Functions, start with the following resources:

パッケージ - Functions 2.xPackages - Functions 2.x

SignalR Service のバインドは Microsoft.Azure.WebJobs.Extensions.SignalRService NuGet パッケージ、バージョン 1.0.0-preview1-* で提供されます。The SignalR Service bindings are provided in the Microsoft.Azure.WebJobs.Extensions.SignalRService NuGet package, version 1.0.0-preview1-*. パッケージのソース コードは、azure-functions-signalrservice-extension GitHub リポジトリにあります。Source code for the package is in the azure-functions-signalrservice-extension GitHub repository.

注意

Azure SignalR Service は一般公開されています。Azure SignalR Service is generally available. ただし、Azure Functions における SignalR Service のバインドは現在プレビューの段階です。However, SignalR Service bindings for Azure Functions are currently in preview.

次の表に、各開発環境でこのバインディングのサポートを追加する方法を示します。The following table tells how to add support for this binding in each development environment.

開発環境Development environment サポートを追加するバージョン:To add support in
Functions 2.xFunctions 2.x
ローカル開発 - C# クラス ライブラリLocal development - C# class library パッケージをインストールするInstall the package
ローカル開発で - C# スクリプト、JavaScript、F#Local development - C# script, JavaScript, F# 拡張機能を登録するRegister the extension
Portal 開発Portal development 拡張機能を登録するRegister the extension

関数アプリ プロジェクトを再発行せずにポータルで既存のバインディング拡張機能を更新する方法については、拡張機能の更新に関するページを参照してください。To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

SignalR 接続情報入力バインドSignalR connection info input binding

クライアントが Azure SignalR Service に接続するには、そのクライアントに、サービス エンドポイント URL と有効なアクセス トークンが必要です。Before a client can connect to Azure SignalR Service, it must retrieve the service endpoint URL and a valid access token. サービスへの接続に使用される SignalR Service エンドポイント URL と有効なトークンは、SignalRConnectionInfo 入力バインドによって生成されます。The SignalRConnectionInfo input binding produces the SignalR Service endpoint URL and a valid token that are used to connect to the service. トークンを使用できる期間は限られています。また、トークンを使うと、特定のユーザーを接続に対して認証できます。このため、トークンをキャッシュしたりクライアント間で共有したりすることはお勧めしません。Because the token is time-limited and can be used to authenticate a specific user to a connection, you should not cache the token or share it between clients. このバインドを使用した HTTP トリガーは、クライアントが接続情報を取得するときに使用できます。An HTTP trigger using this binding can be used by clients to retrieve the connection information.

言語固有の例をご覧ください。See the language-specific example:

2.x C# 入力の例2.x C# input example

次の例は、入力バインドを使用して SignalR 接続情報を取得し、HTTP 経由でそれを返す C# 関数を示しています。The following example shows a C# function that acquires SignalR connection information using the input binding and returns it over HTTP.

[FunctionName("GetSignalRInfo")]
public static SignalRConnectionInfo GetSignalRInfo(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req, 
    [SignalRConnectionInfo(HubName = "chat")]SignalRConnectionInfo connectionInfo)
{
    return connectionInfo;
}

認証済みトークンAuthenticated tokens

認証済みクライアントによって関数がトリガーされている場合は、ユーザー ID 要求を生成済みトークンに追加できます。If the function is triggered by an authenticated client, you can add a user ID claim to the generated token. [App Service 認証] (../app-service/overview-authentication-authorization.md) を使用すると、認証を関数アプリに簡単に追加することができます。You can easily add authentication to a function app using [App Service Authentication] (../app-service/overview-authentication-authorization.md).

App Service 認証によって、x-ms-client-principal-id および x-ms-client-principal-name という名前の HTTP ヘッダーが設定されます。この 2 つの HTTP ヘッダーには、認証済みユーザーのクライアント プリンシパルの ID と名前がそれぞれ含まれています。App Service Authentication sets HTTP headers named x-ms-client-principal-id and x-ms-client-principal-name that contain the authenticated user's client principal ID and name, respectively. バインドの UserId プロパティをいずれかのヘッダーの値に設定するには、バインド式として {headers.x-ms-client-principal-id} または {headers.x-ms-client-principal-name} を使用します。You can set the UserId property of the binding to the value from either header using a binding expression: {headers.x-ms-client-principal-id} or {headers.x-ms-client-principal-name}.

[FunctionName("GetSignalRInfo")]
public static SignalRConnectionInfo GetSignalRInfo(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req, 
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

2.x JavaScript 入力の例2.x JavaScript input example

次の例は、function.json ファイルの SignalR 接続情報入力バインドと、そのバインドを使用して接続情報を返す JavaScript 関数を示しています。The following example shows a SignalR connection info input binding in a function.json file and a JavaScript function that uses the binding to return the connection information.

function.json ファイルのバインド データを次に示します。Here's binding data in the function.json file:

function.json の例:Example function.json:

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

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context, req, connectionInfo) {
    context.res = { body: connectionInfo };
    context.done();
};

認証済みトークンAuthenticated tokens

認証済みクライアントによって関数がトリガーされている場合は、ユーザー ID 要求を生成済みトークンに追加できます。If the function is triggered by an authenticated client, you can add a user ID claim to the generated token. [App Service 認証] (../app-service/overview-authentication-authorization.md) を使用すると、認証を関数アプリに簡単に追加することができます。You can easily add authentication to a function app using [App Service Authentication] (../app-service/overview-authentication-authorization.md).

App Service 認証によって、x-ms-client-principal-id および x-ms-client-principal-name という名前の HTTP ヘッダーが設定されます。この 2 つの HTTP ヘッダーには、認証済みユーザーのクライアント プリンシパルの ID と名前がそれぞれ含まれています。App Service Authentication sets HTTP headers named x-ms-client-principal-id and x-ms-client-principal-name that contain the authenticated user's client principal ID and name, respectively. バインドの userId プロパティをいずれかのヘッダーの値に設定するには、バインド式として {headers.x-ms-client-principal-id} または {headers.x-ms-client-principal-name} を使用します。You can set the userId property of the binding to the value from either header using a binding expression: {headers.x-ms-client-principal-id} or {headers.x-ms-client-principal-name}.

function.json の例:Example function.json:

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

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context, req, connectionInfo) {
    // connectionInfo contains an access key token with a name identifier 
    // claim set to the authenticated user
    context.res = { body: connectionInfo };
    context.done();
};

SignalR 出力バインドSignalR output binding

SignalR 出力バインドを使用して、Azure SignalR Service で 1 つ以上のメッセージを送信します。Use the SignalR output binding to send one or more messages using Azure SignalR Service. すべての接続済みクライアントにメッセージをブロードキャストすることも、特定のユーザーに対して認証されている接続済みクライアントだけにブロードキャストすることも可能です。You can broadcast a message to all connected clients, or you can broadcast it only to connected clients that have been authenticated to a given user.

言語固有の例をご覧ください。See the language-specific example:

2.x C# 出力の例2.x C# output example

すべてのクライアントにブロードキャストするBroadcast to all clients

次の例は、出力バインドを使用してすべての接続済みクライアントにメッセージを送信する C# 関数を示しています。The following example shows a C# function that sends a message using the output binding to all connected clients. Target は、各クライアントで呼び出されるメソッドの名前です。The Target is the name of the method to be invoked on each client. Arguments プロパティは、クライアント メソッドに渡される 0 個以上のオブジェクトの配列です。The Arguments property is an array of zero or more objects to be passed to the client method.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            Target = "newMessage", 
            Arguments = new [] { message } 
        });
}

ユーザーに送信するSend to a user

ユーザーに対して認証された接続だけにメッセージを送信するには、SignalR メッセージの UserId プロパティを設定します。You can send a message only to connections that have been authenticated to a user by setting the UserId property of the SignalR message.

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message, 
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage 
        {
            // the message will only be sent to these user IDs
            UserId = "userId1",
            Target = "newMessage", 
            Arguments = new [] { message } 
        });
}

2.x JavaScript 出力の例2.x JavaScript output example

すべてのクライアントにブロードキャストするBroadcast to all clients

次の例は、function.json ファイルの SignalR 出力バインドと、そのバインドを使用して Azure SignalR Service でメッセージを送信する JavaScript 関数を示しています。The following example shows a SignalR output binding in a function.json file and a JavaScript function that uses the binding to send a message with Azure SignalR Service. 出力バインドを、1 つ以上の SignalR メッセージの配列に設定します。Set the output binding to an array of one or more SignalR messages. SignalR メッセージは、クライアントごとに呼び出すメソッドの名前を指定する target プロパティと、クライアント メソッドに引数として渡されるオブジェクトの配列である arguments プロパティで構成されます。A SignalR message consists of a target property that specifies the name of the method to invoke on each client, and an arguments property that is an array of objects to pass to the client method as arguments.

function.json ファイルのバインド データを次に示します。Here's binding data in the function.json file:

function.json の例:Example function.json:

{
  "type": "signalR",
  "name": "signalRMessages",
  "hubName": "<hub_name>",
  "connectionStringSetting": "<name of setting containing SignalR Service connection string>",
  "direction": "out"
}

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context, req) {
    context.bindings.signalRMessages = [{
        "target": "newMessage",
        "arguments": [ req.body ]
    }];
    context.done();
};

ユーザーに送信するSend to a user

ユーザーに対して認証された接続だけにメッセージを送信するには、SignalR メッセージの userId プロパティを設定します。You can send a message only to connections that have been authenticated to a user by setting the userId property of the SignalR message.

function.json は同じままです。function.json stays the same. JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context, req) {
    context.bindings.signalRMessages = [{
        // message will only be sent to these user IDs
        "userId": "userId1",
        "target": "newMessage",
        "arguments": [ req.body ]
    }];
    context.done();
};

構成Configuration

SignalRConnectionInfoSignalRConnectionInfo

次の表は、function.json ファイルと SignalRConnectionInfo 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the SignalRConnectionInfo attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype signalRConnectionInfo に設定する必要があります。Must be set to signalRConnectionInfo.
directiondirection in に設定する必要があります。Must be set to in.
namename 接続情報オブジェクトの関数コードで使用される変数名。Variable name used in function code for connection info object.
hubNamehubName HubNameHubName この値は、接続情報が生成される SignalR ハブの名前に設定する必要があります。This value must be set to the name of the SignalR hub for which the connection information is generated.
userIduserId UserIdUserId 省略可能:アクセス キー トークンに設定するユーザー識別子要求の値。Optional: The value of the user identifier claim to be set in the access key token.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting SignalR Service 接続文字列を含むアプリ設定の名前 (既定値は "AzureSignalRConnectionString")The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

SignalRSignalR

次の表は、function.json ファイルと SignalR 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the SignalR attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype signalR に設定する必要があります。Must be set to signalR.
directiondirection out に設定する必要があります。Must be set to out.
namename 接続情報オブジェクトの関数コードで使用される変数名。Variable name used in function code for connection info object.
hubNamehubName HubNameHubName この値は、接続情報が生成される SignalR ハブの名前に設定する必要があります。This value must be set to the name of the SignalR hub for which the connection information is generated.
connectionStringSettingconnectionStringSetting ConnectionStringSettingConnectionStringSetting SignalR Service 接続文字列を含むアプリ設定の名前 (既定値は "AzureSignalRConnectionString")The name of the app setting that contains the SignalR Service connection string (defaults to "AzureSignalRConnectionString")

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。When you're developing locally, app settings go into the local.settings.json file.

次の手順Next steps