Endpoint upstream
La funzionalità degli endpoint upstream consente Servizio Azure SignalR di inviare messaggi ed eventi di connessione a un set di endpoint in modalità serverless. È possibile usare gli endpoint upstream per richiamare un metodo hub dai client in modalità serverless per notificare agli endpoint quando le connessioni client sono connesse o disconnesse.
Nota
Gli endpoint upstream possono essere configurati solo in modalità serverless.
Le impostazioni di un endpoint upstream sono costituite da un elenco di elementi sensibili agli ordini:
- Modello di URL, che specifica la posizione in cui i messaggi vengono inviati.
- Set di regole.
- Configurazioni di autenticazione.
Quando viene generato un evento, le regole di un elemento vengono controllate una per una in ordine. I messaggi verranno inviati all'URL dell'endpoint upstream del primo elemento corrispondente.
È possibile parametrizzare l'URL dell'endpoint upstream per supportare vari modelli. Esistono tre parametri predefiniti:
Parametro predefinito | Descrizione |
---|---|
{hub} | Un hub è un concetto di Servizio Azure SignalR. Un hub è un'unità di isolamento. L'ambito degli utenti e del recapito dei messaggi è vincolato a un hub. |
{category} | Una categoria può essere uno dei valori seguenti:
|
{event} | Per la categoria di messaggi , un evento è la destinazione in un messaggio di chiamata inviato dai client. Per la categoria di connessioni , vengono usati solo i collegamenti connessi e disconnessi . |
Questi parametri predefiniti possono essere usati nel modello url. I parametri verranno sostituiti con un valore specificato quando si valuta l'URL dell'endpoint upstream. Ad esempio:
http://host.com/{hub}/api/{category}/{event}
Quando una connessione client nell'hub "chat" è connessa, verrà inviato un messaggio a questo URL:
http://host.com/chat/api/connections/connected
Quando un client nell'hub "chat" richiama il metodo broadcast
hub , verrà inviato un messaggio a questo URL:
http://host.com/chat/api/messages/broadcast
L'URL dell'endpoint upstream non è crittografato. È possibile proteggere gli endpoint upstream sensibili usando Key Vault e accedervi con un'identità gestita.
Per abilitare l'identità gestita nell'istanza del servizio SignalR e concedere l'accesso a Key Vault:
Aggiungere un'identità assegnata dal sistema o un'identità assegnata dall'utente. Vedere Come aggiungere un'identità gestita in portale di Azure.
Concedere l'autorizzazione di lettura privata per l'identità gestita nei criteri di accesso nell'insieme di credenziali delle chiavi. Vedere Assegnare un criterio di accesso a Key Vault usando il portale di Azure
Sostituire il testo sensibile con la sintassi seguente nel modello di URL dell'endpoint upstream:
{@Microsoft.KeyVault(SecretUri=<secret-identity>)}
<secret-identity>
è l'URI completo del piano dati di un segreto in Key Vault, inclusa facoltativamente una versione, ad esempio https://myvault.vault.azure.net/secrets/mysecret/ o https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931Un riferimento completo, ad esempio, avrebbe un aspetto simile al seguente:
{@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
Un URL dell'endpoint upstream per la funzione di Azure sarà simile al seguente:
https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
Nota
Ogni 30 minuti o ogni volta che le impostazioni dell'endpoint upstream o l'identità gestita cambiano, il servizio rilegge il contenuto del segreto. È possibile attivare immediatamente un aggiornamento modificando le impostazioni dell'endpoint upstream.
È possibile impostare le regole dell'hub, le regole di categoria e le regole di evento separatamente. La regola di corrispondenza supporta tre formati:
- Usare un asterisco (*) per trovare una corrispondenza con qualsiasi evento.
- Usare una virgola (,) per unire più eventi. Ad esempio,
connected, disconnected
corrisponde agli eventi connessi e disconnessi. - Usare il nome completo dell'evento per trovare la corrispondenza con l'evento. Ad esempio,
connected
corrisponde all'evento connesso.
Nota
Se si usa Funzioni di Azure con il trigger SignalR, il trigger SignalR esporrà un singolo endpoint nel formato seguente: <Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>
.
È sufficiente configurare le impostazioni del modello di URL per questo URL e mantenere le impostazioni delle regole predefinite. Vedere integrazione Servizio SignalR per informazioni dettagliate su come trovare <Function_App_URL>
e <API_KEY>
.
È possibile configurare l'autenticazione per ogni impostazione dell'endpoint upstream separatamente. Quando si configura l'autenticazione, un token viene impostato nell'intestazione Authentication
del messaggio upstream. Attualmente, Servizio Azure SignalR supporta i tipi di autenticazione seguenti:
None
ManagedIdentity
Quando si seleziona , è prima necessario abilitare ManagedIdentity
un'identità gestita in Servizio Azure SignalR e, facoltativamente, specificare una risorsa. Per informazioni dettagliate, vedere Identità gestite per Servizio Azure SignalR.
Nota
L'integrazione con ambiente del servizio app non è attualmente supportata.
- Passare a Servizio Azure SignalR.
- Seleziona Impostazioni.
- Passare alla modalità servizio su Serverless.
- Aggiungere URL in Modello URL upstream.
- Selezionare Regole hub per aprire Impostazioni upstream.
- Modificare le regole dell'hub, le regole di evento e le regole di categoria immettendo il valore della regola nel campo corrispondente.
- In Autenticazione upstream selezionare
- Usare l'identità gestita. Assicurarsi di aver abilitato l'identità gestita.
- Scegliere le opzioni disponibili in Gruppo di destinatari nel token rilasciato. Per informazioni dettagliate, vedere Identità gestite per Servizio Azure SignalR.
Per configurare le impostazioni dell'endpoint upstream usando un modello di Azure Resource Manager, impostare la upstream
proprietà nella properties
proprietà . Il frammento di codice seguente illustra come impostare la proprietà per la upstream
creazione e l'aggiornamento delle impostazioni dell'endpoint upstream.
{
"properties": {
"upstream": {
"templates": [
{
"UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
"EventPattern": "*",
"HubPattern": "*",
"CategoryPattern": "*",
"Auth": {
"Type": "ManagedIdentity",
"ManagedIdentity": {
"Resource": "<resource>"
}
}
}
]
}
}
}
Servizio Azure SignalR invia messaggi agli endpoint che seguono i protocolli seguenti. È possibile usare Servizio SignalR'associazione di trigger con l'app per le funzioni, che gestisce automaticamente questi protocolli.
POST
Nome | Descrizione |
---|---|
X-ASRS-Connection-Id | ID connessione per la connessione client. |
X-ASRS-Hub | Hub a cui appartiene la connessione client. |
Categoria X-ASRS | Categoria a cui appartiene il messaggio. |
X-ASRS-Event | Evento a cui appartiene il messaggio. |
X-ASRS-Signature | Codice HMAC (Hash-Based Message Authentication Code) usato per la convalida. Per informazioni dettagliate, vedere Firma . |
X-ASRS-User-Claims | Gruppo di attestazioni della connessione client. |
X-ASRS-User-Id | Identità utente del client che invia il messaggio. |
X-ASRS-Client-Query | Query della richiesta quando i client si connettono al servizio. |
Autenticazione | Token facoltativo quando si usa ManagedIdentity . |
Tipo di contenuto: application/json
Tipo di contenuto: application/json
Nome | Tipo | Descrizione |
---|---|---|
Error | string | Messaggio di errore di una connessione chiusa. Vuoto quando le connessioni si chiudono senza errori. |
Content-Type: application/json
o application/x-msgpack
Nome | Tipo | Descrizione |
---|---|---|
InvocationId | string | Stringa facoltativa che rappresenta un messaggio di chiamata. Trovare i dettagli nelle chiamate. |
Destinazione | string | Uguale all'evento e uguale alla destinazione in un messaggio di chiamata. |
Argomenti | Matrice di oggetti | Matrice che contiene argomenti da applicare al metodo a cui si fa riferimento in Target . |
Il servizio calcolerà il codice SHA256 per il X-ASRS-Connection-Id
valore usando sia la chiave di accesso primaria che la chiave di accesso secondaria come HMAC
chiave. Il servizio lo imposta nell'intestazione X-ASRS-Signature
quando effettua richieste HTTP a un endpoint upstream:
Hex_encoded(HMAC_SHA256(accessKey, connection-id))