Este recurso possibilita enviar solicitações HTTP(s) arbitrárias de uma placa, sala ou dispositivo de mesa para um servidor HTTP(S). Além disso, o dispositivo recebe a resposta que o servidor envia de volta. O dispositivo suporta os métodos de Publicar, Colocar, Correção, Obter e Excluir.
Ao usar macros, você pode enviar dados para um servidor HTTP(s) sempre que quiser. Você pode escolher quais dados enviar e estruturar como quiser. Ao fazer isso, você pode adaptar os dados a um serviço já estabelecido.
Medidas de segurança:
O recurso de solicitação de cliente HTTP(S) está desativado por padrão. Um administrador do sistema deve habilitar explicitamente o recurso para Ativado (
xConfiguration HttpClient Mode: On).O administrador do sistema pode impedir o uso de HTTP configurando seja Falso (
xConfiguration HttpClient AllowHTTP: False).O administrador do sistema pode especificar uma lista de servidores HTTP(s) para os quais o dispositivo tem permissão para enviar dados. (Consulte a
xCommand HttpClient Allow Hostnamecomandos.)O número de solicitações HTTP(S) simultâneas é limitado.
As configurações que são mencionadas neste artigo estão disponíveis na interface da web do dispositivo e na API. Os comandos estão disponíveis na API. Leia o artigo de Configurações avançadas para obter informações sobre como acessar a interface da web e usar a API.
Lista de servidores HTTP(s) permitidos
O administrador do sistema pode usar esses comandos para configurar e manter uma lista de até dez servidores HTTP(s) permitidos (hosts):
xCommand HttpClient Allow Hostname Add Expression: <Regular expression that matches the host name or IP address of the HTTP(S) server>xCommand HttpClient Allow Hostname ClearxCommand HttpClient Allow Hostname ListxCommand HttpClient Allow Hostname Remove Id: <id of an entry in the list>
Se a lista não estiver vazia, você pode enviar solicitações HTTP(s) apenas para os servidores da lista. Se a lista estiver em branco, você poderá enviar as solicitações para qualquer servidor HTTP(s).
A verificação contra a lista de servidores permitidos é executada quando se usa a transferência insegura (HTTP) e segura (HTTPS) de dados.
HTTPS sem validação de certificado
Ao enviar solicitações através de HTTPS, o dispositivo verifica o certificado do servidor HTTPS por padrão. Se o certificado do servidor HTTPS não for considerado válido, você recebe uma mensagem de erro. O dispositivo não envia dados para esse servidor.
Recomendamos usar HTTPS com validação de certificado. Se a validação do certificado não for possível, para On (
xConfiguration HttpClient AllowInsecureHTTPS: On
). Isso permite o uso do HTTPS sem validar o certificado do servidor.
Enviando solicitações HTTP(s)
Uma vez que o recurso de solicitação de cliente HTTP(S) está habilitado, você pode usar os seguintes comandos para enviar solicitações a um servidor HTTP(s).
<method>
é
Post
,
Put
,
Patch
,
Get
, ou
Delete
.
xCommand HttpClient <Method> [AllowInsecureHTTPS: <True/False>] [Header: <Header text>] [ResponseSizeLimit: <Maximum response size>] [ResultBody: <None/PlainText/Base64>] [Timeout: <Timeout period>] Url: <URL to send the request to>
Adicionar campos de header é opcional, mas você pode adicionar até 20 campos.
O comando
AllowInsecureHTTPS
o parâmetro tem um efeito apenas se o administrador do sistema permitiu o uso de HTTPS sem validar o certificado do servidor. Se sim, você pode enviar dados para o servidor sem validar o certificado do servidor se o parâmetro estiver definido como
True
. Se você deixar o parâmetro de fora ou defini-lo como
False
, os dados não são enviados se a validação do certificado falhar.
O comando
ResposenSizeLimit
o parâmetro é o tamanho máximo de carga útil (bytes) que o dispositivo aceita como uma resposta do servidor. Se a carga de resposta for maior do que este tamanho máximo, o comando retorna um erro de status. A mensagem de erro diz que o tamanho máximo de arquivo foi excedido. No entanto, isso não tem efeito no lado do servidor; o servidor recebeu e processou a solicitação corretamente.
Use a
ResultBody
parâmetro para decidir como formatar o corpo da resposta HTTP do servidor no resultado do comando. Você tem três opções:
None: Não inclua o corpo da resposta HTTP no resultado do comando.Base64: Base64 codificar o corpo antes de incluí-lo no resultado.PlainText: Inclua o corpo no resultado como texto simples. Se a resposta contiver letras não imprimíveis, o comando retornará um erro de status com uma mensagem dizendo que dados não imprimíveis foram encontrados.
Use a
Timeout
parâmetro para definir um período de tempo tempo (segundos). Se a solicitação não for concluída durante este período, a API retorna um erro.
Insira a carga útil (dados) logo após você ter emitido o comando. Qualquer coisa que você inserir, incluindo quebras de linha, é parte da carga útil. Quando terminar, termine com uma quebra de linha ("\n") e uma linha separada contendo apenas um ponto seguido por uma quebra de linha (".\n"). Agora o comando é executado e os dados são enviados ao servidor.
Exemplos
O corpo da mensagem é JSON em ambos os exemplos. Pode ser em qualquer formato, dependendo do formato esperado do serviço que está recebendo as mensagens.
Exemplo: Controle do dispositivo IoT usando a postagem HTTP
Aqui está uma função de macro que se conecta a uma luz que está conectada a uma Ponte de Matiz da Philips:
function hue_command(data) { var url = 'http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state'; var headers = 'Content-Type: application/json'; var command = '{"on":true}'; xapi.command('HttpClient Put', { 'Url': url, 'Header': headers }, command); }
Você pode fazer o mesmo na linha de comando usando a API:
xcommand HttpClient Put Header: "Content-Type: application/json" URL: "http://192.0.2.10/api/'ZXlU4tUtQ23Pjbdyl-kiyCjTs0i5ANDEu1ypJq0-/lights/1/state" {"on":true} .
Exemplo 2: Publicar dados em uma ferramenta de monitoramento usando a publicação HTTP
xcommand HttpClient Post Header: "Content-Type: application/json" URL: "https://mymonitoringserver.com/service/devicemonitoring" {"Message":"A user reported an issue with this system","systemName":"BoardRoom 4th floor","softwareVersion":"ce9.6.0","softwareReleaseDate":"2018-12-13","videoMonitors":"Dual"} .
Mais informações
Encontre mais detalhes sobre como usar as solicitações de clientes HTTP no guia de Personalização . Escolha a versão mais recente.
O suporte da Cisco (TAC) não suporta a depuração do código de terceiros, incluindo macros. Confira a comunidade do Desenvolvedor de colaboração Cisco se precisar de ajuda com macros e código de terceiros. Além disso, existem muitos recursos de desenvolvedores e integradores neste site.
