Linha Logix

Páginas filhas
  • LGX - LREST

Classe que permite executar um consumo CLIENT de serviços REST.

Para saber mais sobre REST e como configurar o TOTVSTEC como um servidor REST consulte a página REST ADVPL.

Hierarquia

Métodos GET

Métodos acessíveis através da função _ADVPL_get_property que permite recuperar e manipular os valores do componente: 


Método GET: HOST

Retorna o endereço base definido para as requisições REST.

Sintaxe


_ADVPL_get_property(< l_reference >,"GET", "HOST" ) => CHAR

Retorno


Tipo

Descrição

CHAREndereço base das requisições REST.

Exemplo


#------------------------#
 FUNCTION LREST_getHOST()
#------------------------#
    DEFINE l_host CHAR(200)

    LET l_host = _ADVPL_get_property(m_rest_reference,"HOST")
 END FUNCTION



Método GET: GET

Efetua uma requisição GET e retorna verdadeiro se a requisição foi efetuada com sucesso.

Sintaxe


_ADVPL_get_property(< l_reference >,"GET", < l_path >, [ l_headers ]) => SMALLINT

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_pathCHARCaminho do serviço REST para requisição.Sim
l_headersCHARLista de cabeçalhos específicos da requisição.1Não

1 Por ser uma lista de valores, os cabeçalhos precisam ser informados no formato {{"Header1: Content1"},{"Header2: Content2"}}.

   Exemplo: {{"Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}}.

Retorno


TipoDescrição
SMALLINTVerdadeiro se a requisição foi efetuada com sucesso.

Exemplo


#------------------------------------------------------------------------------#
FUNCTION LREST_getGET()
#------------------------------------------------------------------------------#
    DEFINE l_status SMALLINT

    LET l_status = _ADVPL_get_property(m_rest_reference,"GET","/posts")

    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
END FUNCTION

Observação

  • Para recuperar o resultado da requisição, utilize o método RESULT.
  • Para recuperar a mensagem de erro, no caso da requisição não ter sido executada, utilize o método ERROR_MESSAGE.



Método GET: POST

Efetua uma requisição POST e retorna verdadeiro se a requisição foi efetuada com sucesso.

Sintaxe


_ADVPL_get_property(< l_reference >,"POST", < l_path >, [ l_headers ], [ l_post_params ]) => SMALLINT

Parâmetros


Nome

Tipo

Descrição

Obrigatório?

Padrão

l_pathCHARCaminho do serviço REST para requisição.Sim
l_headersCHARLista de cabeçalhos específicos da requisição.1Não
l_post_paramsCHARConteúdo do corpo da requisição (geralmente conteúdo no formato JSON).Não

1 Por ser uma lista de valores, os cabeçalhos precisam ser informados no formato '{"Header1: Content1","Header2: Content2"}'.

   Exemplo: '{"Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}'.

Retorno


Tipo

Descrição

SMALLINTVerdadeiro se a requisição foi efetuada com sucesso.

Exemplo


#------------------------#
 FUNCTION LREST_getPOST()
#------------------------#
    DEFINE l_status SMALLINT
 
    LET l_status = _ADVPL_get_property(m_rest_reference,"POST","/posts","{}")
 
    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
 END FUNCTION

Observação

  • Para recuperar o resultado da requisição, utilize o método RESULT.
  • Para recuperar a mensagem de erro, no caso da requisição não ter sido executada, utilize o método ERROR_MESSAGE.



Método PUT

Efetua uma requisição PUT e retorna verdadeiro se a requisição foi efetuada com sucesso.

Sintaxe


_ADVPL_get_property(< l_reference >,"PUT", < l_path >, [ l_headers ]) => SMALLINT

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_pathCHARCaminho do serviço REST para requisição.Sim
l_headersCHARLista de cabeçalhos específicos da requisição.1Não

1 Por ser uma lista de valores, os cabeçalhos precisam ser informados no formato {{"Header1: Content1"},{"Header2: Content2"}}. Exemplo: {{"Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}}.

Retorno


TipoDescrição
SMALLINTVerdadeiro se a requisição foi efetuada com sucesso.

Exemplo


Exemplo SQLCODE
#------------------------------------------------------------------------------#
FUNCTION LREST_getPUT()
#------------------------------------------------------------------------------#
    DEFINE l_status SMALLINT

    LET l_status = _ADVPL_get_property(m_rest_reference,"PUT","/posts/1")

    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
END FUNCTION

Observação

  • Para recuperar o resultado da requisição, utilize o método RESULT.
  • Para recuperar a mensagem de erro, no caso da requisição não ter sido executada, utilize o método ERROR_MESSAGE.



Método GET: DELETE

Efetua uma requisição DELETE e retorna verdadeiro se a requisição foi efetuada com sucesso.

Sintaxe


_ADVPL_get_property(< l_reference >,"DELETE", < l_path >, [ l_headers ]) => SMALLINT

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_pathCHARCaminho do serviço REST para requisição.Sim
l_headersCHARLista de cabeçalhos específicos da requisição.1Não

1 Por ser uma lista de valores, os cabeçalhos precisam ser informados no formato {{"Header1: Content1"},{"Header2: Content2"}}.

   Exemplo: {{"Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="}}.

Retorno


TipoDescrição
SMALLINTVerdadeiro se a requisição foi efetuada com sucesso.

Exemplo


#------------------------------------------------------------------------------#
FUNCTION LREST_getDELETE()
#------------------------------------------------------------------------------#
    DEFINE l_status SMALLINT

    LET l_status = _ADVPL_get_property(m_rest_reference,"DELETE","/posts/1")

    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
END FUNCTION

Observação

  • Para recuperar o resultado da requisição, utilize o método RESULT.
  • Para recuperar a mensagem de erro, no caso da requisição não ter sido executada, utilize o método ERROR_MESSAGE.



Método GET: RESULT 

Retorna o resultado da requisição REST executada.

Sintaxe


_ADVPL_get_property(< l_reference >,"RESULT") => CHAR

Retorno


TipoDescrição
CHARResultado obtido na execução da requisição REST.

Exemplo


#--------------------------#
 FUNCTION LREST_getRESULT()
#--------------------------#
    DEFINE l_status SMALLINT

    LET l_status = _ADVPL_get_property(m_rest_reference,"GET","/posts")

    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
 END FUNCTION



Método GET: ERROR_MESSAGE 

Retorna a mensagem de erro resultante de uma requisição REST mal sucedida.

Sintaxe


_ADVPL_get_property(< l_reference >,"ERROR_MESSAGE") => CHAR

Retorno


TipoDescrição
CHARMensagem de erro detalhando a inconsistência ocorrida na requisição REST.

Exemplo


#--------------------------------#
 FUNCTION LREST_getERRORMESSAGE()
#--------------------------------#
    DEFINE l_status SMALLINT

    LET l_status = _ADVPL_get_property(m_rest_reference,"GET","/notfound")

    IF  l_status THEN
        CALL CONOUT("OK.:",_ADVPL_get_property(m_rest_reference,"RESULT"))
    ELSE
        CALL CONOUT("NOK:",_ADVPL_get_property(m_rest_reference,"ERROR_MESSAGE"))
    END IF
 END FUNCTION



Método GET: HEADER

Retorna a conteúdo de uma chave contida na seção HEADER do retorno de uma requisição REST executada.

OBS: Disponível a partir do Logix 12.1.2209 ou FIX Framework 12.1.2205(fix01)

Sintaxe


_ADVPL_get_property(< l_reference >,"HEADER", <l_key_name>) => CHAR

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_key_nameCHARNome de chave contida na seção HEADER retornada de uma requisição REST (GET / PUT / POST / DELETE).Sim

Retorno


TipoDescrição
CHARValor da chave indicada no parâmetro <l_key_name> contida no HEADER resultante de uma requisição REST.

Exemplo


#--------------------------------#
 FUNCTION LREST_getHEADER()
#--------------------------------#
    DEFINE l_value CHAR(100)

    #Após executar o método de requisição REST (POST PUT DELETE ou GET) recuperar o valor 
    #da chave "Content-Type" existente na HEADER do retorno da requisição
    LET l_value = _ADVPL_get_property(m_rest_reference,"HEADER","Content-Type")

    CALL conout("Valor da chave CONTENT-TYPE existente no HEADER do retorno da requisição REST = "||l_value)
 END FUNCTION





Método GET: STATUS

Retorna o valor do código do STATUS resultante do processamento de uma requisição REST (GET / PUT / POST / DELETE) .

OBS: Disponível a partir do Logix 12.1.2209 ou FIX Framework 12.1.2205(fix01)

Sintaxe


_ADVPL_get_property(< l_reference >,"STATUS") => CHAR

Retorno


TipoDescrição
CHAR

Valor do código de STATUS resultante de uma requisição REST.

OBS: Caso retorne NULL, indica que a conexão falhou, pois talvez o endereço seja inválido ou esteja indisponível, sendo um caso bem comum para a mensagem "Connection Refused".

Exemplo


#--------------------------------#
 FUNCTION LREST_getSTATUS()
#--------------------------------#
    DEFINE l_value CHAR(10)

    #O status de execução retornado pelos métodos GET POST PUT DELETE do componente LREST contém valor TRUE ou FALSE apenas para indicar o 
    #resultado da operação foi realizado com sucesso, mas não retorna o codigo de STATUS da requisição HTTP REST (Exemplo: 200 que indica SUCESSO)
    #Neste caso para uma requisição que seja executada com sucesso irá retornar o valor do código de STATUS HTTP REST, ou seja, 200, 404, 201, etc.
    LET l_value = _ADVPL_get_property(m_rest_reference,"STATUS")

    CALL conout("STATUS requisição HTTP REST = "||l_value)
 END FUNCTION




Método GET: TIMEOUT

Retorna o valor do TIMEOUT atual (em segundos) utilizado no processamento de uma requisição REST (GET / PUT / POST / DELETE) .

OBS: Disponível a partir do Logix 12.1.2301 ou FIX Framework 12.1.2209(fix01)

Sintaxe


_ADVPL_get_property(< l_reference >,"TIMEOUT") => INTEGER

Retorno


TipoDescrição
INTEGERValor atual de tempo (em segundos) definido como TIMEOUT para uma requisição REST.

Exemplo


#--------------------------------#
 FUNCTION LREST_getTIMEOUT()
#--------------------------------#
    DEFINE l_value INTEGER

    LET l_value = _ADVPL_get_property(m_rest_reference,"TIMEOUT")

    CALL conout("TIMEOUT requisição HTTP REST = "||l_value)
 END FUNCTION

Observações

O tempo de TIMEOUT padrão adotado pelo componente LRest será o tempo configurado na chave de ambiente TIMEOUT configurada na seção [HTTPV11] no arquivo INI de configurações do AppServer, no entanto, caso esta chave não tenha sido configurada, o tempo padrão adotado será 120 segundos.






Métodos SET

Métodos acessíveis através da função _ADVPL_set_property que permite alterar e manipular os valores do componente.


Método SET: HOST

Define o endereço base para as requisições REST.

Sintaxe


CALL _ADVPL_set_property(< l_reference >,"HOST", < l_host >)

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_hostCHAREndereço base das requisições REST.Sim

Exemplo


#------------------------#
 FUNCTION LREST_setHOST()
#------------------------#
    CALL _ADVPL_set_property(m_rest_reference,"HOST","http://www.totvs.com.br")
 END FUNCTION



Método SET: TIMEOUT

Ajusta o valor do TIMEOUT atual (em segundos) que será utilizado no processamento de uma requisição REST (GET / PUT / POST / DELETE) .

OBS: Disponível a partir do Logix 12.1.2301 ou FIX Framework 12.1.2209(fix01)

Sintaxe


_ADVPL_set_property(< l_reference >,"TIMEOUT", < l_value >)

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_valueINTEGERQuantidade de tempo, em segundos, a ser utilizado como novo valor de TIMEOUT para o processamento de requisição REST.Sim

Exemplo


#--------------------------------#
 FUNCTION LREST_setTIMEOUT()
#--------------------------------#      
    DEFINE l_rest_reference VARCHAR(10)
	
    # Cria o componente para requisições REST.
    LET l_rest_reference = _ADVPL_create_component(NULL,"LREST")     
 
    # Ajusta o TIMEOUT do componente REST para 30 segundos
    CALL _ADVPL_set_property(l_rest_reference,"TIMEOUT",30)
 END FUNCTION




Método SET: ADD_HEADER

Adiciona uma chave na definição do cabeçalho (HEADER) de uma requisição REST a ser processada.

OBS: Disponível a partir do Logix 12.1.2309 ou FIX Framework 12.1.2305(fix01)

Sintaxe


_ADVPL_set_property(< l_reference >,"ADD_HEADER", < l_key >, [< l_value >] )

Parâmetros


NomeTipoDescriçãoObrigatório?Padrão
l_keyCHAR

Nome da chave a ser adicionada no HEADER da requisiçao REST a ser processada.

A chave poderá ser enviada de 2 formas distintas:

     chave  (apenas o nome da chave, sendo o valor enviado no 2o parâmetro)
     Exemplo:   "Content-Type"

OU 
     chave: valor
     Exemplo:   "Content-Type: application/json"
     Neste caso não é preciso informar o valor no 2° parâmetro.

Sim
l_valueCHAR

Valor  da chave dicionada no HEADER da requisiçao REST a ser processada.

     Exemplo:   "application/json"
     Este valor só deve ser informado quando no 1° parâmetro o valor não foi informado juntamente com o nome da chave.		Não

Exemplo


#--------------------------------#
 FUNCTION LREST_setADD_HEADER()
#--------------------------------#      
    DEFINE l_rest_reference VARCHAR(10)
	
    # Cria o componente para requisições REST.
    LET l_rest_reference = _ADVPL_create_component(NULL,"LREST")     
 
    # Adiciona a chave "Content-Type" ao HEADER da requisição REST 
    CALL _ADVPL_set_property(l_rest_reference,"ADD_HEADER","Content-Type","application/json")
  END FUNCTION




Sintaxe

Sintaxe geral para criar um componente LREST.

LET m_rest_reference = _ADVPL_create_component(NULL,"LREST")

Exemplo

#------------------------------------------------------------------------------#
 FUNCTION LREST_teste()
#------------------------------------------------------------------------------#
    DEFINE l_rest_reference VARCHAR(10)

    DEFINE l_status  SMALLINT
    DEFINE l_message CHAR(200)

    # Cria o componente para requisições REST.
    LET l_rest_reference = _ADVPL_create_component(NULL,"LREST")

    # Define o endereço base das requisições.
    CALL _ADVPL_set_property(l_rest_reference,"HOST","http://jsonplaceholder.typicode.com")

    # Adiciona a chave "Content-Type" ao HEADER da requisição REST (usando o parâmetro 1 para o nome da chave e o parâmetro 2 para o valor da chave
    CALL _ADVPL_set_property(l_rest_reference,"ADD_HEADER","Content-Type","application/json")
  
    # Adiciona a chave "Authorization" ao HEADER da requisição REST 
    # (usando o parâmetro 1 para o nome e valor da chave juntos, separando por ":" que é o padrão do formato de chave/valor para HEADER de requisição REST)
    CALL _ADVPL_set_property(l_rest_reference,"ADD_HEADER","Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")

    #Processando a requisição REST usando o método GET para o PARAM (endpoint) "/notfound"
    LET l_status = _ADVPL_get_property(l_rest_reference,"GET","/notfound")

    #O retorno será TRUE, quando o status da requisição GET acima for igual a 200 (OK)
    IF  l_status THEN
        LET l_message = "GET (ERRO):"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"RESULT")

        CALL log0030_mensagem(l_message,"info")
    ELSE
        LET l_message = "GET (ERRO):"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"ERROR_MESSAGE")

        CALL log0030_mensagem(l_message,"stop")
    END IF

    # Método GET.
    LET l_status = _ADVPL_get_property(l_rest_reference,"GET","/posts")

    IF  l_status THEN
        LET l_message = "GET:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"RESULT")

        CALL log0030_mensagem(l_message,"info")
    ELSE
        LET l_message = "GET:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"ERROR_MESSAGE")

        CALL log0030_mensagem(l_message,"stop")
    END IF

    # Método POST.
    LET l_status = _ADVPL_get_property(l_rest_reference,"POST","/posts")

    IF  l_status THEN
        LET l_message = "POST:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"RESULT")

        CALL log0030_mensagem(l_message,"info")
    ELSE
        LET l_message = "POST:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"ERROR_MESSAGE")

        CALL log0030_mensagem(l_message,"stop")
    END IF

    # Método PUT.
    LET l_status = _ADVPL_get_property(l_rest_reference,"PUT","/posts/1")

    IF  l_status THEN
        LET l_message = "PUT:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"RESULT")

        CALL log0030_mensagem(l_message,"info")
    ELSE
        LET l_message = "PUT:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"ERROR_MESSAGE")

        CALL log0030_mensagem(l_message,"stop")
    END IF

    # Método DELETE.
    LET l_status = _ADVPL_get_property(l_rest_reference,"DELETE","/posts/1")

    IF  l_status THEN
        LET l_message = "DELETE:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"RESULT")

        CALL log0030_mensagem(l_message,"info")
    ELSE
        LET l_message = "DELETE:"
        LET l_message = l_message CLIPPED, _ADVPL_get_property(l_rest_reference,"ERROR_MESSAGE")

        CALL log0030_mensagem(l_message,"stop")
    END IF

    # Ao finalizar o uso, libera o componente da memória.
    CALL _ADVPL_destroy_component(l_rest_reference)
 END FUNCTION


Abrangência

Componente disponível a partir do LOGIX 12.1.13.