Âncora | ||||
---|---|---|---|---|
|
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 oficialmente disponibilizada e sustentada apenas 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.
Aviso | ||
---|---|---|
| ||
As configurações detalhadas aqui são de uso exclusivo no produto TSS e em releases iguais ou superiores à 12.1.2410. |
Âncora | ||||
---|---|---|---|---|
|
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
Informações | ||
---|---|---|
| ||
Atenção à porta a ser utilizada, não poderá conflitar com nenhuma outra porta usado no mesmo appserver.ini. 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. |
Âncora | ||||
---|---|---|---|---|
|
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.
Âncora | ||||
---|---|---|---|---|
|
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 |
Bloco de código | ||||
---|---|---|---|---|
| ||||
[TSSREST_CONFIG] Enable=1 Servers=TSSREST_SERVER Charset=UTF-8 Log=1 |
Âncora | ||||
---|---|---|---|---|
|
Define as configurações de cada servidor HTTP e/ou HTTPS informados na chave {SERVERS} na seção TSSREST_CONFIG.
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 | |
SslprotocolMin | 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 |
SslprotocolMax | 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 |
Bloco de código | ||||
---|---|---|---|---|
| ||||
[TSSREST_SERVER] Port=1322 URIs=TSSREST_URI Security=1 SslprotocolMin=TLSv1.0 SslprotocolMax=TLSv1.3 SslCertificate=C:\certificados\https_rest\cert_rest.crt SslCertificateKey=C:\certificados\https_rest\cert_rest.pem SslPassPhrase=123456 |
Âncora | ||||
---|---|---|---|---|
|
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 |
AllowOrigins | 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 |
Bloco de código | ||||
---|---|---|---|---|
| ||||
[TSSREST_URI] URL=/rest/tss RootPath=C:\tss\http-root\httprest\httpuri\ DefaultPage=index.html Instances=1,10,2,1 CORSEnable=1 AllowOrigins=* 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 a ser incluido na seção ONSTART.
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 |
Bloco de código | ||||
---|---|---|---|---|
| ||||
[JOBTSSREST] main=TSSREST_START environment=SPED |
Âncora | ||||
---|---|---|---|---|
|
Nesta seção deverão ser incluídos os jobs padrão do TSS que irão ser executados, e adicionalmente o job JOBTSSREST de criação e subida do(s) servidor(es) REST do TSS REST SERVER.
Ficando assim a configuração:
Bloco de código | ||||
---|---|---|---|---|
| ||||
[ONSTART] JOBS=JOBTSSREST REFRESHRATE=10 |
Informações |
---|
Para incluir mais de um job no ONSTART basta informar as seções separadas por virgula. Exemplo: [ONSTART] |
Âncora | ||||
---|---|---|---|---|
|
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:
Âncora | ||||
---|---|---|---|---|
|