Introdução às solicitações WebSocket do Relay Hybrid Connections em Python

• NET
• Node.js

Neste início rápido, você cria aplicativos de remetente e recetor Python que enviam e recebem mensagens usando o protocolo WebSocket. Os aplicativos usam o recurso Conexões Híbridas do Azure Relay. Para saber mais sobre o Azure Relay em geral, consulte Azure Relay.

Neste guia de início rápido, você executa as seguintes etapas:

1. Crie um espaço de nomes de Reencaminhamento com o Portal do Azure.
2. Crie uma ligação híbrida nesse espaço de nomes, com o portal do Azure.
3. Gerar um arquivo de propriedades config.json para armazenar detalhes da conexão
4. Desenvolver um relaylib.py para funções auxiliares (tokens SAS, URLs)
5. Escreva um script de servidor (ouvinte) para receber mensagens.
6. Escreva um script de cliente (remetente) para enviar mensagens.
7. Execute o script de servidor (ouvinte) e, opcionalmente, o script de cliente (remetente).

Pré-requisitos

• Python. Certifique-se de que você está executando o Python 3.10+
• Uma subscrição do Azure. Se não tiver uma, crie uma conta gratuita antes de começar.

Criar um espaço de nomes com o Portal do Azure

1. Inicie sessão no portal do Azure.

2. Selecione Todos os serviços no menu à esquerda. Selecione Integração, procure Relés, mova o rato sobre Relés e, em seguida, selecione Criar.

   

3. Na página Criar namespace, siga estas etapas:

   1. Escolha uma assinatura do Azure na qual criar o namespace.

   2. Para Grupo de recursos, escolha um grupo de recursos existente no qual colocar o namespace ou crie um novo.

   3. Insira um nome para o namespace Relay.

   4. Selecione a região na qual seu namespace deve ser hospedado.

   5. Selecione Rever + criar na parte inferior da página.

      

   6. Na página Rever + criar, selecione Criar.

   7. Depois de alguns minutos, você verá a página Retransmissão para o namespace.

      

Obter credenciais de gestão

1. Na página Retransmissão, selecione Políticas de acesso compartilhado no menu à esquerda.

2. Na página Políticas de acesso compartilhado, selecione RootManageSharedAccessKey.

3. Em Política SAS: RootManageSharedAccessKey, selecione o botão Copiar ao lado de Cadeia de Conexão Primária. Esta ação copia a cadeia de conexão para a área de transferência para uso posterior. Cole este valor no Bloco de Notas ou noutra localização temporária.

4. Repita o passo anterior para copiar e colar o valor da Chave primária para uma localização temporária para utilizar mais tarde.

   

Criar uma ligação híbrida com o Portal do Azure

Na página Retransmissão para seu namespace, siga estas etapas para criar uma conexão híbrida.

1. No menu à esquerda, em Entidades, selecione Conexões híbridas e, em seguida, selecione + Conexão híbrida.

   

2. Na página Criar Conexão Híbrida, insira um nome para a conexão híbrida e selecione Criar.

   

Desenvolver funções auxiliares

Criar um script Python

Este script fornece funções auxiliares para aplicativos que utilizam as Conexões Híbridas de Retransmissão do Azure. Essas funções provavelmente ajudam em tarefas como gerar tokens SAS e estabelecer conexões WebSocket para comunicação segura.

Dependências

Instale as seguintes bibliotecas Python usando pip antes de gerar o script de função auxiliar: base64, hashlib, hmac, math, time, urllib

Essas bibliotecas podem ser instaladas usando o seguinte comando:

pip install <package name>

Escrever o script de função auxiliar

Eis o aspeto que o seu relaylib.py ficheiro deve ter:

import base64
import hashlib
import hmac
import math
import time
import urllib

# Function which generates the HMAC-SHA256 of a given message
def hmac_sha256(key, msg):
   hash_obj = hmac.new(key=key, msg=msg, digestmod=hashlib._hashlib.openssl_sha256)
   return hash_obj.digest()

# Function to create a WebSocket URL for listening for a server application
def createListenUrl(serviceNamespace, entityPath, token = None):
   url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=listen&sb-hc-id=123456'
   if token is not None:
       url = url + '&sb-hc-token=' + urllib.parse.quote(token)
   return url

# Function which creates the url for the client application
def createSendUrl(serviceNamespace, entityPath, token = None):
   url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=connect&sb-hc-id=123456'
   if token is not None:
	url = url + '&sb-hc-token=' + urllib.parse.quote(token)
   return url

# Function which creates the Service Bus SAS token. 
def createSasToken(serviceNamespace, entityPath, sasKeyName, sasKey):
   uri = "http://" + serviceNamespace + "/" + entityPath
   encodedResourceUri = urllib.parse.quote(uri, safe = '')

   # Define the token validity period in seconds (48 hours in this case)   
   tokenValidTimeInSeconds = 60 * 60 * 48 
   unixSeconds = math.floor(time.time())
   expiryInSeconds = unixSeconds + tokenValidTimeInSeconds

   # Create the plain signature string by combining the encoded URI and the expiry time
   plainSignature = encodedResourceUri + "\n" + str(expiryInSeconds)

   # Encode the SAS key and the plain signature as bytes
   sasKeyBytes = sasKey.encode("utf-8")
   plainSignatureBytes = plainSignature.encode("utf-8")
   hashBytes = hmac_sha256(sasKeyBytes, plainSignatureBytes)
   base64HashValue = base64.b64encode(hashBytes)

    # Construct the SAS token string
   token = "SharedAccessSignature sr=" + encodedResourceUri + "&sig=" +  urllib.parse.quote(base64HashValue) + "&se=" + str(expiryInSeconds) + "&skn=" + sasKeyName
   return token

Criar uma aplicação de servidor (serviço de escuta)

Para ouvir e receber mensagens do Relay, escreva um script Python WebSocket Server.

Criar um script Python

Se você desativou a opção "Requer autorização do cliente" ao criar a retransmissão, poderá enviar solicitações para a URL de conexões híbridas com qualquer navegador. Para acessar endpoints protegidos, você precisa criar e passar um token SAS, que é mostrado aqui.

Aqui está um script Python simples que demonstra o envio de solicitações para uma URL de conexões híbridas com tokens SAS utilizando WebSockets.

Dependências

1. Instale as seguintes bibliotecas Python usando pip antes de executar o aplicativo de servidor

   asyncio, json, logging, websockets

   Essas bibliotecas podem ser instaladas usando o seguinte comando:

    pip install <package name>
   

2. Gere um config.json arquivo para armazenar seus detalhes de conexão

    {
   "namespace": "HYBRID_CONNECTION_NAMESPACE",
   "path": "HYBRID_CONNECTION_ENTITY_NAME",
   "keyrule": "SHARED_ACCESS_KEY_NAME",
   "key": "SHARED_ACCESS_PRIMARY_KEY"
    }
   

   Substitua os marcadores de posição entre parênteses retos pelos valores obtidos quando criou a ligação híbrida.

   • namespace - O espaço de nomes do Reencaminhamento. Certifique-se de que utiliza o nome de espaço de nomes totalmente qualificado, por exemplo, {namespace}.servicebus.windows.net.
   • path - O nome da ligação híbrida.
   • keyrule - Nome da sua chave de Políticas de Acesso Compartilhado, que é RootManageSharedAccessKey por padrão.
   • key - A chave primária do namespace que você salvou anteriormente.

3. Gerar um arquivo de função auxiliar para funções auxiliares

   O arquivo a seguir é usado como relaylib.py e tem funções auxiliares para geração de URL WebSocket e tokens SAS

   Criar um script Python

   Este script fornece funções auxiliares para aplicativos que utilizam as Conexões Híbridas de Retransmissão do Azure. Essas funções provavelmente ajudam em tarefas como gerar tokens SAS e estabelecer conexões WebSocket para comunicação segura.

   Dependências

   Instale as seguintes bibliotecas Python usando pip antes de gerar o script de função auxiliar: base64, hashlib, hmac, math, time, urllib

   Essas bibliotecas podem ser instaladas usando o seguinte comando:

   pip install <package name>
   

   Escrever o script de função auxiliar

   Eis o aspeto que o seu relaylib.py ficheiro deve ter:

   import base64
   import hashlib
   import hmac
   import math
   import time
   import urllib
   
   # Function which generates the HMAC-SHA256 of a given message
   def hmac_sha256(key, msg):
      hash_obj = hmac.new(key=key, msg=msg, digestmod=hashlib._hashlib.openssl_sha256)
      return hash_obj.digest()
   
   # Function to create a WebSocket URL for listening for a server application
   def createListenUrl(serviceNamespace, entityPath, token = None):
      url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=listen&sb-hc-id=123456'
      if token is not None:
          url = url + '&sb-hc-token=' + urllib.parse.quote(token)
      return url
   
   # Function which creates the url for the client application
   def createSendUrl(serviceNamespace, entityPath, token = None):
      url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=connect&sb-hc-id=123456'
      if token is not None:
   	url = url + '&sb-hc-token=' + urllib.parse.quote(token)
      return url
   
   # Function which creates the Service Bus SAS token. 
   def createSasToken(serviceNamespace, entityPath, sasKeyName, sasKey):
      uri = "http://" + serviceNamespace + "/" + entityPath
      encodedResourceUri = urllib.parse.quote(uri, safe = '')
   
      # Define the token validity period in seconds (48 hours in this case)   
      tokenValidTimeInSeconds = 60 * 60 * 48 
      unixSeconds = math.floor(time.time())
      expiryInSeconds = unixSeconds + tokenValidTimeInSeconds
   
      # Create the plain signature string by combining the encoded URI and the expiry time
      plainSignature = encodedResourceUri + "\n" + str(expiryInSeconds)
   
      # Encode the SAS key and the plain signature as bytes
      sasKeyBytes = sasKey.encode("utf-8")
      plainSignatureBytes = plainSignature.encode("utf-8")
      hashBytes = hmac_sha256(sasKeyBytes, plainSignatureBytes)
      base64HashValue = base64.b64encode(hashBytes)
   
       # Construct the SAS token string
      token = "SharedAccessSignature sr=" + encodedResourceUri + "&sig=" +  urllib.parse.quote(base64HashValue) + "&se=" + str(expiryInSeconds) + "&skn=" + sasKeyName
      return token
   

Escrever alguns códigos para enviar mensagens

1. Garanta sua dependência config.json e relaylib.py esteja disponível em seu caminho

2. Eis o aspeto que o seu listener.py ficheiro deve ter:

    import asyncio
    import json
    import logging
    import relaylib
    import websockets
   
    async def run_application(config):
        serviceNamespace = config["namespace"]
        entityPath = config["path"]
        sasKeyName = config["keyrule"]
        sasKey = config["key"]
        serviceNamespace += ".servicebus.windows.net"
        # Configure logging
        logging.basicConfig(level=logging.INFO)  # Enable DEBUG/INFO logging as appropriate
   
        try:
            logging.debug("Generating SAS Token for: %s", serviceNamespace)
    	token = relaylib.createSasToken(serviceNamespace, entityPath, sasKeyName, sasKey)
    	logging.debug("Generating WebSocket URI")
    	wssUri = relaylib.createListenUrl(serviceNamespace, entityPath, token)
    	async with websockets.connect(wssUri) as websocket:
    	    logging.info("Listening for messages on Azure Relay WebSocket...")
    	    while True:
    		message = await websocket.recv()
    		logging.info("Received message: %s", message)
    	    except KeyboardInterrupt:
    		logging.info("Exiting listener.")
   
    if __name__ == "__main__":
        # Load configuration from JSON file
        with open("config.json") as config_file:
           config = json.load(config_file)
   
        asyncio.run(run_application(config))
   

Criar uma aplicação cliente (remetente)

Para enviar mensagens para o Relay, você pode usar qualquer cliente HTTP ou WebSocket, o exemplo incluído é uma implementação python.

Criar um script Python

Se você desativou a opção "Requer autorização do cliente" ao criar a retransmissão, poderá enviar solicitações para a URL de conexões híbridas com qualquer navegador. Para acessar endpoints protegidos, você precisa criar e passar um token SAS, que é mostrado aqui.

Aqui está um script Python simples que demonstra o envio de solicitações para uma URL de conexões híbridas com tokens SAS utilizando WebSockets.

Dependências

1. Instale as seguintes bibliotecas Python usando pip antes de executar o aplicativo cliente

   asyncio, json, logging, websockets

   Essas bibliotecas podem ser instaladas usando o seguinte comando:

    pip install <package name>
   

2. Gere um config.json arquivo para armazenar seus detalhes de conexão

    {
   "namespace": "HYBRID_CONNECTION_NAMESPACE",
   "path": "HYBRID_CONNECTION_ENTITY_NAME",
   "keyrule": "SHARED_ACCESS_KEY_NAME",
   "key": "SHARED_ACCESS_PRIMARY_KEY"
   }
   

   Substitua os marcadores de posição entre parênteses retos pelos valores obtidos quando criou a ligação híbrida.

   • namespace - O espaço de nomes do Reencaminhamento. Certifique-se de que utiliza o nome de espaço de nomes totalmente qualificado, por exemplo, {namespace}.servicebus.windows.net.
   • path - O nome da ligação híbrida.
   • keyrule - Nome da sua chave de Políticas de Acesso Compartilhado, que é RootManageSharedAccessKey por padrão.
   • key - A chave primária do namespace que você salvou anteriormente.

3. Gerar um arquivo de função auxiliar para funções auxiliares

   O arquivo a seguir é usado como relaylib.py e tem funções auxiliares para geração de URL WebSocket e tokens SAS

   Criar um script Python

   Este script fornece funções auxiliares para aplicativos que utilizam as Conexões Híbridas de Retransmissão do Azure. Essas funções provavelmente ajudam em tarefas como gerar tokens SAS e estabelecer conexões WebSocket para comunicação segura.

   Dependências

   Instale as seguintes bibliotecas Python usando pip antes de gerar o script de função auxiliar: base64, hashlib, hmac, math, time, urllib

   Essas bibliotecas podem ser instaladas usando o seguinte comando:

   pip install <package name>
   

   Escrever o script de função auxiliar

   Eis o aspeto que o seu relaylib.py ficheiro deve ter:

   import base64
   import hashlib
   import hmac
   import math
   import time
   import urllib
   
   # Function which generates the HMAC-SHA256 of a given message
   def hmac_sha256(key, msg):
      hash_obj = hmac.new(key=key, msg=msg, digestmod=hashlib._hashlib.openssl_sha256)
      return hash_obj.digest()
   
   # Function to create a WebSocket URL for listening for a server application
   def createListenUrl(serviceNamespace, entityPath, token = None):
      url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=listen&sb-hc-id=123456'
      if token is not None:
          url = url + '&sb-hc-token=' + urllib.parse.quote(token)
      return url
   
   # Function which creates the url for the client application
   def createSendUrl(serviceNamespace, entityPath, token = None):
      url = 'wss://' + serviceNamespace + '/$hc/' + entityPath + '?sb-hc-action=connect&sb-hc-id=123456'
      if token is not None:
   	url = url + '&sb-hc-token=' + urllib.parse.quote(token)
      return url
   
   # Function which creates the Service Bus SAS token. 
   def createSasToken(serviceNamespace, entityPath, sasKeyName, sasKey):
      uri = "http://" + serviceNamespace + "/" + entityPath
      encodedResourceUri = urllib.parse.quote(uri, safe = '')
   
      # Define the token validity period in seconds (48 hours in this case)   
      tokenValidTimeInSeconds = 60 * 60 * 48 
      unixSeconds = math.floor(time.time())
      expiryInSeconds = unixSeconds + tokenValidTimeInSeconds
   
      # Create the plain signature string by combining the encoded URI and the expiry time
      plainSignature = encodedResourceUri + "\n" + str(expiryInSeconds)
   
      # Encode the SAS key and the plain signature as bytes
      sasKeyBytes = sasKey.encode("utf-8")
      plainSignatureBytes = plainSignature.encode("utf-8")
      hashBytes = hmac_sha256(sasKeyBytes, plainSignatureBytes)
      base64HashValue = base64.b64encode(hashBytes)
   
       # Construct the SAS token string
      token = "SharedAccessSignature sr=" + encodedResourceUri + "&sig=" +  urllib.parse.quote(base64HashValue) + "&se=" + str(expiryInSeconds) + "&skn=" + sasKeyName
      return token
   

Escrever alguns códigos para enviar mensagens

1. Garanta sua dependência config.json e relaylib.py esteja disponível em seu caminho

2. Eis o aspeto que o seu sender.py ficheiro deve ter:

    import asyncio
    import json
    import logging
    import relaylib
    import websockets
   
    async def run_application(message, config):
    	service_namespace = config["namespace"]
    	entity_path = config["path"]
    	sas_key_name = config["keyrule"]
    	sas_key = config["key"]
    	service_namespace += ".servicebus.windows.net"
   
    	# Configure logging
    	logging.basicConfig(level=logging.DEBUG)  # Enable debug logging
   
    	token = relaylib.createSasToken(service_namespace, entity_path, sas_key_name, sas_key)
    	logging.debug("Token: %s", token)
    	wss_uri = relaylib.createListenUrl(service_namespace, entity_path, token)
    	logging.debug("WssURI: %s", wss_uri)
   
    	try:
    		async with websockets.connect(wss_uri) as websocket:
    			logging.info("Sending message to Azure Relay WebSocket...")
    			await websocket.send(json.dumps({"message": message}))
    			logging.info("Message sent: %s", message)
    	except Exception as e:
    		logging.error("An error occurred: %s", str(e))
   
    if __name__ == "__main__":
    	# Load configuration from JSON file
    	with open("config.json") as config_file:
    		config = json.load(config_file)
   
    	asyncio.run(run_application("This is a message to Azure Relay Hybrid Connections!", config))
   

Nota

O código de exemplo neste artigo usa uma cadeia de conexão para autenticar em um namespace do Azure Relay para manter o tutorial simples. Recomendamos que você use a autenticação do Microsoft Entra ID em ambientes de produção, em vez de usar cadeias de conexão ou assinaturas de acesso compartilhado, que podem ser mais facilmente comprometidas. Para obter informações detalhadas e código de exemplo para usar a autenticação do Microsoft Entra ID, consulte Autenticar e autorizar um aplicativo com o Microsoft Entra ID para acessar entidades do Azure Relay e Autenticar uma identidade gerenciada com o Microsoft Entra ID para acessar os recursos do Azure Relay.

Executar as aplicações

1. Execute o aplicativo de servidor: a partir de um prompt de comando, digite python3 listener.py.
2. Execute o aplicativo cliente: a partir de um prompt de comando, digite python3 sender.py.

Parabéns, você criou um aplicativo Hybrid Connections de ponta a ponta usando Python!

Próximos passos

Neste início rápido, você criou aplicativos cliente e servidor Python que usavam WebSockets para enviar e receber mensagens. O recurso Conexões Híbridas do Azure Relay também dá suporte ao uso de HTTP para enviar e receber mensagens. Para saber como usar HTTP com Conexões Híbridas de Retransmissão do Azure, consulte o Guia de início rápido HTTP.

Neste início rápido, você usou Python para criar aplicativos cliente e servidor. Para saber como escrever aplicativos cliente e servidor usando o .NET Framework, consulte o início rápido HTTP do .NET ou o início rápido do HTTP do .NET.