Points de terminaison en amont

La fonctionnalité de points de terminaison en amont permet à Azure SignalR Service d’envoyer des messages et des événements de connexion à un ensemble de points de terminaison en mode serverless. Vous pouvez utiliser les points de terminaison en amont pour invoquer une méthode hub à partir de clients en mode serverless afin de notifier les points de terminaison lorsque des connexions client sont établies ou interrompues.

Remarque

Les points de terminaison en amont ne peuvent être configurés qu’en mode serverless.

Paramètres du point de terminaison en amont

Les paramètres du point de terminaison en amont sont constitués d’une liste d’éléments sensibles à l’ordre :

• un modèle d’URL spécifiant où les messages sont envoyés ;
• un ensemble de règles ;
• des configurations d’authentification.

Lorsqu’un événement spécifié est enclenché, les règles d’un élément sont vérifiées une à une dans l’ordre. Des messages sont envoyés à la première URL du point de terminaison en amont de l’élément correspondant.

Paramètres de modèle d’URL

Vous pouvez paramétrer l’URL de point de terminaison en amont pour prendre en charge différents motifs. Il existe trois paramètres prédéfinis :

Paramètre prédéfini	Description
{hub}	Un Hub est un concept d’Azure SignalR Service. Un Hub est une unité d’isolation. L’étendue des utilisateurs et de la remise des messages est limitée à un Hub.
{category}	Une catégorie peut avoir l’une des valeurs suivantes : connexions : événements de durée de vie de connexion. La valeur est déclenchée quand une connexion client est connectée ou déconnectée. Elle inclut les événements connectés et déconnectés. messages : enclenchée lorsque les clients invoquent une méthode hub. Elle inclut tous les autres événements, hormis ceux de la catégorie connexions.
{event}	Pour la catégorie messages, un événement est la cible d’un message d’appel que le client envoie. Pour la catégorie connections, seules les valeurs connecté et déconnecté sont utilisées.

Ces paramètres prédéfinis peuvent être utilisés dans le modèle d’URL. Les paramètres sont remplacés par une valeur spécifiée lorsque vous évaluez l’URL de point de terminaison en amont. Par exemple :

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

quand une connexion client dans le Hub « conversation » est établie, un message est envoyé à cette URL :

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

Quand un client dans le Hub « conversation » appelle la méthode Hub broadcast, un message est envoyé à cette URL :

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

Référence Key Vault secrète dans les paramètres de modèle d’URL

L’URL du point de terminaison en amont n’est pas chiffrée. Vous pouvez sécuriser les points de terminaison en amont sensibles à l’aide de Key Vault et y accéder avec une identité managée.

Pour activer l’identité managée dans votre instance de service SignalR et lui accorder un accès Key Vault :

1. Ajoutez une identité affectée par le système ou une identité affectée par l’utilisateur. Consultez Comment ajouter une identité managée dans le Portail Azure.

2. Accordez une autorisation de lecture secrète pour l’identité gérée dans les stratégies d’accès de Key Vault. Consultez Attribuer une stratégie d’accès Key Vault à l’aide du portail Azure

3. Remplacez votre texte sensible par la syntaxe suivante dans le modèle d’URL de point de terminaison en amont :

   {@Microsoft.KeyVault(SecretUri=<secret-identity>)}
   

   <secret-identity> correspond à l’URI complet du plan de données d’un secret dans Key Vault, y compris éventuellement une version, par exemple https://myvault.vault.azure.net/secrets/mysecret/ ou https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931.

   Par exemple, une référence complète ressemble à ce qui suit :

   {@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
   

   Une URL de point de terminaison en amont vers Azure Function se présente comme suit :

   https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
   

Remarque

Toutes les 30 minutes, ou bien lorsque les paramètres de point de terminaison en amont ou l’identité managée changent, le service relit le contenu secret. Vous pouvez immédiatement déclencher une mise à jour en modifiant les paramètres de point de terminaison en amont.

Paramètres de règle

Vous pouvez définir séparément les règles de hub, les règles de catégorie et les règles d’événement. La règle de correspondance prend en charge trois formats :

• Utilisez un astérisque (*) pour faire correspondre n’importe quel événement.
• Utilisez une virgule (,) pour joindre plusieurs événements. Par exemple, connected, disconnected correspond aux événements connectés et déconnectés.
• Utilisez le nom complet de l’événement pour correspondre à l’événement. Par exemple, connected correspond à l’événement connecté.

Remarque

Si vous utilisez Azure Functions avec le déclencheur SignalR, ce dernier expose un seul point de terminaison au format suivant : <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>. Vous pouvez simplement configurer les paramètres de modèle d’URL pour cette URL et conserver les paramètres de règle par défaut. Pour plus d’informations sur la recherche des <Function_App_URL> et des <API_KEY>, consultez Intégration du service SignalR.

Paramètres d’authentification

Vous pouvez configurer séparément l’authentification pour chaque paramètre de point de terminaison en amont. Quand vous configurez l’authentification, un jeton est défini dans l’en-tête Authentication du message en amont. Actuellement, Azure SignalR Service prend en charge les types d’authentifications suivants :

• None
• ManagedIdentity

Lorsque vous sélectionnez ManagedIdentity, vous devez d’abord activer une identité managée dans Azure SignalR Service et éventuellement spécifier une ressource. Pour plus de détails, consultez Identités managées pour Azure SignalR Service.

Configurer des paramètres de point de terminaison en amont via le Portail Azure

Remarque

L’intégration avec App Service Environment n’est actuellement pas prise en charge.

1. Accédez à Azure SignalR Service.
2. Cliquez sur Paramètres.
3. Passez du Mode de service à Serverless.
4. Ajoutez des URL sous Modèle d’URL en amont.
5. Sélectionnez Règles hub pour ouvrir les Paramètres en amont.
6. Modifiez Règles hub, Règles d’événement et Règles de catégorie en entrant la valeur de règle dans le champ correspondant.
7. Sous Authentification en amont, sélectionnez
8. Utiliser l’Identité managée. (Vérifiez que vous avez activé l’identité managée)
9. Choisissez les options sous Audience dans le jeton émis. Pour plus de détails, consultez Identités managées pour Azure SignalR Service.

Configurer des paramètres de point de terminaison en amont via le modèle Resource Manager

Pour configurer les paramètres de point de terminaison en amont à l’aide d’un modèle Azure Resource Manager, définissez la propriété upstream dans la propriété properties. L’extrait de code suivant montre comment définir la propriété upstream pour la création et la mise à jour de paramètres de point de terminaison en amont.

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

Protocoles serverless

Azure SignalR Service envoie des messages aux points de terminaison qui suivent les protocoles suivants. Vous pouvez utiliser la liaison de déclencheur du service SignalR avec Function App, qui gère ces protocoles pour vous.

méthode

PUBLICATION

En-tête de requête

Nom	Description
X-ASRS-Connection-Id	ID de connexion pour la connexion client.
X-ASRS-Hub	Hub auquel appartient la connexion client.
X-ASRS-Category	Catégorie à laquelle appartient le message.
X-ASRS-Event	Événement auquel appartient le message.
X-ASRS-Signature	Code HMAC (Hash-based Message Authentication Code) utilisé pour la validation. Pour plus d’informations, consultez Signature.
X-ASRS-User-Claims	Groupe de revendications de la connexion client.
X-ASRS-User-Id	Identité d’utilisateur du client qui envoie le message.
X-ASRS-Client-Query	Requête de la demande lorsque les clients se connectent au service.
Authentification	Jeton facultatif lorsque vous utilisez ManagedIdentity.

Corps de la demande

Connecté

Type de contenu : application/json

Déconnecté

Type de contenu : application/json

Nom	Type	Description
Error	string	Message d’erreur d’une connexion fermée. Vide quand la connexions se ferme sans erreur.

Message d’appel

Type de contenu : application/json ou application/x-msgpack

Nom	Type	Description
InvocationId	string	Chaîne facultative représentant un message d’appel. Pour plus d’informations, consultez Appels.
Cible	string	Identique à l’événement et à la cible dans un message d’appel.
Arguments	Tableau d’objets	Tableau contenant des arguments à appliquer à la méthode référencée dans Target.

Signature

Le service calcule le code SHA256 pour la valeur X-ASRS-Connection-Id à l’aide de la clé d’accès principale et de la clé d’accès secondaire en tant que clé HMAC. Le service la définit dans l’en-tête X-ASRS-Signature lors du placement de demandes HTTP vers un point de terminaison en amont :

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

Étapes suivantes

• Identités managées pour Azure SignalR Service
• Développement et configuration Azure Functions avec Azure SignalR Service
• Gérer les messages du service SignalR (liaison de déclenchement)
• Exemple de liaison de déclencheur SignalR Service