Cliente HTTP/HTTPS
O recurso de Cliente HTTP/HTTPS do HIscada Pro consiste, atualmente, em executar requisições HTTP ou HTTPS do HIscada Pro através da função global chamada HttpRequest via scripts do Kernel.
|
A função de requisição HTTP/HTTPS está disponível a partir da versão 1.7.00 do HIscada Pro e deve ser utilizada apenas em scripts do KERNEL. |
Protocolo HTTP
O Hypertext Transfer Protocol, da sigla HTTP (em português Protocolo de Transferência de Hipertexto) é um protocolo de comunicação (na camada de aplicação segundo o Modelo OSI) utilizado em sistemas de informação de hipermídia, distribuídos e colaborativos.
Este protocolo é a base para a comunicação de dados na Internet.
O HTTP funciona como um protocolo de requisição-resposta no modelo computacional cliente-servidor.
Um cliente HTTP geralmente é um navegador Web, porém, pode ser qualquer outra aplicação que realize requisições para um servidor, que pode ser, por exemplo, um site na internet ou no caso do HIscada Pro, um script LUA.
O cliente submete uma mensagem de requisição HTTP para o servidor. O servidor, é responsável por fornecer os recursos, como arquivos HTML e outros conteúdos (como objetos JSON), ou realiza outras funções de interesse do cliente.
Para isso, o servidor retorna uma mensagem de resposta para o cliente com o conteúdo solicitado.
A resposta contém informações de estado completas sobre a requisição e pode também conter o conteúdo solicitado no corpo de sua mensagem.
Para maiores detalhes sobre o protocolo HTTP, acesse este link.
Execução de requisições HTTP no HIscada Pro
O cliente HTTP do HIscada Pro tem suporte para execução de requisições através dos seguintes métodos HTTP:
Método |
Descrição |
|---|---|
GET |
Utilizado para OBTER uma lista de recursos ou as informações de um recurso em específico |
POST |
Utilizado para CRIAR um recurso |
PUT |
Utilizado para ATUALIZAR todas as informações de um recurso |
PATCH |
Utilizado para ATUALIZAR parte das informações de um recurso |
DELETE |
Utilizado para remover um recurso |
result, error, status, content, headers = HttpRequest(parameters)
Descrição:
Executa a requisição HTTP de acordo com a configuração informada nos parâmetros de entrada da função(parameters).
Parâmetros de entrada:
parameters: tabela Lua com a configuração da requisição HTTP/HTTPS. As chaves da tabela de configuração devem ser as seguintes:
Parâmetro |
Descrição |
Exemplo |
|---|---|---|
url |
Endereço HTTP ou HTTPS da requisição |
https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/ |
http_method |
Método HTTP da requisição(GET, POST, PUT, PATCH ou DELETE) |
GET |
payload |
String com o conteúdo de criação(quando utilizado o método POST) ou atualização(quando utilizado o método PUT ou PATCH) de um recurso |
|
query_string |
Tabela LUA com os parâmetros de consulta de recursos via URL |
{[“data_id”]=14185, [“start”]=”2023-01-15T12:00:00”, [“end”]=”2023-01-13:00:00”} |
headers |
Tabela LUA com os parâmetros de cabeçalho da requisição |
{[“Accept-Language”]=”pt-br”, [“Content-Type”]=”application/json”} |
auth_method |
Método de autenticação da requisição(caso necessário): basic ou bearer |
basic |
user_auth |
Usuário da requisição(quando utilizado o método de autenticação Basic Authentication) |
teste@hitecnologia.com.br |
password_auth |
Senha do usuário da requisição(quando utilizado o método de autenticação Basic Authentication) |
teste123456 |
bearer_auth_token |
Token de autenticação(quando utilizado o método de autenticação Bearer) |
|
timeout |
Tempo(em segundos) para aguardar a resposta da requisição realizada |
60 |
Parâmetros de saída:
result: Booleano indicando true se a requisição foi executada com sucesso, ou false caso de alguma falha.
error: Nulo(nil) indicando que não houve erro na requisição ou o texto referente ao eventual erro que ocorreu neste processo.
status: Número inteiro com o status de resposta da requisição HTTP. Para maiores informações sobre os status possíveis para reposta de uma requisição HTTP, acesse aqui.
content: String com o conteúdo de resposta da requisição HTTP.
headers: String com o conteúdo do cabeçalho de resposta da requisição HTTP.
Exemplos de utilização
Todos os exemplos abaixo utilizaram em suas requisições HTTP os endpoints disponibilizados pela API REST do Portal de Telemetria da HI Tecnologia.
A API REST do Portal Telemetria retorna(responde) nas requisições realizadas para a mesma objetos denotados em JSON(Java Script Object Notation). Este o formato é uma coleção de pares de nome/valor comum em várias linguagens de programação, sendo tratada como um objeto, registro, estrutura, dicionário, tabela de hash, lista com chave ou matriz associativa.
Para maiores detalhes sobre esta API, acesse a Documentação da API REST.
Portanto, os exemplos consideraram as requisições HTTP através dos seguintes métodos:
Método |
Descrição |
|---|---|
Exemplo de uma requisição HTTP para obter informações do histórico de um determinado Dado no Portal |
|
Exemplo de uma requisição para criar um Dado no Portal |
|
Exemplo de uma requisição para atualizar as informações de um determinado Dado no Portal |
|
Exemplo de uma requisição para remover um determinado Dado do Portal |
Requisição com o método GET
Neste exemplo, foi configurado os parâmetros da requisição HTTP para utilizar o método GET(responsável por obter recursos em um servidor) em um endpoint(URL) da API REST do Portal de Telemetria.
O endpoint utilizado retorna uma lista de objetos JSON que representam um registro no histórico de valores coletados pelo Portal no equipamento remoto para um determinado Dado.
Portanto, vamos a explicação de como a requisição foi configurada no exemplo:
Parâmetro |
Explicação |
|---|---|
url |
Endereço do endpoint de acesso ao histórico de Dados do Portal |
http_method |
Método da requisição HTTP(definido como GET) |
query_string |
Tabela LUA com os parâmetros de filtro(suportados pela API) do histórico de Dados(filtro por um Dado e período específicos) |
headers |
Tabela LUA com os cabeçalhos da requisição(neste caso, informado ao servidor que conteúdo retornado deve ser em JSON) |
auth_method |
Método de autenticação definido como Basic Authentication(um dos métodos suportados pela API do Portal) |
user_auth |
Usuário para a autenticação no Portal(que utiliza um endereço de e-mail) |
password_auth |
Senha do usuário para autenticação no Portal |
timeout |
Tempo(em segundos) de aguardo para o retorno da resposta pela API do Portal |
|
O exemplo abaixo utiliza um módulo externo LUA chamado json.lua para realizar a conversão da resposta do endpoint(que é em JSON) para uma tabela LUA. Copie o conteúdo deste módulo clicando aqui e crie um arquivo chamado json.lua no diretório LUA do projeto com este conteúdo. O roteiro de criação de módulos externos documenta e exemplifica como criar módulos de funções. |
----------------------------------------------------------------------------
-- Define tabela LUA com os parâmetros de configuração da requisição HTTP
----------------------------------------------------------------------------
local request_parameters = {
url='https://api.telemetria.hitecnologia.com.br/rest/v1/data_history/',
http_method='GET',
query_string={["data_id"]=1, ["start"]="2023-05-15T100:00:00", ["end"]= "2023-05-15T23:59:59"},
headers={["Content-Type"]= "application/json"},
auth_method='basic',
user_auth='teste@hitecnologia.com.br',
password_auth='teste123456',
timeout=60
}
----------------------------------------------------------------------------
-- Executa a requisição HTTP
----------------------------------------------------------------------------
local result, error, status_code, content, headers = HttpRequest(
request_parameters
)
-----------------------------------------------------------------------------
-- Caso a variável result seja false, indica que houve um erro na requisição
-- HTTP. Caso não, indica que a requisição foi realizada com sucesso para URL
-- informada, porém, a reposta dependerá do código do status retornado pelo
-- servidor no qual a requisição foi realizada
-----------------------------------------------------------------------------
if (result == false) then
if (error ~= nil) then
print("Erro na execução da requisição HTTP: " .. error)
else
print("Erro na execução da requisição HTTP")
end
return
else
print("Requisição HTTP realizada com sucesso!")
if (status_code ~= nil) then
print("STATUS DA RESPOSTA: " .. status_code)
else
print("STATUS DA RESPOSTA: NULO")
end
if (content ~= nil) then
print("CONTEÚDO DA RESPOSTA: " .. content)
else
print("CONTEÚDO DA RESPOSTA: NULO")
end
if (headers ~= nil) then
print("CABEÇALHOS DA RESPOSTA: " .. headers)
else
print("CABEÇALHOS DA RESPOSTA: NULO")
end
end
----------------------------------------------------------------------------
-- Caso o status da resposta da requisição não seja de 200, significa que,
-- para este endpoint, o conteúdo esperado não será retornado por algum
-- erro(como informações inválidas para autenticação, por exemplo).
----------------------------------------------------------------------------
if (status_code ~= 200) then
print("Status de resposta da requisição[" .. status_code .."] não foi de sucesso")
return
end
----------------------------------------------------------------------------
-- Importa módulo de manipulação de objetos JSON via LUA
----------------------------------------------------------------------------
local JSON = require("JSON")
----------------------------------------------------------------------------
-- Transforma o conteúdo de resposta da requisição ao endpoint de histórico
-- de Dados do Portal recebido(string JSON) em uma tabela LUA
-- Este endpoint retorna um objeto JSON caso o seguinte conteúdo(exemplo):
-- [
-- {
-- "data_id": 100,
-- "date_time": "2023-03-01T12:15:51.277695+00:00",
-- "value": "30.50000"
-- },
-- {
-- "data_id": 101,
-- "date_time": "2023-03-01T12:15:51.277695+00:00",
-- "value": "150.00000"
-- },
-- ...
-- ]
-- Onde cada chave indica:
-- data_id: Identificador do Dado (ID) no Portal
-- date_time: Data/hora (no formato ISO 8601 e em UTC) do registro.
-- value: String com o valor associado ao Dado do registro.
-- Exemplo da tabela LUA após a decodificação do JSON de resposta:
-- {[1]={["data_id"]=100, ["value"]=30.50000, ["date_time"]=2023-03-01T12:15:51.277695+00:00}...}
----------------------------------------------------------------------------
local data_history_table = JSON:decode(content)
----------------------------------------------------------------------------
-- Percorre os registros de histórico do Dado retornados para que seja
-- montada uma string com todos esses eventos
----------------------------------------------------------------------------
for i = 1, #data_history_table do
----------------------------------------------------------------------------
-- Obtém um regsitro de histórico na tabela LUA
-- Ex: {["data_id"] = 100,["value"] = 30.50000,["date_time"] = 2023-03-01T12:15:51.277695+00:00}
----------------------------------------------------------------------------
local data_history_item = data_history_table[i]
----------------------------------------------------------------------------
-- Obtém o ID do Dado do registro. Exemplo: 100
----------------------------------------------------------------------------
local event_data_id = data_history_item['data_id']
----------------------------------------------------------------------------
-- Obtém a data/hora do registro já a transformando em um DateTime LUA
-- Exemplo: 15/05/2023 12:15:51
----------------------------------------------------------------------------
local event_datetime = DateTime.FromIsoFormat(data_history_item['date_time'])
----------------------------------------------------------------------------
-- Converte o timezone da data/hora de UTC para America/Sao_Paulo(-3 horas)
-- Exemplo: 15/05/2023 09:15:51
----------------------------------------------------------------------------
local event_datetime_with_tz = DateTime(event_datetime:GetValue() - 3/24)
----------------------------------------------------------------------------
-- Obtém o valor do Dado do registro. Exemplo: 30.50000
----------------------------------------------------------------------------
local event_value = data_history_item['value']
print("Registro em: " .. tostring(event_datetime_with_tz) .. " - ID do Dado: " .. event_data_id .. " - Valor: ".. event_value)
end
Resultado da execução do exemplo acima:
Requisição HTTP realizada com sucesso!
STATUS DA RESPOSTA: 200
CONTEÚDO DA RESPOSTA: [{"data_id":100,"date_time":"2023-03-01T12:15:51.277695+00:00","value":"30.50000"},{"data_id":101,"date_time":"2023-03-01T12:15:51.277695+00:00","value":"150.00000"}]
CABEÇALHOS DA RESPOSTA: {'Server': 'nginx/1.18.0 (Ubuntu)', 'Date': 'Mon, 15 May 2023 16:00:02 GMT', 'Content-Type': 'application/json', ...}
Registro em: 15/05/2023 09:15:51 - ID do Dado: 100 - Valor: 30.50000
Registro em: 15/05/2023 09:15:51 - ID do Dado: 101 - Valor: 150.00000
Requisição com o método POST
Neste exemplo, foi configurado os parâmetros da requisição HTTP para utilizar o método POST(responsável criar um recurso no servidor) em um endpoint(URL) da API REST do Portal de Telemetria.
O endpoint utilizado neste caso foi o de Dados., onde após a criação com sucesso do Dado, é retornado um objeto JSON que representa as informações do recurso criado.
Portanto, vamos a explicação de como a requisição foi configurada no exemplo:
Parâmetro |
Explicação |
|---|---|
url |
Endereço do endpoint para criação de Dados no Portal |
http_method |
Método da requisição HTTP(definido como POST) |
payload |
String contendo a definição de um objeto JSON com os parâmetros de criação de um Dado |
headers |
Tabela LUA com os cabeçalhos da requisição(neste caso, informado ao servidor que conteúdo retornado deve ser em JSON) |
auth_method |
Método de autenticação definido como Basic Authentication(um dos métodos suportados pela API do Portal) |
user_auth |
Usuário para a autenticação no Portal(que utiliza um endereço de e-mail) |
password_auth |
Senha do usuário para autenticação no Portal |
timeout |
Tempo(em segundos) de aguardo para o retorno da resposta pela API do Portal |
--------------------------------------------------------------------------------
-- Exemplo de requisição HTTP utilizando o POST(criar recursos)
--------------------------------------------------------------------------------
local request_parameters = {
url='https://api.telemetria.hitecnologia.com.br/rest/v1/data/',
http_method='POST',
payload='{"name": "Temperatura", "memory_address": 0, "device_id": 1, "source_value_id": 1}',
headers={["Content-Type"]= "application/json"},
auth_method='basic',
user_auth='teste@hitecnologia.com.br',
password_auth='teste123456',
timeout=60
}
--------------------------------------------------------------------------------
-- Executa a requisição HTTP
--------------------------------------------------------------------------------
local result, error, status_code, content, headers = HttpRequest(
request_parameters
)
--------------------------------------------------------------------------------
-- Caso a variável result seja false, indica que houve um erro na requisição
-- HTTP. Caso não, indica que a requisição foi realizada com sucesso para URL
-- informada, porém, a reposta dependerá do código do status retornado pelo
-- servidor no qual a requisição foi realizada
--------------------------------------------------------------------------------
if (result == false) then
if (error ~= nil) then
print("Erro na execução da requisição HTTP: " .. error)
else
print("Erro na execução da requisição HTTP")
end
return
else
print("Requisição HTTP realizada com sucesso!")
if (status_code ~= nil) then
print("STATUS DA RESPOSTA: " .. status_code)
else
print("STATUS DA RESPOSTA: NULO")
end
if (content ~= nil) then
print("CONTEÚDO DA RESPOSTA: " .. content)
else
print("CONTEÚDO DA RESPOSTA: NULO")
end
if (headers ~= nil) then
print("CABEÇALHOS DA RESPOSTA: " .. headers)
else
print("CABEÇALHOS DA RESPOSTA: NULO")
end
end
Requisição com o método PATCH
Neste exemplo, foi configurado os parâmetros da requisição HTTP para utilizar o método PATCH(responsável atualizar informações de um recurso no servidor) em um endpoint(URL) da API REST do Portal de Telemetria.
O endpoint utilizado neste caso foi o de Dados., onde após a criação com sucesso do Dado, é retornado um objeto JSON que representa as informações do recurso atualizado.
Portanto, vamos a explicação de como a requisição foi configurada no exemplo:
Parâmetro |
Explicação |
|---|---|
url |
Endereço do endpoint para atualização de um determinado Dado(utilizando o seu ID na URL) |
http_method |
Método da requisição HTTP(definido como PATCH) |
payload |
String contendo a definição de um objeto JSON com os parâmetros de atualização do Dado |
headers |
Tabela LUA com os cabeçalhos da requisição. No caso do Portal, é exigida a informação da versão do recurso que se deseja alterar(chamado de ETAG). Então essa informação foi fornecida pela chave If-Match. |
auth_method |
Método de autenticação definido como Basic Authentication(um dos métodos suportados pela API do Portal) |
user_auth |
Usuário para a autenticação no Portal(que utiliza um endereço de e-mail) |
password_auth |
Senha do usuário para autenticação no Portal |
timeout |
Tempo(em segundos) de aguardo para o retorno da resposta pela API do Portal |
--------------------------------------------------------------------------------
-- Exemplo de requisição HTTP utilizando o PATCH(atualizar um recurso)
--------------------------------------------------------------------------------
local http_request_parameters = {
url='https://api.telemetria.hitecnologia.com.br/rest/v1/data/1/',
http_method='PATCH',
payload='{"name": "Temperatura Ambiente"}',
headers={["Content-Type"]= "application/json", ["If-Match"]= '\\"d2e9f9129c6a4ce6cd24fc10e2389b9d\\"'},
auth_method='basic',
user_auth='teste@hitecnologia.com.br',
password_auth='teste123456',
timeout=60
}
--------------------------------------------------------------------------------
-- Executa a requisição HTTP
--------------------------------------------------------------------------------
local result, error, status_code, content, headers = HttpRequest(
http_request_parameters
)
--------------------------------------------------------------------------------
-- Caso a variável result seja false, indica que houve um erro na requisição
-- HTTP. Caso não, indica que a requisição foi realizada com sucesso para URL
-- informada, porém, a reposta dependerá do código do status retornado pelo
-- servidor no qual a requisição foi realizada
--------------------------------------------------------------------------------
if (result == false) then
if (error ~= nil) then
print("Erro na execução da requisição HTTP: " .. error)
else
print("Erro na execução da requisição HTTP")
end
return
else
print("Requisição HTTP realizada com sucesso!")
if (status_code ~= nil) then
print("STATUS DA RESPOSTA: " .. status_code)
else
print("STATUS DA RESPOSTA: NULO")
end
if (content ~= nil) then
print("CONTEÚDO DA RESPOSTA: " .. content)
else
print("CONTEÚDO DA RESPOSTA: NULO")
end
if (headers ~= nil) then
print("CABEÇALHOS DA RESPOSTA: " .. headers)
else
print("CABEÇALHOS DA RESPOSTA: NULO")
end
end
Requisição com o método DELETE
Neste exemplo, foi configurado os parâmetros da requisição HTTP para utilizar o método DELETE(responsável remover um determinado recurso no servidor) em um endpoint(URL) da API REST do Portal de Telemetria.
O endpoint utilizado neste caso foi o de Dados., onde após a remoção com sucesso de uma Área de Processo, é retornado um status 204(No Content).
Portanto, vamos a explicação de como a requisição foi configurada no exemplo:
Parâmetro |
Explicação |
|---|---|
url |
Endereço do endpoint para atualização de um determinado Dado(utilizando o seu ID na URL) |
http_method |
Método da requisição HTTP(definido como DELETE) |
headers |
Tabela LUA com os cabeçalhos da requisição. No caso do Portal, é exigida a informação da versão do recurso que se deseja remover(chamado de ETAG). Então essa informação foi fornecida pela chave If-Match. |
auth_method |
Método de autenticação definido como Basic Authentication(um dos métodos suportados pela API do Portal) |
user_auth |
Usuário para a autenticação no Portal(que utiliza um endereço de e-mail) |
password_auth |
Senha do usuário para autenticação no Portal |
timeout |
Tempo(em segundos) de aguardo para o retorno da resposta pela API do Portal |
--------------------------------------------------------------------------------
-- Exemplo de requisição HTTP utilizando o DELETE(remover um recurso)
--------------------------------------------------------------------------------
local http_request_parameters = {
url='https://api.telemetria.hitecnologia.com.br/rest/v1/data/1/',
http_method='DELETE',
headers={["If-Match"]= '\\"d2e9f9129c6a4ce6cd24fc10e2389b9d\\"'},
auth_method='basic',
user_auth='teste@hitecnologia.com.br',
password_auth='teste123456',
timeout=60
}
--------------------------------------------------------------------------------
-- Executa a requisição HTTP
--------------------------------------------------------------------------------
local result, error, status_code, content, headers = HttpRequest(
http_request_parameters
)
--------------------------------------------------------------------------------
-- Caso a variável result seja false, indica que houve um erro na requisição
-- HTTP. Caso não, indica que a requisição foi realizada com sucesso para URL
-- informada, porém, a reposta dependerá do código do status retornado pelo
-- servidor no qual a requisição foi realizada
--------------------------------------------------------------------------------
if (result == false) then
if (error ~= nil) then
print("Erro na execução da requisição HTTP: " .. error)
else
print("Erro na execução da requisição HTTP")
end
return
else
print("Requisição HTTP realizada com sucesso!")
if (status_code ~= nil) then
print("STATUS DA RESPOSTA: " .. status_code)
else
print("STATUS DA RESPOSTA: NULO")
end
if (headers ~= nil) then
print("CABEÇALHOS DA RESPOSTA: " .. headers)
else
print("CABEÇALHOS DA RESPOSTA: NULO")
end
end