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.

Impostazioni dell'endpoint upstream

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.

Impostazioni del modello di URL

È 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: connections: eventi di durata della connessione. Viene generato quando una connessione client è connessa o disconnessa. Include eventi connessi e disconnessi. messages: generato quando i client richiamano un metodo hub. Include tutti gli altri eventi, ad eccezione degli eventi nella categoria connessioni .
{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 broadcasthub , verrà inviato un messaggio a questo URL:

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

Informazioni di riferimento sul segreto di Key Vault nelle impostazioni del modello di URL

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:

1. Aggiungere un'identità assegnata dal sistema o un'identità assegnata dall'utente. Vedere Come aggiungere un'identità gestita in portale di Azure.

2. 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

3. 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/ec96f02080254f109c51a1f14cdb1931

   Un 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.

Impostazioni delle regole

È 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>.

Impostazioni di autenticazione

È 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 ManagedIdentityun'identità gestita in Servizio Azure SignalR e, facoltativamente, specificare una risorsa. Per informazioni dettagliate, vedere Identità gestite per Servizio Azure SignalR.

Configurare le impostazioni dell'endpoint upstream tramite il portale di Azure

Nota

L'integrazione con ambiente del servizio app non è attualmente supportata.

1. Passare a Servizio Azure SignalR.
2. Seleziona Impostazioni.
3. Passare alla modalità servizio su Serverless.
4. Aggiungere URL in Modello URL upstream.
5. Selezionare Regole hub per aprire Impostazioni upstream.
6. Modificare le regole dell'hub, le regole di evento e le regole di categoria immettendo il valore della regola nel campo corrispondente.
7. In Autenticazione upstream selezionare
8. Usare l'identità gestita. Assicurarsi di aver abilitato l'identità gestita.
9. Scegliere le opzioni disponibili in Gruppo di destinatari nel token rilasciato. Per informazioni dettagliate, vedere Identità gestite per Servizio Azure SignalR.

Configurare le impostazioni dell'endpoint upstream tramite il modello di Resource Manager

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>"
            }
          }
        }
      ]
    }
  }
}

Protocolli serverless

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.

metodo

POST

Intestazione della richiesta

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.

Testo della richiesta

Connesso

Tipo di contenuto: application/json

Disconnesso

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.

Messaggio di chiamata

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.

Firma

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))

Passaggi successivi

• Identità gestite per Servizio Azure SignalR
• Sviluppo e configurazione di Funzioni di Azure e con il Servizio Azure SignalR
• Gestire i messaggi da Servizio SignalR (associazione di trigger)
• Esempio di associazione trigger Servizio SignalR