Panoramica dell'API del pacchetto Node per Connessioni ibride di inoltroRelay Hybrid Connections Node API overview

PanoramicaOverview

Il pacchetto Node hyco-ws per le connessioni ibride di inoltro di Azure si basa sul pacchetto NPM 'ws' e lo estende.The hyco-ws Node package for Azure Relay Hybrid Connections is built on and extends the 'ws' NPM package. Questo pacchetto permette di esportare nuovamente tutte le esportazioni del pacchetto di base e aggiunge nuove esportazioni che consentono l'integrazione con la funzionalità connessioni ibride del servizio di inoltro di Azure.This package re-exports all exports of that base package and adds new exports that enable integration with the Azure Relay service Hybrid Connections feature.

Le applicazioni esistenti che usano require('ws') possono usare questo pacchetto con require('hyco-ws'), che consente scenari ibridi in cui un'applicazione può contemporaneamente restare in attesa di connessioni WebSocket in locale dall'interno del firewall e tramite connessioni ibride.Existing applications that require('ws') can use this package with require('hyco-ws') instead, which also enables hybrid scenarios in which an application can listen for WebSocket connections locally from "inside the firewall" and via Hybrid Connections, all at the same time.

DocumentazioneDocumentation

La documentazione delle API si trova nel pacchetto 'ws' principale.The APIs are documented in the main 'ws' package. Questo articolo descrive le differenze tra questo pacchetto e il pacchetto di base.This article describes how this package differs from that baseline.

La differenza principale tra il pacchetto di base e questo pacchetto 'hyco-ws' sta nell'aggiunta di una nuova classe server, esportata tramite require('hyco-ws').RelayedServer, e alcuni metodi helper.The key differences between the base package and this 'hyco-ws' is that it adds a new server class, exported via require('hyco-ws').RelayedServer, and a few helper methods.

Metodi helper del pacchettoPackage helper methods

Nell'esportazione del pacchetto sono disponibili diversi metodi di utilità a cui è possibile fare riferimento come indicato di seguito:There are several utility methods available on the package export that you can reference as follows:

const WebSocket = require('hyco-ws');

var listenUri = WebSocket.createRelayListenUri('namespace.servicebus.windows.net', 'path');
listenUri = WebSocket.appendRelayToken(listenUri, 'ruleName', '...key...')
...

I metodi helper sono progettati per questo pacchetto, ma possono essere usati anche da un server Node per abilitare client di dispositivo o Web per la creazione di listener o mittenti.The helper methods are for use with this package, but can also be used by a Node server for enabling web or device clients to create listeners or senders. Il server ne fa uso passando a questi metodi URI che incorporano token di breve durata.The server uses these methods by passing them URIs that embed short-lived tokens. È possibile usare questi URI anche con stack WebSocket comuni che non supportano l'impostazione di intestazioni HTTP per l'handshake WebSocket.These URIs can also be used with common WebSocket stacks that do not support setting HTTP headers for the WebSocket handshake. L'incorporamento di token di autorizzazione nell'URI è supportato principalmente per scenari di utilizzo esterni alla libreria.Embedding authorization tokens into the URI is supported primarily for those library-external usage scenarios.

createRelayListenUricreateRelayListenUri

var uri = createRelayListenUri([namespaceName], [path], [[token]], [[id]])

Crea un URI del listener della connessione ibrida di inoltro di Azure valido per il percorso e lo spazio dei nomi specificati.Creates a valid Azure Relay Hybrid Connection listener URI for the given namespace and path. L'URI può quindi essere usato con la versione di inoltro della classe WebSocketServer.This URI can then be used with the relay version of the WebSocketServer class.

  • namespaceName (obbligatorio): nome di dominio completo dello spazio dei nomi di inoltro di Azure da usare.namespaceName (required) - the domain-qualified name of the Azure Relay namespace to use.
  • path (obbligatorio): nome di una connessione ibrida di inoltro di Azure esistente nello spazio dei nomi.path (required) - the name of an existing Azure Relay Hybrid Connection in that namespace.
  • token (facoltativo): token di accesso di inoltro rilasciato in precedenza incorporato nell'URI del listener. Vedere l'esempio seguente.token (optional) - a previously issued Relay access token that is embedded in the listener URI (see the following example).
  • id (facoltativo): identificatore di rilevamento che consente di tenere traccia della diagnostica end-to-end delle richieste.id (optional) - a tracking identifier that enables end-to-end diagnostics tracking of requests.

Il valore token è facoltativo e deve essere usato solo quando non è possibile inviare intestazioni HTTP con l'handshake WebSocket, come nel caso dello stack WebSocket W3C.The token value is optional and should only be used when it is not possible to send HTTP headers along with the WebSocket handshake, as is the case with the W3C WebSocket stack.

createRelaySendUricreateRelaySendUri

var uri = createRelaySendUri([namespaceName], [path], [[token]], [[id]])

Crea un URI di invio della connessione ibrida di inoltro di Azure valido per il percorso e lo spazio dei nomi specificati.Creates a valid Azure Relay Hybrid Connection send URI for the given namespace and path. L'URI può essere usato con qualsiasi client WebSocket.This URI can be used with any WebSocket client.

  • namespaceName (obbligatorio): nome di dominio completo dello spazio dei nomi di inoltro di Azure da usare.namespaceName (required) - the domain-qualified name of the Azure Relay namespace to use.
  • path (obbligatorio): nome di una connessione ibrida di inoltro di Azure esistente nello spazio dei nomi.path (required) - the name of an existing Azure Relay Hybrid Connection in that namespace.
  • token (facoltativo): token di accesso di inoltro rilasciato in precedenza incorporato nell'URI di invio. Vedere l'esempio seguente.token (optional) - a previously issued Relay access token that is embedded in the send URI (see the following example).
  • id (facoltativo): identificatore di rilevamento che consente di tenere traccia della diagnostica end-to-end delle richieste.id (optional) - a tracking identifier that enables end-to-end diagnostics tracking of requests.

Il valore token è facoltativo e deve essere usato solo quando non è possibile inviare intestazioni HTTP con l'handshake WebSocket, come nel caso dello stack WebSocket W3C.The token value is optional and should only be used when it is not possible to send HTTP headers along with the WebSocket handshake, as is the case with the W3C WebSocket stack.

createRelayTokencreateRelayToken

var token = createRelayToken([uri], [ruleName], [key], [[expirationSeconds]])

Crea un token di firma di accesso condiviso di inoltro di Azure per l'URI di destinazione specificato, una regola di firma di accesso condiviso e la relativa chiave. Quest'ultima è valida per il numero di secondi specificato o per un'ora dall'istante corrente, se viene omesso l'argomento della scadenza.Creates an Azure Relay Shared Access Signature (SAS) token for the given target URI, SAS rule, and SAS rule key that is valid for the given number of seconds or for an hour from the current instant if the expiry argument is omitted.

  • uri (obbligatorio): URI per il quale viene rilasciato il token.uri (required) - the URI for which the token is to be issued. L'URI viene normalizzato affinché usi lo schema HTTP e le informazioni sulla stringa di query vengono rimosse.The URI is normalized to use the HTTP scheme, and query string information is stripped.
  • ruleName (obbligatorio): nome della regola di firma di accesso condiviso per l'entità rappresentata dall'URI specificato o per lo spazio dei nomi rappresentato dalla parte dell'URI relativa all'host.ruleName (required) - SAS rule name for either the entity represented by the given URI, or for the namespace represented by the URI host portion.
  • key (obbligatorio): chiave valida della regola di firma di accesso condiviso.key (required) - valid key for the SAS rule.
  • expirationSeconds (facoltativo): numero di secondi fino alla scadenza del token generato.expirationSeconds (optional) - the number of seconds until the generated token should expire. Se non viene specificato, il valore predefinito è 1 ora (3600).If not specified, the default is 1 hour (3600).

Il token rilasciato conferisce i diritti associati alla regola di firma di accesso condiviso specificata per la durata specificata.The issued token confers the rights associated with the specified SAS rule for the given duration.

appendRelayTokenappendRelayToken

var uri = appendRelayToken([uri], [ruleName], [key], [[expirationSeconds]])

A livello funzionale, questo metodo equivale al metodo createRelayToken documentato in precedenza, ma restituisce il token aggiunto in modo corretto all'URI di input.This method is functionally equivalent to the createRelayToken method documented previously, but returns the token correctly appended to the input URI.

Class ws.RelayedServerClass ws.RelayedServer

La classe hycows.RelayedServer rappresenta un'alternativa alla classe ws.Server, che non rimane in ascolto sulla rete locale ma delega l'ascolto al servizio di inoltro di Azure.The hycows.RelayedServer class is an alternative to the ws.Server class that does not listen on the local network, but delegates listening to the Azure Relay service.

Le due classi sono per lo più compatibili a livello di contratto. Ciò significa che un'applicazione esistente che usa la classe ws.Server può essere modificata facilmente per l'uso della versione inoltrata.The two classes are mostly contract compatible, meaning that an existing application using the ws.Server class can easily be changed to use the relayed version. Le differenze principali sono rappresentate dal costruttore e dalle opzioni disponibili.The main differences are in the constructor and in the available options.

CostruttoreConstructor

var ws = require('hyco-ws');
var server = ws.RelayedServer;

var wss = new server(
    {
        server: ws.createRelayListenUri(ns, path),
        token: function() { return ws.createRelayToken('http://' + ns, keyrule, key); }
    });

Il costruttore RelayedServer supporta un set di argomenti diverso rispetto a Server, perché non è un listener autonomo né può essere incorporato in un framework di listener HTTP esistente.The RelayedServer constructor supports a different set of arguments than the Server, because it is not a standalone listener, or able to be embedded into an existing HTTP listener framework. Anche il numero di opzioni disponibili è ridotto, perché la gestione del WebSocket viene delegata in gran parte al servizio di inoltro.There are also fewer options available since the WebSocket management is largely delegated to the Relay service.

Argomenti del costruttore:Constructor arguments:

  • server (obbligatorio): URI completo del nome di una connessione ibrida su cui rimanere in ascolto, costruito in genere con il metodo helper WebSocket.createRelayListenUri().server (required) - the fully qualified URI for a Hybrid Connection name on which to listen, usually constructed with the WebSocket.createRelayListenUri() helper method.
  • token (obbligatorio): questo argomento contiene una stringa di token rilasciata in precedenza o una funzione di callback che è possibile chiamare per ottenere la stringa di token.token (required) - this argument holds either a previously issued token string or a callback function that can be called to obtain such a token string. È preferibile usare l'opzione di callback, perché consente il rinnovo del token.The callback option is preferred, as it enables token renewal.

EventiEvents

Le istanze di RelayedServer generano tre eventi che consentono di gestire le richieste in ingresso, stabilire le connessioni e rilevare le condizioni di errore.RelayedServer instances emit three events that enable you to handle incoming requests, establish connections, and detect error conditions. Per gestire i messaggi è necessario sottoscrivere l'evento connect.You must subscribe to the connect event to handle messages.

headersheaders
function(headers)

L'evento headers viene generato immediatamente prima che venga accettata una connessione in ingresso, consentendo la modifica delle intestazioni da inviare al client.The headers event is raised just before an incoming connection is accepted, enabling modification of the headers to send to the client.

connessioneconnection
function(socket)

Viene generato quando viene accettata una nuova connessione WebSocket.Emitted when a new WebSocket connection is accepted. L'oggetto è di tipo ws.WebSocket, come nel pacchetto di base.The object is of type ws.WebSocket, same as with the base package.

errorerror
function(error)

Se il server sottostante genera un errore, viene inoltrato qui.If the underlying server emits an error, it is forwarded here.

HelperHelpers

Per semplificare l'avvio di un server inoltrato e sottoscrivere immediatamente le connessioni in ingresso, il pacchetto espone una semplice funzione helper che viene usata anche negli esempi, come indicato di seguito:To simplify starting a relayed server and immediately subscribing to incoming connections, the package exposes a simple helper function, which is also used in the examples, as follows:

createRelayedListenercreateRelayedListener
var WebSocket = require('hyco-ws');

var wss = WebSocket.createRelayedServer(
    {
        server: WebSocket.createRelayListenUri(ns, path),
        token: function() { return WebSocket.createRelayToken('http://' + ns, keyrule, key); }
    }, 
    function (ws) {
        console.log('connection accepted');
        ws.onmessage = function (event) {
            console.log(JSON.parse(event.data));
        };
        ws.on('close', function () {
            console.log('connection closed');
        });       
});
createRelayedServercreateRelayedServer
var server = createRelayedServer([options], [connectCallback] )

Questo metodo chiama il costruttore per creare una nuova istanza di RelayedServer e quindi sottoscrive il callback specificato nell'evento 'connection'.This method calls the constructor to create a new instance of the RelayedServer and then subscribes the provided callback to the 'connection' event.

relayedConnectrelayedConnect

Con il semplice mirroring dell'helper createRelayedServer nella funzione, relayedConnect crea una connessione client e sottoscrive l'evento 'open' nel socket risultante.Simply mirroring the createRelayedServer helper in function, relayedConnect creates a client connection and subscribes to the 'open' event on the resulting socket.

var uri = WebSocket.createRelaySendUri(ns, path);
WebSocket.relayedConnect(
    uri,
    WebSocket.createRelayToken(uri, keyrule, key),
    function (socket) {
        ...
    }
);

Passaggi successiviNext steps

Per altre informazioni sul servizio di inoltro di Azure, vedere i collegamenti seguenti:To learn more about Azure Relay, visit these links: