TOTVSTEC

Árvore de páginas

Atenção!

Recurso disponível somente em: APPSERVER 24.3.0.1 + TLPPCORE 01.05.00


Através da função de callback onBlock, o usuário/desenvolvedor pode definir quais serviços REST (endpoints + método) serão bloqueados para uso ou somente ocultados na listagem de serviços disponíveis.

Esse recurso é útil quando queremos manter disponíveis somente alguns serviços REST para determinado ambiente.

Informações Importantes

  • A função informada em onBlock será executada somente na subida do REST, antes da criação do mapa de serviços que serão disponibilizados no serviço.

  • A chave OnBlock só será lida quando informada na Thread Pool, pois ela está diretamente relacionada ao servidor REST. Portanto, caso seja configurado OnBlock nas sessões destinadas aos Slaves, estas serão ignoradas e não terão uso algum para o ambiente REST.

Atenção!

As duas funções de callback, OnAllow e OnBlock, possuem a mesma finalidade de indicar à aplicação (AppServer) quais APIs REST estarão disponíveis para uso em determinado ambiente.

A diferença entre eles é que em OnAllow é indicado as APIs que serão permitidas o uso e portanto as demais APIs serão automaticamente bloqueadas. Porém em OnBlock é indicado as APIs que serão bloqueadas e portanto as demais permanecerão permitidas para uso.

Devido à isso, não podemos utilizar as duas funções simultaneamente e por essa razão a aplicação dará prioridade para OnAllow caso ambas estejam ativadas, ignorando OnBlock nesse caso.

Portanto, para utilizar OnBlock, certifique-se que OnAllow não esteja ativado.

Parâmetro Recebido

A função customizada recebe somente 1 (um) parâmetro, sendo:

1 - oList

Classe contendo valores da execução e métodos para informar que determinado endpoint + método deve ser bloqueado ou oculto.

Métodos Sets

oList:block( cEndpoint as character, cMethod as character )

Responsável por adicionar um Endpoint e Método que será bloqueado no ambiente REST.

Ex:

Sintaxe
oList:block( cEndpoint, cMethod )

oList:hide( cEndpoint as character, cMethod as character )

Responsável por adicionar um Endpoint e Método que será somente ocultado no ambiente REST, ou seja, ele não aparece em nenhuma listagem de serviços disponíveis, porém, quem conhecer a sua assinatura poderá acessá-lo.

Ex:

Sintaxe
oList:hide( cEndpoint, cMethod )

Métodos Gets

oList:getServiceName()

Retorna o nome do serviço REST o qual foi configurado o onBlock.

[HTTPSERVER]
Servers=SERVIDOR_REST_01

oList:getServicePort()

Retorna a porta do serviço REST o qual foi configurado o onBlock.

[HTTPSERVER]
Servers=SERVIDOR_REST_01
 
[HTTP_DBMONITOR]
port=8080

oList:getThreadPoolName()

Retorna o nome do Thread Pool do serviço REST o qual foi configurado o onBlock.

[HTTPSERVER]
Servers=SERVIDOR_REST_01
 
[SERVIDOR_REST_01]
port=8080
locations=LOC_SRV_01

[LOC_SRV_01]
ThreadPool=THREAD_POOL_SRV_01

oList:getUserData()

Retorna o JSON informado em UserData do serviço REST o qual foi configurado o onBlock.

[HTTPSERVER]
Servers=SERVIDOR_REST_01
 
[HTTP_DBMONITOR]
userData={"sua_chave":"seu_valor"}

Retorna um Json contendo os endpoints que foram encontrados para serem disponibilizados neste ambiente. A lista contém endpoints criados via annotation e via inicialização dinâmica do server através de LoadURNs.

O recebimento dessa lista é opcional pois pode degradar a performance da subida da aplicação (AppServer), portanto o comportamento padrão é o não recebimento da lista de APIs.

Para ativar o recebimento, informe através da configuração do REST na chave TlppData, conforme abaixo:

  • INI
TlppData={"OnBlockGetApiList":true}
  • Inicialização Dinâmica
jTP_TlppData := {"OnBlockGetApiList":true}
jREST['ThreadPool']['TlppData'] := jTP_TlppData


JSON enviado ao callback

JSON retornado quando não requisitada a lista
{
    "required": false,
    "success": false,
    "annotation": [],
    "json": []
}
JSON contando APIs
{
    "required": true,
    "success": true,
    "annotation": [
        { "/exemplo1/annotation": ["GET","POST","PUT"] },
        { "/exemplo2/annotation": ["GET"] }
    ],
    "json": [
        { "/exemplo1/loadurn": ["GET"] }
    ]
}

Retorno

Sugerimos que o retorno seja NULL pois todo e qualquer retorno será ignorado.

Exemplo

function U_onBlock( oList )

  local cEndpoint as character
  local cServiceName as character
  local nServicePort as numeric
  local cThreadPoolName as character
  local cUserData as character
  local jApis as json

  // Use os valores abaixo conforme sua necessidade de implementação
  // Embora você sempre receberá tais valores, seu uso é opcional.
  
  cServiceName    := oList:getServiceName()
  nServicePort    := oList:getServicePort()
  cThreadPoolName := oList:getThreadPoolName()
  cUserData       := oList:getUserData()
  jApis           := oList:getApiList() 


  // Para bloquear ou ocultar algum serviço, utilize os métodos Sets

  cEndpoint := '/exemplo1/urn'
    oList:block( cEndpoint, 'get'  )
    oList:block( cEndpoint, 'post' )
    oList:hide(  cEndpoint, 'put'  )

  cEndpoint := '/exemplo2/urn'
    oList:block( cEndpoint, 'get' )

return

Conclusão

É muito simples bloquear/ocultar um serviço REST, basta utilizar um dos métodos mencionados acima indicando a ação (block | hide), o endpoint e seu método.

Note que sempre é preciso informar o endpoint e método para cada ação; sendo assim, poderemos bloquear todos os métodos de um mesmo endpoint ou somente alguns, conforme necessidade.


Importante!

Devido à criticidade de disponibilizar dados indesejados, caso ocorra alguma "exception" na criação da lista, o AppServer não será iniciado.

Porém, se essa criticidade não for a sua realidade e ainda assim queira que o AppServer seja iniciado, mesmo que disponibilizando todos os serviços REST, é possível configurar o REST indicando que o OnBlock seja executado em modo "Soft", conforme abaixo:

[HTTPSERVER]
Servers=SERVIDOR_REST_01
 
[SERVIDOR_REST_01]
port=8080
locations=LOC_SRV_01

[LOC_SRV_01]
ThreadPool=THREAD_POOL_SRV_01

[THREAD_POOL_SRV_01]
TlppData={"OnBlockSoft":false}
  • Sem rótulos