Páginas filhas
  • LGX - LREST

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Pagetitle
LGX - LREST
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: 


Expandir
titleHOST

Método GET: HOST

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

Sintaxe



Bloco de código
_ADVPL_get_property(< l_reference >,"GET", "HOST" ) => CHAR

Retorno



Tipo

Descrição

CHAREndereço base das requisições REST.

Exemplo



Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------#
 FUNCTION LREST_getHOST()
#------------------------#
    DEFINE l_host CHAR(200)

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




Expandir
titleGET

Método GET: GET

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

Sintaxe



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------------------------------------------------------------#
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.




Expandir
titlePOST

Método GET: POST

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

Sintaxe



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------#
 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.




Expandir
titlePUT

Método PUT

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

Sintaxe



Bloco de código
_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



Bloco de código
titleExemplo SQLCODE
linenumberstrue
#------------------------------------------------------------------------------#
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.




Expandir
titleDELETE

Método GET: DELETE

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

Sintaxe



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------------------------------------------------------------#
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.




Expandir
titleRESULT

Método GET: RESULT 
Âncora
getResult
getResult

Retorna o resultado da requisição REST executada.

Sintaxe



Bloco de código
_ADVPL_get_property(< l_reference >,"RESULT") => CHAR

Retorno



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

Exemplo



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------#
 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




Expandir
titleERROR_MESSAGE

Método GET: ERROR_MESSAGE 
Âncora
getErrorMessage
getErrorMessage

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

Sintaxe



Bloco de código
_ADVPL_get_property(< l_reference >,"ERROR_MESSAGE") => CHAR

Retorno



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

Exemplo



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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étodos acessíveis através da função _ADVPL_set_property que permite alterar e manipular os valores do componente.




Expandir
title

...

HEADER

Método

...

GET:

...

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

Sintaxe

...

 HEADER
Âncora
getHeader
getHeader

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



Bloco de código
_ADVPL_get_property(< l_reference >,"

...

HEADER", 

...

<l_key_name>) => CHAR

Parâmetros



NomeTipoDescriçãoObrigatório?Padrão
l_

...

key_nameCHAR

...

Nome 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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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






Expandir
titleSTATUS

Método GET: STATUS
Âncora
getStatus
getStatus

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



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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





Expandir
titleTIMEOUT

Método GET: TIMEOUT
Âncora
getTimeout
getTimeout

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



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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.


Expandir
titleHOST

Método SET: HOST

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

Sintaxe



Bloco de código
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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------#
 FUNCTION LREST_setHOST()
#------------------------#
    CALL _ADVPL_set_property(m_rest_reference,"HOST","http://www.totvs.com.br")
 END FUNCTION




Expandir
titleTIMEOUT

Método SET: TIMEOUT
Âncora
setTimeout
setTimeout

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



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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





Expandir
titleADD_HEADER

Método SET: ADD_HEADER
Âncora
setAddHeader
setAddHeader

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



Bloco de código
_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



Bloco de código
languageruby
themeConfluence
linenumberstrue
#--------------------------------#
 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.

Bloco de código
LET m_rest_reference = _ADVPL_create_component(NULL,"LREST")

Exemplo


Bloco de código
languageruby
themeConfluence
linenumberstrue
#------------------------------------------------------------------------------#
 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)
   

Sintaxe

Bloco de código
LET m_rest_reference = _ADVPL_create_component(NULL,"LREST")

Exemplo

...

languageruby
themeConfluence
linenumberstrue

...

 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.