Referencia de línea de comandos de túneles de desarrollo

  • Artículo

Los túneles de desarrollo ofrecen una herramienta de interfaz de línea de comandos (CLI) para crear y administrar tuneles dev. En este artículo se explican la sintaxis y los parámetros de los distintos devtunnel comandos de la CLI.

Importante

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas.

Nota:

devtunnel Los comandos de la CLI están en versión preliminar. Los nombres y opciones de comandos pueden cambiar en futuras versiones.

Opciones globales

  • -v, --verbose: habilite la salida detallada.
  • -?, -h, --help: muestra información de ayuda y uso.

Administración de credenciales de usuario

El servicio de túnel de desarrollo requiere el inicio de sesión para autorizar la administración y el acceso a tuneles dev. De forma predeterminada, un túnel de desarrollo solo es accesible para el usuario que creó el túnel de desarrollo, aunque ese usuario puede conceder acceso a otros usuarios.

Después de iniciar sesión, el token de inicio de sesión se almacena en caché en la cadena de claves segura del sistema y es válido durante varios días antes de la expiración. Al cerrar sesión de la CLI se borra este token almacenado en caché, pero no se borran las cookies del explorador. Lo que puede incluir tokens de acceso del túnel de desarrollo si se usó un explorador para autenticarse con un túnel de desarrollo.

Comando Descripción
devtunnel user login Inicie sesión con una cuenta de Microsoft o GitHub.
devtunnel user logout Borrar el token almacenado en caché
devtunnel user show Mostrar el estado de inicio de sesión actual

Sugerencia

devtunnel login y devtunnel logout son comandos abreviados para iniciar y cerrar sesión.

Estos son algunos ejemplos sobre el uso de estos comandos:

Ejemplos Descripción
devtunnel user login Inicio de sesión con una organización de Microsoft (Id. de Microsoft Entra) o una cuenta personal
devtunnel user login -g Inicio de sesión con una cuenta de GitHub
devtunnel user login -d Inicio de sesión con una cuenta de GitHub con el inicio de sesión de código de dispositivo, si no es posible iniciar sesión en el explorador interactivo local
devtunnel user login -g -d Inicio de sesión con una cuenta de GitHub con el inicio de sesión de código de dispositivo, si no es posible iniciar sesión en el explorador interactivo local

Hospedar un túnel de desarrollo

devtunnel host es el comando principal que se usa para hospedar el túnel de desarrollo. El comando debe ejecutarse en el sistema host que ejecuta el servidor al que desea acceder a través del túnel de desarrollo.

Comando Descripción
devtunnel host Hospede un túnel de desarrollo. Si no se especifica un identificador de túnel de desarrollo, se crea un nuevo túnel de desarrollo temporal que se elimina una vez cerrada la conexión.

Estos son algunos ejemplos sobre el uso de este comando:

Ejemplos Descripción
devtunnel host -p 3000 Hospede un túnel de desarrollo temporal para un puerto de escucha de servidor 3000 en el sistema host.
devtunnel host -p 3000 --allow-anonymous Hospede un túnel de desarrollo temporal y habilite el acceso de cliente anónimo.
devtunnel host -p 3000 5000 Hospede un túnel de desarrollo temporal para los servidores locales que escuchan en los puertos 3000 y 5000.
devtunnel host -p 8443 --protocol https Hospede un túnel de desarrollo temporal para un servidor que escuche en el puerto 8443 que usa el protocolo HTTPS.
devtunnel host -p 8000 --expiration 2d Hospede un túnel de desarrollo temporal con una hora de expiración personalizada. El mínimo es de 1 hora (1h) y el máximo es de 30 días (30d).
devtunnel host TUNNELID Hospede un túnel de desarrollo existente que se haya configurado anteriormente.

Advertencia

Permitir el acceso anónimo a un túnel de desarrollo significa que cualquier persona de Internet puede conectarse al servidor local, si pueden adivinar el identificador del túnel de desarrollo.

Presione Control-C para detener el proceso del host del túnel de desarrollo y finalizar las conexiones de cliente a través del túnel de desarrollo. Si no se proporcionó un túnel de desarrollo existente, el túnel de desarrollo que creó automáticamente el proceso se eliminará al salir del proceso.

Conectar a un túnel de desarrollo

Uso de la interfaz de usuario de reenvío web:

El devtunnel host comando muestra una salida similar a la siguiente:

Hosting port 3000 at https://l3rs99qw-3000.usw2.devtunnels.ms/

El URI mostrado https: es único para el puerto del túnel de desarrollo: el primer componente es un subdominio que contiene el identificador de túnel de desarrollo y el número de puerto especificados.

Si el puerto hospedado se conecta a un servidor web, ese URI se puede abrir directamente en un explorador, desde cualquier lugar. Si el acceso al túnel de desarrollo requiere autorización, la solicitud inicial al URI le redirigirá a una página de inicio de sesión y volverá al sitio una vez autorizado el usuario.

Si el puerto hospedado se conecta a un servicio web, ese URI se puede usar como URI base mediante una aplicación cliente de servicio web. Sin embargo, si el túnel de desarrollo no permite el acceso anónimo, el cliente de servicio web normalmente no sabrá cómo autenticarse. Si el servicio web es seguro para exponerse públicamente, considere la posibilidad de permitir el acceso anónimo. De lo contrario, un cliente de servicio web puede agregar un encabezado de solicitud con un token de acceso de túnel de desarrollo para autorizar la conexión.

Con la CLI:

En lugar de que un explorador cliente o una aplicación se conecten directamente a un URI de retransmisión de túnel de desarrollo, la CLI se puede usar para reenviar conexiones desde un puerto del cliente a un puerto de túnel de desarrollo. Es posible que el cliente también tenga que iniciar sesión si el túnel de desarrollo no permite el acceso anónimo.

devtunnel connect TUNNELID
  • Reemplace por TUNNELID el mismo identificador de túnel de desarrollo que se usó en el host.

La salida correcta del cliente es similar a la siguiente:

Connected to tunnel: l3rs99qw
SSH: Forwarding from 127.0.0.1:3000 to host port 3000.
SSH: Forwarding from [::1]:3000 to host port 3000.

Ahora, el servidor que se ha compartido en el puerto 3000 del host está disponible en localhost:3000 en el cliente, mediante IPv4 o IPv6. (El prefijo "SSH" se debe a que el servicio de túnel de desarrollo se basa en el protocolo SSH estándar para el reenvío de puertos). Si el puerto hospedado se conecta a un servidor web, http://localhost:3000/ se puede abrir en un explorador. En este caso, no se requiere ninguna autorización adicional porque el token de inicio de sesión de la CLI del cliente se usó para autorizar la conexión si es necesario.

Avanzado: Administrar tuneles dev

Es posible crear un túnel de desarrollo sin hospedarlo aún. Esto es útil para la configuración y administración avanzadas del túnel de desarrollo, como:

  • Enumerar todos los tuneles dev propiedad
  • Adición y eliminación de puertos de un túnel de desarrollo
  • Administración de controles de acceso de túnel de desarrollo
  • Adición de metadatos a un túnel de desarrollo, como la descripción y las etiquetas
Comando Descripción
devtunnel create Creación de un túnel de desarrollo persistente
devtunnel list Enumerar tuneles dev
devtunnel show Mostrar detalles del túnel de desarrollo
devtunnel update Actualizar las propiedades del túnel de desarrollo
devtunnel delete Eliminar un túnel de desarrollo
devtunnel delete-all Eliminar todos los tuneles dev

Estos son algunos ejemplos sobre el uso de estos comandos:

Ejemplos Descripción
devtunnel create -a Cree un túnel de desarrollo persistente que permita el acceso anónimo.
devtunnel create -d 'my tunnel description' Cree un túnel de desarrollo persistente con una descripción no buscable.
devtunnel create --expiration 4h Cree un túnel de desarrollo persistente con una hora de expiración personalizada. El mínimo es de 1 hora (1h) y el máximo es de 30 días (30d).
devtunnel create myTunnelID Cree un túnel de desarrollo persistente con un identificador de túnel personalizado.
devtunnel create --tags my-web-app v1 Cree un túnel de desarrollo persistente y aplique etiquetas que se puedan buscar.
devtunnel list --tags my-web-app Enumera tuneles dev que tienen cualquiera de las etiquetas especificadas.
devtunnel list --all-tags my-web-app v1 Enumera tuneles dev que tienen todas las etiquetas especificadas.
devtunnel show Muestra los detalles del túnel de desarrollo usado por última vez.
devtunnel show TUNNELID Muestra los detalles de un túnel de desarrollo.
devtunnel update TUNNELID -d 'my new tunnel description' Actualice la descripción de un túnel de desarrollo.
devtunnel update TUNNELID --remove-tags Quite todas las etiquetas de un túnel de desarrollo.
devtunnel update TUNNELID --expiration 10d Actualice un túnel de desarrollo con una nueva hora de expiración personalizada. El mínimo es de 1 hora (1h) y el máximo es de 30 días (30d).
devtunnel delete TUNNELID Elimina un túnel de desarrollo.
devtunnel delete-all Elimine todos los tuneles dev.

Sugerencia

La mayoría de los comandos de la CLI funcionan implícitamente en el túnel de desarrollo usado por última vez, aunque hay una opción para especificar un identificador de túnel de desarrollo si es necesario.

Avanzado: Administración de puertos de túnel de desarrollo

Un túnel de desarrollo creado con el devtunnel create comando inicialmente no tiene puertos. Use devtunnel port comandos para agregar puertos antes de hospedar:

Comando Descripción
devtunnel port create Creación de un puerto de túnel de desarrollo
devtunnel port list Enumeración de puertos de túnel de desarrollo
devtunnel port show Mostrar los detalles del puerto del túnel de desarrollo
devtunnel port update Actualizar las propiedades del puerto del túnel de desarrollo
devtunnel port delete Eliminación de un puerto de túnel de desarrollo
Ejemplos Descripción
devtunnel port create -p 3000 --protocol http Adición de un puerto con el protocolo especificado
devtunnel port list TUNNELID Enumeración de puertos actuales
devtunnel port show TUNNELID -p 3000 Mostrar los detalles del puerto 3000
devtunnel port update -p 3000 --description 'frontend port' Actualización de una descripción del puerto del túnel de desarrollo
devtunnel port delete -p 3000 Eliminación de un puerto

Al crear un puerto, el protocolo puede especificarse opcionalmente, si la detección automática no funciona correctamente. Las opciones actuales son "http", "https" o "auto" (valor predeterminado). Si el puerto hospedado es HTTPS, se recomienda establecer el protocolo de puerto en "https"; de lo contrario, es probable que "auto" esté bien.

Después de configurar un túnel de desarrollo mediante los comandos anteriores, empiece a hospedarlo:

devtunnel host

Avanzado: Administrar el acceso al túnel de desarrollo

Con los comandos siguientes, se pueden emitir tokens de acceso del túnel de desarrollo para proporcionar a otros clientes acceso al túnel de desarrollo sin permitir el acceso anónimo. Los comandos de entrada de control de acceso permiten configurar el control de acceso en tuneles dev y puertos de túnel de desarrollo.

Comando Descripción
devtunnel token Problema del token de acceso del túnel de desarrollo
devtunnel access create Creación de una entrada de control de acceso
devtunnel access list Enumerar entradas de control de acceso
devtunnel access delete Eliminación de una entrada de control de acceso
devtunnel access reset Restablecer las entradas del control de acceso al valor predeterminado

Estos son algunos ejemplos sobre el uso de estos comandos:

Ejemplos Descripción
devtunnel token TUNNELID --scopes connect Obtenga un token de acceso "connect" para un túnel de desarrollo que se pueda compartir para proporcionar acceso temporal al túnel de desarrollo.
devtunnel access create TUNNELID --anonymous Habilite el acceso de cliente anónimo en el túnel de desarrollo.
devtunnel access create TUNNELID --anonymous --expiration 4h Habilite el acceso de cliente anónimo en el túnel de desarrollo con un tiempo de expiración de control de acceso personalizado. El mínimo es de 1 hora (1h) y el máximo es de 30 días (30d).
devtunnel access create TUNNELID --port 3000 --anonymous Habilite el acceso de cliente anónimo en el puerto 3000.
devtunnel access create TUNNELID --tenant Habilite el acceso de inquilino actual de Microsoft Entra en el túnel de desarrollo.
devtunnel access create TUNNELID --org ORG Habilite el acceso de una organización de GitHub por nombre en el túnel de desarrollo.

Sugerencia

El acceso a la organización de GitHub requiere la instalación de la aplicación Dev Tunnels de GitHub en la organización.

Comandos complementarios

Estos comandos se pueden usar si necesita establecer o anular explícitamente esta caché local del túnel de desarrollo usado por última vez.

Comando Descripción
devtunnel set Establecimiento del túnel de desarrollo predeterminado
devtunnel unset Borrar el túnel de desarrollo predeterminado

Comandos de diagnóstico

Comando Descripción
devtunnel clusters Enumeración de clústeres de servicio disponibles por ubicación
devtunnel echo Ejecución de un servidor de eco de diagnóstico en un puerto local
devtunnel ping Envío de mensajes de diagnóstico a un servidor de eco remoto
Ejemplos Descripción
devtunnel clusters --ping Enumere los clústeres de servicio disponibles ordenados por latencia medida.
devtunnel echo http --port 8080 --interface 127.0.0.1 Inicie un servidor de diagnóstico http local en el puerto 8080.

Solución de problemas

Para solucionar problemas con la devtunnel CLI, las siguientes sugerencias pueden ser útiles:

  • Asegúrese de que está en la versión más reciente de la devtunnel CLI. Compruebe la versión instalada actualmente con devtunnel --version.
  • La --verbose opción imprime los mensajes de depuración, que pueden proporcionar información de diagnóstico adicional.