Para que o sistema TSS possibilite uma maior configuração e segurança de acesso às suas APIs REST, foi implementado o TSS REST SERVER, com uma camada de autenticação para as APIs REST do TSS.
Este documento tem o objetivo de ilustrar a configuração do TSS REST SERVER a ser realizada no arquivo appserver.ini do TSS.
O TSS REST SERVER é o substituto para o REST 2.0 do Framework Protheus como configuração de REST para (e somente) o TSS.
Para que isso, será necessário realizar a troca do REST 2.0 presente nos releases de TSS 12.1.2310 ou versões inferiores para o novo TSS REST SERVER, que será o REST oficial e sustentada para release do TSS igual ou superiores a 12.1.2410. As configurações de REST presentes em releases do TSS inferiores à 12.1.2410 poderão ser mantidas mas não terão suporte a autenticação de APIs em REST.
A seguir, serão detalhadas as configurações do novo TSS REST SERVER.
As configurações detalhadas aqui são de uso exclusivo do produto TSS. |
Neste capitulo iremos abordar as configurações mínimas ou simplificada para o correto funcionamento do novo TSS REST SERVER.
Para isso basta informar as seguintes seções e chaves no arquivo de appserver.ini do TSS.
São elas:
[TSSREST_CONFIG]
Servers=TSSREST_SERVER
[TSSREST_SERVER]
Port=1322
URIs=TSSREST_URI
[TSSREST_URI]
URL=/rest/tss
[JOBTSSREST]
main=TSSREST_START
environment=SPED
[ONSTART]
JOBS=JOBTSSREST
REFRESHRATE=10
O JOBTSSREST deverá ser incluído junto dos demais jobs presentes na seção [ONSTART] e, uma vez que esteja presente, o job referente ao REST 2.0 do Framework poderá ser removido. |
Aqui serão detalhadas todas as seções e chaves possíveis de serem configuradas para um maior controle do(s) servidor(es) e serviço(s) REST do TSS REST SERVER.
Para para um melhor entendimento, serão quebradas por seções a serem incluídas no appserver.ini do TSS.
[TSSREST_CONFIG]
Seção responsável por iniciar as configurações do TSS REST SERVER (HTTPSERVER).
De todos os nomes de seções que serão tratados neste documento, esta é a única seção que se deve manter o nome TSSREST_CONFIG.
Abaixo serão detalhadas as chaves desta seção:
| Chave | Descrição | Valores Possíveis | Obrigatório | Valor padrão |
|---|---|---|---|---|
| Enable | Responsável por habilitar ou desabilitar a subida/criação do TSS REST SERVER (HTTPSERVER). | 0=Desabilitado ou 1=Habilitado | Não | 1 |
| Servers | Nome das seções de servers com configuração de porta e URL. Por ela é possível definir um ou mais servidores, sendo assim, pode-se informar uma lista. Como exemplo será adotado o nome TSSREST_SERVER. | Nome livre | Sim | |
| Charset | Chave para definir com qual Codepage que será configurado no REST. | Exemplos: ASCII, UTF-8, ANSI e ISO-8859-1 | Não | UTF-8 |
| Log | Define se habilita ou não a gravação dos logs de eventos do HttpServer. Para mais detalhes | 0=Desabilitado ou 1=Habilitado | Não | 0 |
[TSSREST_CONFIG] Enable=1 Servers=TSSREST_SERVER Charset=UTF-8 Log=1 |
Define as configurações de cada servidor HTTP e/ou HTTPS informados na seção [TSSREST_CONFIG] pela chave {SERVERS}.
Os nomes aqui preenchidos podem variar conforme desejado, neste caso vamos tratar como [TSSREST_SERVER] apenas para exemplo.
Abaixo serão detalhadas as chaves desta seção:
| Chave | Descrição | Valores Possíveis | Obrigatório | Valor padrão |
|---|---|---|---|---|
| Port | Define a porta em que o servidor atenderá às requisições após ativado. | Campo livre | Sim | |
| URIs | Define o nome das sessões (URIs) deste servidor. O(s) nome(s) definido(s) nesta chave serão utilizado(s) na chave de URI (neste exemplo usaremos: TSSREST_URI) | Campo livre | Sim | |
| SslCertificate | Informar o path com o nome do arquivo do certificado digital, para utilização do REST com o protocolo HTTPS/SSL (caminho absoluto). | Campo livre | Não | |
| SslCertificateKey | Informar o path com o nome do arquivo com a chave do certificado digital, para utilização do REST com o protocolo HTTPS/SSL (caminho absoluto). | Campo livre | Não | |
| SslPassPhrase | Senha utilizada para autenticar o arquivo de certificado digital | Campo livre | Não | |
| ProtocolMin | Configuração de protocolo de segurança mínimo a ser aplicado na configuração do REST. | SSL/TLS, TLSv1.3, TLSv1.2, TLSv1.1, TLSv1 | Não | SSL/TLS |
| ProtocolMax | Configuração de protocolo de segurança máximo a ser aplicado na configuração do REST. | SSL/TLS, TLSv1.3, TLSv1.2, TLSv1.1, TLSv1 | Não | SSL/TLS |
Port=1322 URIs=TSSREST_URI Security=1 protocolMin=TLSv1.0 protocolMax=TLSv1.3 SslCertificate=C:\certificados\https_rest\cert_rest.crt SslCertificateKey=C:\certificados\https_rest\cert_rest.pem SslPassPhrase=123456 |
Através da URIs
Os nomes aqui preenchidos podem variar conforme desejado, neste caso vamos tratar como [TSSREST_SERVER] apenas para exemplo.
Abaixo serão detalhadas as chaves desta seção:
| Chave | Descrição | Valores Possíveis | Obrigatório | Valor padrão |
|---|---|---|---|---|
| URL | URN do site | Texto livre | Não | / |
| RootPath | Diretório onde estão armazenados os arquivos do site, pode ser informado como um path absoluto ou relativo ao diretório onde o servidor de aplicações executa | Texto livre | Não | ROOTPATH do TSS + '\http-root\tssrest\' |
| DefaultPage | Páginas iniciais que serão inicializadas no acesso a URL. Podem ser informadas várias páginas separados por espaço. Podem ser definidas mais de uma página default separados pode vírgula (,) | Texto livre | Não | index.html |
| Instances | Indica o controle de thread pool disponíveis para atender as requisições de APIs no TSS REST SERVER, em formato P1,P2,P3,P4. Onde: P1 = Indica a quantidade mínima de threads ativas no thread pool. Deve ser maior que zeros. P2 = Indica a quantidade máxima de threads ativas no thread pool. Deve ser maior ou igual que P1. P3 = Indica a quantidade mínima de threads prontas para execução no thread pool. Deve ser positivo e menor ou igual a P1. P4= O fator de crescimento, indica a quantidade de threads a serem alocadas. Deve ser maior que zero. | Mínimo, Máximo, Mínimo Livre, Fator Crescimento | Não | 1,4,1,1 |
| CORSEnable | Habilita utilização de controle de CORS | 0=Desabilitado ou 1=Habilitado | Não | 1 |
| AllowOrigin | Define lista de domínios permitidos para acessar as APIs do servidor REST. Exemplo: https://www.dominio.com.br/, https://10.172.0.84:1081/, http://localhost:1080/ | *=Para liberar todos os domínios ou texto livre com os domínios separados por virgula. | Não | * |
| AllowMethods | Define lista de métodos HTTP permitidos para acessar as APIs do servidor REST | GET,POST,PUT,DELETE,PATCH,OPTIONS,HEAD | Não | GET,POST,PUT,DELETE,PATCH,OPTIONS,HEAD |
| ExpirationTime | É o tempo em segundos que a thread aguarda uma nova requisição. Se expirado a thread retorna a aguardar uma requisição ou finalizara conforme análise dos controles da quantidade de threads. O valor deve se maior que zero se não for informado o sistema assume o valor padrão. | Não | 60 | |
| AcceptTimeOut | É o tempo em segundos que uma nova requisição aguarda para ser processada. Se expirado a requisição é descartada e o cliente sairá por timeout. O valor deve se maior que zero se não for informado o sistema assume o valor padrão. | Não | 10 |
[TSSREST_URI] URL=/rest/tss RootPath=C:\tss\http-root\httprest\httpuri\ DefaultPage=index.html Instances=1,10,2,1 CORSEnable=1 AllowOrigin=* AllowMethods=POST,GET,DELETE,UPDATE ExpirationTime=120 AcceptTimeOut=10 |
Esta seção define a configuração do JOB responsável por criar o(s) servidor(es) do TSS REST SERVER.
O nome desta seção pode variar conforme desejado, neste caso vamos seguir tratando como [JOBTSSREST] apenas para exemplo.
Abaixo serão detalhadas as chaves desta seção:
| Chave | Descrição | Valores Possíveis | Obrigatório | Valor padrão |
|---|---|---|---|---|
| main | Nome da função a ser executada. Neste caso deve ser preenchido sempre com: TSSREST_START | TSSREST_START | Sim | |
| environment | Nome do ambiente onde será executado o TSS REST SERVER. Normalmente o mesmo nome do ambiente configurado para o TSS. Exemplo: SPED | Texto livre | Sim |
[JOBTSSREST] main=TSSREST_START environment=SPED |
O JOBTSSREST deverá ser incluído junto dos demais jobs presentes na seção [ONSTART] e, uma vez que esteja presente, o job referente ao REST 2.0 do Framework poderá ser removido. |
Com o appserver.ini do TSS devidamente configurado, ao inicializar o serviço do TSS (appserver.exe), após mais ou menos 10 segundos da inicialização, serão impressos alguns logs no arquivo de console.log, informando o status da criação do(s) servidor(es) REST do TSS REST SERVER, conforme imagens a seguir:
Subida do TSS REST SERVER com sucesso:
Indicativo da(s) URL(s) do(s) TSS REST SERVER mapeado(s):
Cada URL poderá ser informado como endereço de URL em um browser/navegador, para verificação da disponibilidade do serviço REST do(s) servidor(es) do TSS REST SERVER:
