Referência de linha de comando de túneis de desenvolvimento

Os túneis de desenvolvimento oferecem uma ferramenta de interface de linha de comando (CLI) para criar e gerenciar túneis de desenvolvimento. Este artigo explica a sintaxe e os parâmetros para os vários devtunnel comandos da CLI.

Importante

Esta funcionalidade está atualmente em pré-visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas.

Nota

devtunnel Os comandos da CLI estão em visualização. Os nomes e as opções dos comandos podem ser alterados em versões futuras.

Opções globais

• -v, --verbose: Habilite a saída detalhada.
• -?, -h, --help: Mostrar informações de ajuda e uso.

Gerenciar credenciais de usuário

O serviço de túnel de desenvolvimento requer login para autorizar o gerenciamento e o acesso aos túneis de desenvolvimento. Por padrão, um túnel de desenvolvimento só é acessível ao usuário que criou o túnel de desenvolvimento, embora esse usuário possa conceder acesso a outros.

Após o login, o token de login é armazenado em cache no conjunto de chaves seguro do sistema e é válido por vários dias antes da expiração. O logout da CLI limpa esse token armazenado em cache, mas não limpa nenhum cookie do navegador. O que pode incluir tokens de acesso ao túnel de desenvolvimento se um navegador foi usado para autenticar com um túnel de desenvolvimento.

Comando	Description
devtunnel user login	Faça login com uma conta Microsoft ou GitHub.
devtunnel user logout	Limpar o token armazenado em cache
devtunnel user show	Mostrar estado de início de sessão atual

Gorjeta

devtunnel login e são comandos abreviados para entrar e devtunnel logout sair.

Aqui estão alguns exemplos sobre o uso desses comandos:

Exemplos	Description
devtunnel user login	Iniciar sessão com uma organização Microsoft (Microsoft Entra ID) ou conta pessoal
devtunnel user login -g	Faça login com uma conta do GitHub
devtunnel user login -d	Faça login com uma conta do GitHub com login de código de dispositivo, se o login do navegador interativo local não for possível
devtunnel user login -g -d	Faça login com uma conta do GitHub com login de código de dispositivo, se o login do navegador interativo local não for possível

Hospedar um túnel de desenvolvimento

devtunnel host é o comando principal usado para hospedar seu túnel de desenvolvimento. O comando deve ser executado no sistema host que executa o servidor que você deseja que seja acessado através do túnel de desenvolvimento.

Comando	Description
devtunnel host	Hospede um túnel de desenvolvimento. Se um ID de túnel de desenvolvimento não for especificado, um novo túnel de desenvolvimento temporário será criado que será excluído assim que a conexão for fechada.

Aqui estão alguns exemplos sobre o uso deste comando:

Exemplos	Description
devtunnel host -p 3000	Hospede um túnel de desenvolvimento temporário para uma porta de escuta de servidor 3000 no sistema host.
devtunnel host -p 3000 --allow-anonymous	Hospede um túnel de desenvolvimento temporário e habilite o acesso de cliente anônimo.
devtunnel host -p 3000 5000	Hospede um túnel de desenvolvimento temporário para servidores locais escutando nas portas 3000 e 5000.
devtunnel host -p 8443 --protocol https	Hospede um túnel de desenvolvimento temporário para um servidor escutando na porta 8443 que usa o protocolo HTTPS.
devtunnel host -p 8000 --expiration 2d	Hospede um túnel de desenvolvimento temporário com um tempo de expiração personalizado. O mínimo é de 1 hora (1h) e o máximo é de 30 dias (30d).
devtunnel host TUNNELID	Hospede um túnel de desenvolvimento existente que tenha sido configurado anteriormente.

Aviso

Permitir o acesso anônimo a um túnel de desenvolvimento significa que qualquer pessoa na Internet pode se conectar ao seu servidor local, se puder adivinhar o ID do túnel de desenvolvimento.

Pressione Control-C para interromper o processo de host do túnel de desenvolvimento e encerrar todas as conexões de cliente através do túnel de desenvolvimento. Se um túnel de desenvolvimento existente não foi fornecido, o túnel de desenvolvimento que foi criado automaticamente pelo processo será excluído na saída do processo.

Conectar-se a um túnel de desenvolvimento

Usando a interface do usuário de encaminhamento da Web:

O devtunnel host comando mostra uma saída semelhante à seguinte:

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

O URI exibido https: é exclusivo para a porta do túnel de desenvolvimento: o primeiro componente é um subdomínio que contém o ID do túnel de desenvolvimento e o número da porta fornecidos.

Se a porta hospedada se conectar a um servidor Web, esse URI poderá ser aberto diretamente em um navegador, de qualquer lugar. Se o acesso ao túnel de desenvolvimento exigir autorização, a solicitação inicial para o URI será redirecionada para uma página de login e retornará ao site depois que o usuário for autorizado.

Se a porta hospedada se conectar a um serviço Web, esse URI poderá ser usado como o URI base por um aplicativo cliente de serviço Web. No entanto, se o túnel de desenvolvimento não permitir acesso anônimo, o cliente de serviço Web normalmente não saberá como autenticar. Se o serviço Web for seguro para expor publicamente, considere permitir acesso anônimo. Caso contrário, um cliente de serviço Web pode adicionar um cabeçalho de solicitação com um token de acesso ao túnel de desenvolvimento para autorizar a conexão.

Usando a CLI:

Em vez de ter um navegador cliente ou aplicativo conectado diretamente a um URI de retransmissão de túnel de desenvolvimento, a CLI pode ser usada para encaminhar conexões de uma porta no cliente para uma porta de túnel de desenvolvimento. O cliente também pode precisar fazer login, se o túnel de desenvolvimento não permitir acesso anônimo.

devtunnel connect TUNNELID

• Substitua TUNNELID pelo mesmo id de túnel de desenvolvimento que foi usado no host.

A saída bem-sucedida do cliente é semelhante à seguinte:

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.

Agora, o servidor que foi compartilhado na porta 3000 do host está disponível no localhost:3000 cliente, usando IPv4 ou IPv6. (O prefixo "SSH" é porque o serviço de túnel de desenvolvimento se baseia no protocolo SSH padrão para encaminhamento de portas.) Se a porta hospedada se conectar a um servidor web, poderá http://localhost:3000/ ser aberta em um navegador. Nesse caso, nenhuma autorização adicional é necessária porque o token de login da CLI do cliente foi usado para autorizar a conexão, se necessário.

Avançado: Gerenciar túneis de desenvolvimento

É possível criar um túnel de desenvolvimento sem hospedá-lo ainda. Isso é útil para configuração e gerenciamento avançados de túnel de desenvolvimento, como:

• Listando todos os túneis de desenvolvimento de propriedade
• Adicionando e removendo portas de um túnel de desenvolvimento
• Gerenciando controles de acesso ao túnel de desenvolvimento
• Adicionando metadados a um túnel de desenvolvimento, como descrição e tags

Comando	Description
devtunnel create	Criar um túnel de desenvolvimento persistente
devtunnel list	Listar túneis de desenvolvimento
devtunnel show	Mostrar detalhes do túnel de desenvolvimento
devtunnel update	Atualizar propriedades do túnel de desenvolvimento
devtunnel delete	Excluir um túnel de desenvolvimento
devtunnel delete-all	Excluir todos os túneis de desenvolvimento

Aqui estão alguns exemplos sobre o uso desses comandos:

Exemplos	Description
devtunnel create -a	Crie um túnel de desenvolvimento persistente que permita acesso anônimo.
devtunnel create -d 'my tunnel description'	Crie um túnel de desenvolvimento persistente com uma descrição não pesquisável.
devtunnel create --expiration 4h	Crie um túnel de desenvolvimento persistente com um tempo de expiração personalizado. O mínimo é de 1 hora (1h) e o máximo é de 30 dias (30d).
devtunnel create myTunnelID	Crie um túnel de desenvolvimento persistente com um ID de túnel personalizado.
devtunnel create --tags my-web-app v1	Crie um túnel de desenvolvimento persistente e aplique tags pesquisáveis.
devtunnel list --tags my-web-app	Liste túneis de desenvolvimento que tenham qualquer uma das tags especificadas.
devtunnel list --all-tags my-web-app v1	Liste túneis de desenvolvimento que tenham todas as tags especificadas.
devtunnel show	Mostrar detalhes do último túnel de desenvolvimento usado.
devtunnel show TUNNELID	Mostrar detalhes de um túnel de desenvolvimento.
devtunnel update TUNNELID -d 'my new tunnel description'	Atualize a descrição de um túnel de desenvolvimento.
devtunnel update TUNNELID --remove-tags	Remova todas as tags de um túnel de desenvolvimento.
devtunnel update TUNNELID --expiration 10d	Atualize um túnel de desenvolvimento com um novo tempo de expiração personalizado. O mínimo é de 1 hora (1h) e o máximo é de 30 dias (30d).
devtunnel delete TUNNELID	Exclua um túnel de desenvolvimento.
devtunnel delete-all	Exclua todos os seus túneis de desenvolvimento.

Gorjeta

A maioria dos comandos da CLI opera no último túnel de desenvolvimento usado implicitamente, embora haja uma opção para especificar um ID de túnel de desenvolvimento, se necessário.

Avançado: Gerenciar portas de túnel de desenvolvimento

Um túnel de desenvolvimento criado usando o devtunnel create comando inicialmente não tem portas. Use devtunnel port comandos para adicionar portas antes de hospedar:

Comando	Description
devtunnel port create	Criar uma porta de túnel de desenvolvimento
devtunnel port list	Listar portas de túnel de desenvolvimento
devtunnel port show	Mostrar detalhes da porta do túnel de desenvolvimento
devtunnel port update	Atualizar propriedades da porta do túnel de desenvolvimento
devtunnel port delete	Excluir uma porta de túnel de desenvolvimento

Exemplos	Description
devtunnel port create -p 3000 --protocol http	Adicionar uma porta com o protocolo especificado
devtunnel port list TUNNELID	Listar portas atuais
devtunnel port show TUNNELID -p 3000	Mostrar os detalhes da porta 3000
devtunnel port update -p 3000 --description 'frontend port'	Atualizar uma descrição da porta do túnel de desenvolvimento
devtunnel port delete -p 3000	Excluir uma porta

Ao criar uma porta, o protocolo pode opcionalmente ser especificado, se a deteção automática não funcionar corretamente. As opções atuais são "http", "https" ou "auto" (padrão). Se a porta hospedada for HTTPS, é recomendável definir o protocolo de porta como "https"; caso contrário, "auto" é provavelmente bom.

Depois de configurar um túnel de desenvolvimento usando os comandos acima, comece a hospedá-lo:

devtunnel host

Avançado: Gerencie o acesso ao túnel de desenvolvimento

Com os comandos a seguir, os tokens de acesso ao túnel de desenvolvimento podem ser emitidos para fornecer a outros clientes acesso ao seu túnel de desenvolvimento sem permitir acesso anônimo. Os comandos de entrada de controle de acesso permitem configurar o controle de acesso em túneis de desenvolvimento e portas de túnel de desenvolvimento.

Comando	Description
devtunnel token	Emitir token de acesso ao túnel de desenvolvimento
devtunnel access create	Criar uma entrada de controle de acesso
devtunnel access list	Listar entradas de controle de acesso
devtunnel access delete	Excluir uma entrada de controle de acesso
devtunnel access reset	Redefinir entradas de controle de acesso para padrão

Aqui estão alguns exemplos sobre o uso desses comandos:

Exemplos	Description
devtunnel token TUNNELID --scopes connect	Obtenha um token de acesso 'connect' para um túnel de desenvolvimento que pode ser compartilhado para fornecer acesso temporário ao túnel de desenvolvimento.
devtunnel access create TUNNELID --anonymous	Habilite o acesso de cliente anônimo no túnel de desenvolvimento.
devtunnel access create TUNNELID --anonymous --expiration 4h	Habilite o acesso de cliente anônimo no túnel de desenvolvimento com um tempo de expiração de controle de acesso personalizado. O mínimo é de 1 hora (1h) e o máximo é de 30 dias (30d).
devtunnel access create TUNNELID --port 3000 --anonymous	Habilite o acesso de cliente anônimo na porta 3000.
devtunnel access create TUNNELID --tenant	Habilite o acesso atual do locatário do Microsoft Entra no túnel de desenvolvimento.
devtunnel access create TUNNELID --org ORG	Habilite o acesso de uma organização do GitHub pelo nome no túnel de desenvolvimento.

Gorjeta

O acesso à organização do GitHub requer a instalação do aplicativo GitHub Dev Tunnels na organização.

Comandos suplementares

Esses comandos podem ser usados se você precisar definir ou desdefinir explicitamente esse cache local do túnel de desenvolvimento usado pela última vez.

Comando	Description
devtunnel set	Definir túnel de desenvolvimento padrão
devtunnel unset	Limpar túnel de desenvolvimento padrão

Comandos de diagnóstico

Comando	Description
devtunnel clusters	Listar clusters de serviço disponíveis por local
devtunnel echo	Executar um servidor de eco de diagnóstico em uma porta local
devtunnel ping	Enviar mensagens de diagnóstico para um servidor de eco remoto

Exemplos	Description
devtunnel clusters --ping	Liste os clusters de serviço disponíveis classificados por latência medida.
devtunnel echo http --port 8080 --interface 127.0.0.1	Inicie um servidor de diagnóstico http local na porta 8080.

Resolução de Problemas

Para solucionar problemas com a devtunnel CLI, as seguintes dicas podem ser úteis:

• Verifique se você está na versão mais recente da devtunnel CLI. Verifique a versão atualmente instalada com devtunnel --version.
• A --verbose opção imprime mensagens de depuração, que podem fornecer informações de diagnóstico extras.