Com este recurso é possível enviar solicitações HTTP(S) arbitrárias de um dispositivo de mesa, de sala ou de quadro 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 Post, Put, Patch, Get e Delete.
Usando macros, você pode enviar dados para um servidor HTTP(S) sempre que desejar. Você pode escolher quais dados serão enviados e estruturá-los como quiser. Procedendo dessa forma, é possível adaptar os dados para um serviço já estabelecido.
Medidas de segurança:
-
O recurso de solicitação do cliente HTTP(S) é definido como desabilitado por padrão. Um administrador do sistema deve ativar explicitamente o recurso configurando o
como On (xConfiguration HttpClient Mode: On
). -
O administrador do sistema pode impedir o uso de HTTP, definindo
como Falso (xConfiguration HttpClient AllowHTTP: Falso
). -
O administrador do sistema pode especificar uma lista de servidores HTTP(S) para os quais o dispositivo pode enviar dados. (Consulte os comandos
xCommand HttpClient Allow Hostname
.) -
O número de solicitações HTTP(S) simultâneas é limitado.
As configurações citadas neste artigo estão disponíveis na interface da Web do dispositivo e na API. Comandos estão disponíveis na API. Leia o artigo Configurações avançadas para mais informações sobre como acessar a interface da Web e usar a API.
Lista de servidores HTTPs permitidos
O administrador do sistema pode usar estes comandos para configurar e manter uma lista de até dez servidores HTTP(S) autorizados (hosts):
-
xCommand HttpClient Allow Hostname Add Expression: <Expressão regular que corresponde ao nome do host ou endereço IP do servidor HTTPS>
-
xCommand HttpClient Allow Hostname Clear
-
xCommand HttpClient Allow Hostname List
-
xCommand HttpClient Allow Hostname Remove Id: <ID de uma entrada na lista >
Se a lista não estiver vazia, você poderá enviar solicitações HTTP(S) somente para os servidores na lista. Se a lista estiver vazia, você pode enviar solicitações para qualquer servidor HTTP(S).
A verificação em relação à lista de permitidos servidores é executada ambos ao usar vulneráveis (HTTP) e transferência (HTTPS) segura de dados.
HTTPS sem validação do certificado
Ao enviar solicitações em HTTPS, o dispositivo verificará o certificado do servidor HTTPS por padrão. Se o certificado do servidor HTTPS encontrado não for válido, você receberá uma mensagem de erro. O dispositivo não envia quaisquer dados para que o servidor.
Recomendamos usar HTTPS com validação do certificado. Se a validação do certificado não for possível, o administrador do sistema poderá definir xConfiguration HttpClient AllowInsecureHTTPS: On
). Assim, será possível usar o HTTPS sem validar o certificado do servidor.
Enviar solicitações HTTP(S)
Quando o recurso de solicitação do cliente HTTP(S) for ativado, você poderá usar os seguintes comandos para enviar solicitações para um servidor HTTP(S). O <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>
A adição de campos de cabeçalho é opcional, mas você pode adicionar até 20 campos.
O parâmetro AllowInsecureHTTPS
apenas funcionará se o administrador do sistema tiver permitido o uso de HTTPS sem precisar validar o certificado do servidor. Se este for o caso, você poderá 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 em branco ou defini-lo como False
, os dados não serão enviados caso a validação do certificado falhe.
O parâmetro
ResposenSizeLimit é o tamanho máximo do Payload (bytes) que o dispositivo aceita como resposta do servidor. Se a carga útil da resposta for maior que o tamanho máximo, o comando retornará um erro de status. A mensagem de erro informa que o tamanho máximo do arquivo foi excedido. No entanto, isso não afeta o lado do servidor; o servidor recebeu e processou a solicitação corretamente.
Use o parâmetro ResultBody
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
: o Base64 codifica o corpo antes de incluí-lo no resultado. -
PlainText
: inclua o corpo no resultado como texto sem formatação. Se a resposta contiver letras não imprimíveis, o comando retornará um erro de status com uma mensagem informando que foram encontrados dados não imprimíveis.
Use o parâmetro Timeout
para definir um período de tempo limite (segundos). Se a solicitação não for concluída durante esse período, a API retornará um erro.
Digite a carga (dados) logo após receber o comando. Tudo o que você digitar, inclusive quebras de linha, fará parte da carga. Ao finalizar, inclua uma quebra de linha ("\n") e uma linha separada contendo apenas um ponto final seguido de uma quebra de linha (". \n"). Agora o comando é executado e os dados são enviados para o servidor.
Exemplos
O corpo da mensagem está no formato JSON nos exemplos a seguir. Pode ser qualquer formato, dependendo do formato esperado do serviço que está recebendo as mensagens.
Exemplo 1: controle de dispositivo IoT usando HTTP POST
Esta é uma função de macro que ativa uma luz conectada a um Philips Hue Bridge:
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: gerar dados para uma ferramenta de monitoramento usando HTTP POST
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
Saiba mais sobre como usar as solicitações do cliente HTTP no Guia de personalização. Escolha a versão mais recente.
O suporte da Cisco (TAC) não é compatível com a depuração do código de terceiros, incluindo macros. Verifique a Comunidade de desenvolvedores da Cisco se precisar de ajuda com macros e código de terceiros. Além disso, existem muitos recursos integradores e para desenvolvedores neste site.