HTTP
Incluída no Macro DeckEnvie requisições HTTP a partir de um botão e salve valores da resposta em variáveis.
A página da integração HTTP com a chave ativada e sem opções de configuração
- GET, POST, PUT, PATCH, DELETE e outros, com parâmetros de consulta e cabeçalhos
- Autenticação basic, bearer token ou chave de API em cabeçalho
- Corpo em JSON, formulário, texto ou envio de arquivo
- Salve o status, os cabeçalhos ou valores JSON em variáveis
- Variáveis nos valores de parâmetros de consulta e cabeçalhos
A integração HTTP envia requisições web a partir do Macro Deck. Use-a para chamar um webhook, controlar um dispositivo da sua rede que tenha uma API web ou ler um valor de um serviço online e mostrá-lo em um botão. Ela vem com o Macro Deck e já está ativada desde o início, então não há nada para conectar nem conta para entrar.
Duas ações
Enviar requisição HTTP monta uma requisição completa. Escolha o Método, informe a URL e adicione Parâmetros de consulta e Cabeçalhos como pares de nome e valor. Em Tipo do corpo, escolha none, json, form, text ou multipart (um envio de arquivo com campos de formulário extras). Autenticação oferece basic (nome de usuário e senha), bearer (um token) e header (um token em um cabeçalho com o nome que você definir, por exemplo X-Api-Key). Status esperado define quais respostas contam como sucesso, 2xx por padrão. Também é possível definir o Tempo limite, desativar Seguir redirecionamentos e limitar o Tamanho máximo da resposta (bytes).
Capturas salvam partes da resposta em variáveis. Cada linha associa um nome de variável a um seletor: $status, $ok, $duration, $body, $truncated, $headers, $header:<name> ou um caminho JSON como data.items[0].name. Uma variável que ainda não existe é criada.
Obter valor JSON é a forma curta para ler um único valor: informe a URL, um Caminho JSON e a variável em Salvar em variável.
Exemplos de uso
- Um botão que publica
{"text": "Stream is live"}em um webhook de chat com Enviar requisição HTTP e tipo do corpojson. - Um botão que liga uma tomada inteligente da sua rede pela API web local dela.
- Um botão que lê o preço atual de uma API pública com Obter valor JSON e o mostra no rótulo com
{{ vars.price }}. - Um fluxo que envia uma requisição, captura
$statuse usa Se / Senão para deixar o botão vermelho quando o servidor não responder com200.
Os valores de parâmetros de consulta e de cabeçalhos podem conter variáveis, por exemplo {{ vars.channel }}. A requisição é executada no computador em que o Macro Deck está rodando, então endereços como http://192.168.1.20 alcançam dispositivos da rede desse computador. Uma ação falha com uma mensagem clara quando o servidor não pode ser alcançado, a requisição excede o tempo limite, o certificado TLS é recusado ou o status não é o esperado.
O que é necessário
- Macro Deck 3 no Windows, macOS ou Linux
- O endereço da API web ou do webhook que você quer chamar
- Uma chave de API, token ou senha, se o serviço exigir
Configuração
Passo 1: Confira se a integração está ativada
No Macro Deck, clique em Integrações na barra lateral e depois em HTTP. A chave no canto superior direito vem ativada por padrão; ative-a se estiver desativada. Não há nada para configurar: a aba Visão geral mostra Nenhuma opção de configuração disponível para esta integração.
Passo 2: Adicione uma ação HTTP a um botão
Na página Deck, clique em um botão. O deck precisa estar desbloqueado: se o botão Bloquear aparece no canto superior direito, ele está. O editor abre com Toque curto selecionado. Clique em + Adicionar ação, selecione HTTP à esquerda da caixa de diálogo Adicionar ação e escolha Enviar requisição HTTP, ou Obter valor JSON se quiser ler só um valor. Também é possível digitar o nome em Pesquisar ações....
Passo 3: Informe a requisição
Escolha o Método e informe a URL. Adicione Parâmetros de consulta e Cabeçalhos se a API precisar deles. Para uma requisição com dados, escolha o Tipo do corpo e preencha o Corpo JSON, os Campos de formulário ou o Corpo de texto.
Passo 4: Adicione a autenticação
Se o serviço precisar de login ou chave, escolha em Autenticação:
basiccom Nome de usuário e Senha / token,bearercom o token em Senha / token, ouheadercom o Nome do cabeçalho e a chave em Senha / token. A maioria dos serviços mostra as chaves de API ou os tokens nas configurações da conta ou de desenvolvedor.Passo 5: Salve valores da resposta
Para usar a resposta, adicione linhas em Capturas: um nome de variável e um seletor como
$statusou um caminho JSON comodata.temperature. Com Obter valor JSON, informe o Caminho JSON e escolha a variável em Salvar em variável.Passo 6: Teste o botão
Clique em Executar no editor para enviar a requisição na hora, ou salve e pressione o botão. Se a ação falhar, a mensagem dela diz o motivo, por exemplo que o servidor não pôde ser alcançado ou que o status não correspondeu ao Status esperado.
Ações2
Coloque estas ações em um botão ou execute-as a partir de um fluxo.
- Enviar requisição HTTP
- Envia uma requisição HTTP configurável e pode capturar a resposta em variáveis.
- Obter valor JSON
- Busca uma URL e grava um valor da resposta JSON em uma variável.
Perguntas frequentes
Onde minhas chaves de API e senhas ficam armazenadas?
O que é informado em Senha / token fica armazenado criptografado e só vira texto simples quando a requisição é enviada. Os valores digitados em Cabeçalhos ficam armazenados sem criptografia e vão junto em perfis exportados, então coloque chaves e tokens nos campos de autenticação.
Posso chamar um dispositivo da minha rede local?
Sim. A requisição é enviada pelo computador em que o Macro Deck está rodando, então qualquer endereço que esse computador alcance funciona. Para um dispositivo com certificado autoassinado, é possível desativar Validar certificado TLS, mas faça isso só para dispositivos da sua própria rede.
Por que a ação falha mesmo com o servidor respondendo?
A resposta não correspondeu ao Status esperado, que é 2xx por padrão. Informe o código de status que a API realmente devolve, um intervalo como 200-204, uma lista, ou any para aceitar qualquer status. Obter valor JSON sempre espera uma resposta 2xx.
Quais caminhos JSON posso usar?
Use pontos e índices, por exemplo data.items[0].name ou [0].id, ou $ para o documento inteiro. Em Capturas, os seletores reservados como $status têm prioridade, então um campo que se chama de fato status é lido com $.status.
Preciso criar as variáveis antes?
Não. Quando uma captura ou Salvar em variável indica uma variável que não existe, o Macro Deck a cria. Se já existir uma variável com esse nome e outro tipo, o salvamento falha com uma mensagem.
Mais em Casa inteligente e web
Home Assistant
Incluída no Macro DeckAcione luzes, execute cenas e scripts e mostre no seu deck os estados ao vivo do seu Home Assistant.
AdGuard Home
Incluída no Macro DeckAtive, desative ou pause a proteção do AdGuard Home e mostre as estatísticas dele no seu deck.
Feeds RSS
Incluída no Macro DeckAcompanhe feeds RSS e Atom, mostre os artigos mais recentes em widgets e reaja quando chegam artigos novos.
Clima
Incluída no Macro DeckMostre no deck o clima atual e a previsão para os seus locais, sem chave de API.