上游设置Upstream settings

Upstream 是一项预览功能,它允许 Azure SignalR 服务以无服务器模式将消息和连接事件发送到一组终结点。Upstream is a preview feature that allows Azure SignalR Service to send messages and connection events to a set of endpoints in serverless mode. 你可以使用上游在无服务器模式下从客户端调用某个中心方法,并让终结点在客户端建立连接或断开连接时获得通知。You can use upstream to invoke a hub method from clients in serverless mode and let endpoints get notified when client connections are connected or disconnected.

备注

只有无服务器模式可以配置上游设置。Only serverless mode can configure upstream settings.

上游设置的详细信息Details of upstream settings

上游设置由一系列顺序敏感项组成。Upstream settings consist of a list of order-sensitive items. 每个项都包含:Each item consists of:

  • 一个 URL 模板,它指定将消息发送到的位置。A URL template, which specifies where messages send to.
  • 一组规则。A set of rules.
  • 身份验证配置。Authentication configurations.

当发生指定的事件时,将按顺序逐个检查项的规则。When the specified event happens, an item's rules are checked one by one in order. 消息将发送到第一个匹配项的上游 URL。Messages will be sent to the first matching item's upstream URL.

URL 模板设置URL template settings

可以将 URL 参数化以支持各种模式。You can parameterize the URL to support various patterns. 有三个预定义的参数:There are three predefined parameters:

预定义的参数Predefined parameter 说明Description
{hub}{hub} 中心是 Azure SignalR 服务的一个概念。A hub is a concept of Azure SignalR Service. 中心是一个隔离单元。A hub is a unit of isolation. 用户和消息传递的作用域被限定为某个中心。The scope of users and message delivery is constrained to a hub.
{category}{category} 类别可以是下列值之一:A category can be one of the following values:
  • 连接:连接生存期事件。connections: Connection lifetime events. 它在客户端建立连接或断开连接时引发。It's fired when a client connection is connected or disconnected. 它包括“已连接”事件和“已断开连接”事件。It includes connected and disconnected events.
  • 消息:当客户端调用某个中心方法时引发。messages: Fired when clients invoke a hub method. 它包含除“连接”类别中事件之外的所有其他事件。It includes all other events, except those in the connections category.
{event}{event} 对于“消息”类别,事件是客户端发送的调用消息中的目标。For the messages category, an event is the target in an invocation message that clients send. 对于“连接”类别,只使用“已连接”和“已断开连接” 。For the connections category, only connected and disconnected are used.

这些预定义参数可用于 URL 模式。These predefined parameters can be used in the URL pattern. 在评估上游 URL 时,参数将替换为某个指定的值。Parameters will be replaced with a specified value when you're evaluating the upstream URL. 例如:For example:

http://host.com/{hub}/api/{category}/{event}

当“聊天”中心内建立了某个客户端连接时,会向以下 URL 发送消息:When a client connection in the "chat" hub is connected, a message will be sent to this URL:

http://host.com/chat/api/connections/connected

当“聊天”中心内的客户端调用中心方法 broadcast 时,会向以下 URL 发送消息:When a client in the "chat" hub invokes the hub method broadcast, a message will be sent to this URL:

http://host.com/chat/api/messages/broadcast

URL 模板设置中的 Key Vault 机密引用Key Vault secret reference in URL template settings

上游的 URL 不会静态加密。The URL of upstream is not encryption at rest. 如果有任何敏感信息,建议使用 Key Vault 将其保存在访问控制更为安全的地方。If you have any sensitive information, it's suggested to use Key Vault to save them where access control has better insurance. 基本上可以启用 Azure SignalR 服务的托管标识,然后授予对 Key Vault 实例的读取权限,并在上游 URL 模式中使用 Key Vault 引用而不是纯文本。Basically, you can enable the managed identity of Azure SignalR Service and then grant read permission on a Key Vault instance and use Key Vault reference instead of plaintext in Upstream URL Pattern.

  1. 添加系统分配的标识或用户分配的标识。Add a system-assigned identity or user-assigned identity. 请参阅如何在 Azure 门户中添加托管标识See How to add managed identity in Azure Portal

  2. 在 Key Vault 的访问策略中授予对托管标识的机密读取权限。Grant secret read permission for the managed identity in the Access policies in the Key Vault. 请参阅使用 Azure 门户分配 Key Vault 访问策略See Assign a Key Vault access policy using the Azure portal

  3. 在上游 URL 模式中将敏感文本替换为语法 {@Microsoft.KeyVault(SecretUri=<secret-identity>)}Replace your sensitive text with the syntax {@Microsoft.KeyVault(SecretUri=<secret-identity>)} in the Upstream URL Pattern.

备注

仅在更改上游设置或托管标识时,机密内容才会重新读取。The secret content only rereads when you change the Upstream settings or change the managed identity. 使用 Key Vault 机密引用之前,请确保你已授予对托管标识的机密读取权限。Make sure you have granted secret read permission to the managed identity before using the Key Vault secret reference.

规则设置Rule settings

你可以分别为“中心规则”、“类别规则”和“事件规则”设置规则。You can set rules for hub rules, category rules, and event rules separately. 匹配规则支持三种格式。The matching rule supports three formats. 以事件规则为例:Take event rules as an example:

  • 使用星号 (*) 来匹配任何事件。Use an asterisk(*) to match any events.
  • 使用逗号 (,) 来联接多个事件。Use a comma (,) to join multiple events. 例如,connected, disconnected 匹配“已连接”和“已断开连接”事件。For example, connected, disconnected matches the connected and disconnected events.
  • 使用完整的事件名称来匹配事件。Use the full event name to match the event. 例如,connected 匹配“已连接”事件。For example, connected matches the connected event.

备注

如果使用 Azure Functions 和 SignalR 触发器,则 SignalR 触发器将按以下格式公开单个终结点:<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>If you're using Azure Functions and SignalR trigger, SignalR trigger will expose a single endpoint in the following format: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>. 只需为此 URL 配置“URL 模板设置”,并将“规则设置”保留为默认值 。You can just configure URL template settings to this url and keep Rule settings default. 有关如何查找 <Function_App_URL><API_KEY> 的详细信息,请参阅 SignalR 服务集成See SignalR Service integration for details about how to find <Function_App_URL> and <API_KEY>.

身份验证设置Authentication settings

你可以分别为每个上游设置项配置身份验证。You can configure authentication for each upstream setting item separately. 配置身份验证时,会在上游消息的 Authentication 标头中设置令牌。When you configure authentication, a token is set in the Authentication header of the upstream message. 目前,Azure SignalR 服务支持以下身份验证类型:Currently, Azure SignalR Service supports the following authentication types:

  • None
  • ManagedIdentity

选择 ManagedIdentity 时,必须提前在 Azure SignalR 服务中启用托管标识,可以指定资源。When you select ManagedIdentity, you must enable a managed identity in Azure SignalR Service in advance and optionally specify a resource. 有关详细信息,请参阅 Azure SignalR 服务的托管标识See Managed identities for Azure SignalR Service for details.

通过 Azure 门户创建上游设置Create upstream settings via the Azure portal

  1. 转到“Azure SignalR 服务”。Go to Azure SignalR Service.

  2. 选择“设置”并将“服务模式”切换到“无服务器”。Select Settings and switch Service Mode to Serverless. 此时会显示上游设置:The upstream settings will appear:

    上游设置

  3. 在“上游 URL 模式”下添加 URL。Add URLs under Upstream URL Pattern. 然后,设置(如“中心规则”)会显示默认值。Then settings such as Hub Rules will show the default value.

  4. 若要设置“中心规则”、“事件规则”、“类别规则”和“上游身份验证”的设置,请选择“中心规则”的值。 To set settings for Hub Rules, Event Rules, Category Rules, and Upstream Authentication, select the value of Hub Rules. 此时会显示一个页面,你可以在其中编辑设置:A page that allows you to edit settings appears:

    Upstream 设置详细信息

  5. 若要设置“上游身份验证”,请确保已先启用托管标识。To set Upstream Authentication, make sure you've enabled a managed identity first. 然后选择“使用托管标识”。Then select Use Managed Identity. 可以根据需要选择“身份验证资源 ID”下的任何选项。According to your needs, you can choose any options under Auth Resource ID. 有关详细信息,请参阅 Azure SignalR 服务的托管标识See Managed identities for Azure SignalR Service for details.

通过资源管理器模板创建上游设置Create upstream settings via Resource Manager template

若要使用 Azure 资源管理器模板创建上游设置,请在 properties 属性中设置 upstream 属性。To create upstream settings by using an Azure Resource Manager template, set the upstream property in the properties property. 以下代码片段显示了如何设置用于创建和更新上游设置的 upstream 属性。The following snippet shows how to set the upstream property for creating and updating upstream settings.

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

无服务器协议Serverless protocols

Azure SignalR 服务将消息发送到遵循以下协议的终结点。Azure SignalR Service sends messages to endpoints that follow the following protocols. 可以将 SignalR 服务触发器绑定用于处理这些协议的 Function App。You can use SignalR Service trigger binding with Function App, which handles these protocols for you.

方法Method

POSTPOST

请求头Request header

名称Name 说明Description
X-ASRS-Connection-IdX-ASRS-Connection-Id 客户端连接的连接 ID。The connection ID for the client connection.
X-ASRS-HubX-ASRS-Hub 客户端连接所属的中心。The hub that the client connection belongs to.
X-ASRS-CategoryX-ASRS-Category 消息所属的类别。The category that the message belongs to.
X-ASRS-EventX-ASRS-Event 消息所属的事件。The event that the message belongs to.
X-ASRS-SignatureX-ASRS-Signature 一个基于哈希的消息身份验证代码 (HMAC),用于验证。A hash-based message authentication code (HMAC) that's used for validation. 有关详细信息,请参阅签名See Signature for details.
X-ASRS-User-ClaimsX-ASRS-User-Claims 客户端连接的一组声明。A group of claims of the client connection.
X-ASRS-User-IdX-ASRS-User-Id 发送消息的客户端的用户标识。The user identity of the client that sends the message.
X-ASRS-Client-QueryX-ASRS-Client-Query 客户端连接到服务时的请求的查询。The query of the request when clients connect to the service.
身份验证Authentication 使用 ManagedIdentity 时的一个可选令牌。An optional token when you're using ManagedIdentity.

请求正文Request body

连续Connected

Content-Type: application/jsonContent-Type: application/json

已断开连接Disconnected

Content-Type:application/jsonContent-Type: application/json

名称Name 类型Type 说明Description
错误Error stringstring 已关闭连接的错误消息。The error message of a closed connection. 当连接无错关闭时为空。Empty when connections close with no error.

调用消息Invocation message

Content-Type:application/jsonapplication/x-msgpackContent-Type: application/json or application/x-msgpack

名称Name 类型Type 说明Description
InvocationIdInvocationId stringstring 一个表示调用消息的可选字符串。An optional string that represents an invocation message. 可以在调用中找到详细信息。Find details in Invocations.
目标Target stringstring 与事件相同,并且与调用消息中的目标相同。The same as the event and the same as the target in an invocation message.
参数Arguments 对象的数组Array of object 一个数组,其中包含要应用于 Target 中所引用方法的参数。An array that contains arguments to apply to the method referred to in Target.

签名Signature

服务将同时使用主要访问密钥和辅助访问密钥作为 HMAC 密钥来计算 X-ASRS-Connection-Id 值的 SHA256 代码。The service will calculate SHA256 code for the X-ASRS-Connection-Id value by using both the primary access key and the secondary access key as the HMAC key. 向上游发出 HTTP 请求时,服务会在 X-ASRS-Signature 标头中设置该代码:The service will set it in the X-ASRS-Signature header when making HTTP requests to upstream:

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

后续步骤Next steps