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 configurando o Modo > HttpClient para Ativado ( xConfiguration HttpClient Mode: On ).

  • O administrador do sistema pode impedir o uso de HTTP configurando o protocolo HttpClient > Permitir queHTTP 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 Hostname comandos.)

  • 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 Clear

  • xCommand HttpClient Allow Hostname List

  • xCommand 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, o administrador do sistema pode configurar o HttpClient > AllowInsecureHTTPS 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.