Histórico da Página

Ativando o serviço HTTP REST para requisições API REST

O serviço que permite acionar requisições HTTP REST no AppServer é disponibilizado em uma porta diferente das portas definidas para os serviços HTTP e HTTPS, e este serviço HTTP REST não basta definir o ambiente do Logix e em que porta ficará disponível para acesso, mas precisa executar um JOB que disponibiliza um conjunto de Threads, denominadas "Working Threads" que ficam "a espera" de requisições API REST para serem executadas. Apesar do serviço HTTP REST funcionar semelhante ao serviço de requisições HTTP SOAP, este serviço responde única e exclusivamente requisições no formato REST.

As configurações para ativar o serviço REST para atender as requisições HTTP REST das aplicações WEB resume-se a:

[ONSTART]
REFRESHRATE=30
JOBS=HTTPJOB 

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=logix12_ora  ;*** Nome do Ambiente Logix, pode ser modificado

[HTTPV11]
ENABLE=1
SOCKETS=HTTPREST
TIMEOUT=600 

[HTTPREST]
PORT=8580   ;*** Porta utilizada na URI, pode ser modificada
URIS=URIAPPS
SECURITY=0 

[URIAPPS]
URL=/   ;*** Endereço base pra atender as requisições REST. Exemplo: http://localhost:8580/api/vdp/v1/clientes
INSTANCES=2,10   ;*** Número de instâncias utilizadas para atender as requisições REST (quantidade inicial e máxima de instâncias)
ONSTART=LOGIXRESTSTART
ONCONNECT=LOGIXRESTCONNECT
ONEXIT=LOGIXRESTEXIT 
CORSENABLE=1
ALLOWORIGIN=*  ;;*** Aqui o padrão assumido é * mas caso exista uma restrição de acessos é preciso configurar a lista de permissões

Seção ONSTART

A seção ONSTART é responsável por definir a lista de JOBS que serão iniciados automaticamente no momento em que o AppServer é iniciado e a chave REFRESHRATE é responsável por monitorar se a lista de JOBS indicados está em execução a cada intervalo de segundos informado. Quando algum JOB informado na lista não estiver em execução, o AppServer automaticamente irá colocar o JOB para executar, garantindo assim que não ficará inativo, caso ocorra qualquer interrupção.

No exemplo abaixo veja que foi definido o JOB chamado HTTPJOB, sendo que o AppServer pode ter definido na chave JOBS uma lista, separada por vírgula ( , ).

Seção HTTPJOB

Na seção HTTPJOB, a chave MAIN é definida com a função HTTP_START existente no Repositório Logix e que é responsável por dar início a um conjunto de "Working Treads" que se mantém em execução no AppServer, a espera de requisições API REST para execução.

As quantidades de Working Threads (instâncias) para atender as requisições HTTP REST simultâneas é configurada conforme Instances.

Seção HTTPV11

Para habilitar o HTTP para REST será necessário criar a seção abaixo no appserver.ini:

[HTTPV11]
Enable=1
Sockets=HTTPREST
Timeout=600 

Parâmetro

Descrição

Obrigatório

A chave Sockets referencia as seções com a configuração de porta e URL que a mesma irá atender, permitindo que o Application Server seja configurado com mais de uma porta HTTP do REST.   Exemplo:  Sockets=HTTPREST,HTTPREST2

É necessário definir ao menos uma seção.

Seção Socket HTTPREST

Para a seção Socket chamada HTTPREST deve-se indicar algumas configurações como URIS que apontam os endPoints disponíveis pra requisições REST, número de porta em que as requisições REST podem ser acionadas, e determinar a segurança, onde irá exigir ou não autenticação.

[HTTPREST] 
Port=8085
URIs=URIAPPS
Security=1

Parâmetro

Descrição

Obrigatório

Definindo o endpoint /apps para definir a localização dos artefatos das aplicações WEB

Um ENDPOINT para acesso de artefatos WEB no appserver.ini é sempre definido com o seguinte formato:  

Image Added

Onde:

SERVER_IP_OR_HOSTNAME → Nome do servidor (HOSTNAME) ou número de endereço IP do servidor correspondente ao IP do appserver Logix.
PROTOCOL_PORT → Número da porta do protocolo que será utilizado para acesso das aplicações WEB, que pode ser a porta indicada para o serviço HTTP, HTTPS ou porta MULTIPROTOCOLO.
ENDPOINT → é o caminho relativo de um endereço (URL) que permite que um cliente acesse um recurso específico de um servidor web, ou seja isso dará acesso ao ponto final de comunicação entre um browser e os artefatos de uma aplicação WEB no servidor.

Na definição de uma seção de um ENDPOINT para acesso de recursos WEB a partir do Appserver é possível definir:

• O diretório no disco do servidor de aplicação onde estão localizados os artefatos WEB
• O ambiente (ENVIRONMENT) que este acesso irá utilizar, ou seja, qual é o RPO, banco de dados e tudo mais que irá respeitar a execução desta aplicação WEB.
• Entre outras configurações padrões adotadas para todo ENDPOINT configurado, conforme o exemplo abaixo:

Para execução das aplicações WEB Logix é preciso definir obrigatoriamente o endpoint como /apps conforme indicando a pasta raiz onde os artefatos WEB e também o ambiente que será usado pra execução conforme abaixo:

[172.23.155.24:9194/apps]
ENVIRONMENT=logix_prd
RESPONSEJOB=JOBWEB
DEFAULTPAGE=index.html ;*** Recurso web inicial acessado na pasta da aplicação web, quando não for informado na URL (Exemplo: https://localhost:9194/apps/gtrib/gtr10000)
PATH=c:\totvs\web\apps
UPLOADPATH=\upload
CACHE-CONTROL=no-store
PRAGMA=no-cache

O número de IP 172.23.155.24 e PORTA 9194, no exemplo acima, foram apenas utilizados como exemplo, pois devem respeitar os respectivos dados definidos para o Appserver Logix.

       logix.app.hostname = "meuservidor"

[meuservidor:9194/apps]
ENVIRONMENT=logix_prd
RESPONSEJOB=JOBWEB
DEFAULTPAGE=index.html ;*** Recurso web inicial acessado na pasta da aplicação web, quando não for informado na URL (Exemplo: https://localhost:9194/apps/gtrib/gtr10000)
PATH=c:\totvs\web\apps
UPLOADPATH=\upload
CACHE-CONTROL=no-store
PRAGMA=no-cache

Ativando o serviço HTTP REST para requisições API REST

O serviço que permite acionar requisições HTTP REST no AppServer é disponibilizado em uma porta diferente das portas definidas para os serviços HTTP e HTTPS, e este serviço HTTP REST não basta definir o ambiente do Logix e em que porta ficará disponível para acesso, mas precisa executar um JOB que disponibiliza um conjunto de Threads, denominadas "Working Threads" que ficam "a espera" de requisições API REST para serem executadas. Apesar do serviço HTTP REST funcionar semelhante ao serviço de requisições HTTP SOAP, este serviço responde única e exclusivamente requisições no formato REST.

As configurações para ativar o serviço REST para atender as requisições HTTP REST das aplicações WEB resume-se a definir as seções abaixo no arquivo appserver.ini:

[ONSTART]
REFRESHRATE=30
JOBS=HTTPJOB 

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=logix12_ora  ;*** Nome do Ambiente Logix, pode ser modificado

[HTTPV11]
ENABLE=1
SOCKETS=HTTPREST
TIMEOUT=600 

[HTTPREST]
PORT=8580   ;*** Porta utilizada na URI, pode ser modificada
URIS=URIAPPS
SECURITY=1  ;*** quando aqui o valor for 1, é obrigatório configurar seções HTTPS e SSLCONFIGURE indicando o certificado SSL.

[URIAPPS]
URL=/   ;*** Endereço base pra atender as requisições REST. Exemplo: http://localhost:8580/api/vdp/v1/clientes
INSTANCES=10,40,3,10   ;*** Número de instâncias utilizadas para atender as requisições REST (quantidade inicial e máxima de instâncias, quantidade minima livre e quantidade de novas instancias quando limite mímimo livre for alcançado)
ONSTART=LOGIXRESTSTART
ONCONNECT=LOGIXRESTCONNECT
ONEXIT=LOGIXRESTEXIT 
CORSENABLE=1
ALLOWORIGIN=*  ;;*** Aqui o padrão assumido é * mas caso exista uma restrição de acessos é preciso configurar a lista de permissões

[HTTPV11]
Enable=1
Sockets=HTTPREST
Timeout=600 

[HTTPREST] 
Port=8085
URIs=URIAPPS
Security=1

Disponibilização de artefatos das aplicações WEB Logix no AppServer

Após configurar e ativar os serviços HTTP, HTTP REST e definir o ENDPOINT/apps no AppServer, falta apenas disponibilizar os artefatos WEB para execução da interface das aplicações WEB Logix. 

Para isso você precisará descompactar os arquivos de artefatos WEB correspondentes a cada aplicação WEB na respectiva pasta e subpasta indicada na documentação disponibilizada por cada time Logix responsável pela aplicação.

Na pasta principal de cada aplicação WEB existirá o arquivo inicial chamado Index.html.

Segue um exemplo para a aplicação WEB Logix GTR10000, disponibilizada na estrutura /apps/gtrib/gtr10000:

Image Added

Image Added

É muito importante que todos artefatos da aplicação WEB estejam na pasta raiz da aplicação. Vejam que nesta imagem acima o arquivo index.html e todos demais artefatos WEB do programa gtr10000 estão na pasta final gtr10000/. 

Veja que além da pasta /apps ser definida em letras minúsculas, é preciso também respeitar o caminho relativo da aplicação WEB em questão, que neste caso é /gtrib que também exige uso de letras mínúsculas.

A pasta /gtrib é a indicação do módulo ao qual pertence a aplicação e essa informação consta no pacote de atualização da aplicação ou na respectiva documentação disponibilizada no portal TDN pelo time responsável pela aplicação. Em caso de dúvidas sobre a pasta de destino da aplicação WEB, entre em contato com o time de atendimento responsável pela aplicação.

A última parte deste caminho relativo é a pasta da aplicação, que neste caso é a pasta /gtr10000 e novamente ela precisa OBRIGATORIAMENTE ser definida com letras minúsculas.

Portanto todo caminhor relativo da aplicação WEB e também a pasta principal da aplicação precisa ser criada sempre com letras minúsculas, para evitarmos qualquer tipo de problema no acesso das aplicações via browser, que tem por padrão diferenciar letras maiúsculas e minúsculas (CASE SENSITIVE).

A chave URIs referencia as seções com a configuração da URL que a porta irá atender. Pode ser configurado mais de uma URL.
Exemplo: URIs=HTTPURI,HTTPURI2

Configure ao menos uma seção.

Indica se a autenticação de requisição esta habilitada.

Recomenda-se fortemente que esta chave seja configurada como 1 (Habilitado) para garantir a exigência de autenticação em todas as requisições HTTP REST executadas pelo AppServer.

Ao ativar SECURITY=1 é necessário configurar outras chaves que indicarão o caminho do certificado e chave, e o protocolo de segurança utilizado (SSL/TLS).

Image Removed
O HTTP do REST verifica existência do campo Authorization no HEADER da requisição para requisições REST em geral, mas para requisições REST realizadas a partir de aplicações WEB a autenticação é realizada exclusivamente pelo existência do campo AppSession no HEADER, e ambos os controles de autorização são realizados pelo framework do produto que está utilizando o protocolo.

Seção URIAPPS 

Exemplo de configuração da seção URIAPPS para requisições REST das aplicações WEB Logix:

Parâmetro

Descrição

Obrigatório

Configuração de inicialização de working threads. 

A chave Instances é configurada como no HTTP do SOAP.
Para mais detalhes acesse Instances.

Determina a função acionada ao iniciar qualquer Thread destinada ao funcionamento do REST.
Sempre manter como LOGIXRESTSTART para produto ERP Logix.

Função de inicialização, conexão e execução de qualquer Thread destinada a uma requisição REST.
Sempre manter como LOGIXRESTCONNECT para produto ERP Logix.

Determina a função acionada na finalização de qualquer Thread destinada ao funcionamento do REST
Sempre manter como LOGIXRESTEXIT para produto ERP Logix.

Ativa o recurso para gerenciamento de páginas permissíveis de recebimento de dados do servidor, recurso anti-CSRF.

É sugerido manter esta chave com o valor 1 para aceitar requisições de APPs Web Logix.

Essa chave limita os IPs que o REST do Logix pode responder, deve conter o valor * (responder para qualquer IP) ou informar a lista de IPs aceitos.

É importante sempre avaliar o conceito de uso para avaliar o uso ou não das chaves CORSENABLE e ALLOWORIGIN.

Por padrão é sugerido informar como * (Qualquer IP).

Disponibilização de artefatos das aplicações WEB Logix no AppServer

Após configurar e ativar os serviços HTTP e HTTP REST no AppServer, falta apenas disponibilizar os artefatos WEB para execução da interface das aplicações WEB Logix. 

Para isso você precisará descompactar os arquivos de artefatos WEB correspondentes a cada aplicação WEB na respectiva pasta e subpasta indicada na documentação disponibilizada por cada time Logix responsável pela aplicação.

Na pasta principal de cada aplicação WEB existirá o arquivo inicial chamado Index.html.

Segue um exemplo para a aplicação WEB Logix GTR10000, disponibilizada na estrutura /apps/gtrib/gtr10000:

Image Removed

PRONTO! Agora que os artefatos WEB das aplicações Logix já estão devidamente alocados na pasta raiz apps, que é a mesma pasta configurada nas chave PATH da seção [<SERVER_IP>:<PORT_HTTP_or_HTTPS>/apps] do appserver, é só realizar o teste de acesso da aplicação WEB a partir do menu Logix.