Páginas filhas
  • FWRest


Classe: FWRest


Descrição
Classe Client de REST


New

Sintaxe
FWREST():New(<cHost >)-> NIL

Descrição
Construtor

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
cHostCaracteresEndereço do Host que iremos fazer o consumo do REST
X

SetPath

Sintaxe
FWREST():SetPath(<cPath >)-> NIL

Descrição
Informa o path aonde será feito a requisição

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
cPathCaracteresPath do caminho da requisição
X

Get

Sintaxe
FWREST():Get(<aHeadStr >, <cGetParam>)-> lOK

Descrição
Efetua o Comando Get, no Host e Path informados anteriormente.
Utilize o método getResult para pegar o resultado
Ou o método GetLastError para verificar o erro.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
aHeadStrArrayArray com parâmetros do head
X
cGetParamCaracteresIndica a lista de strings de parâmetros que serão enviadas ao servidor HTTP, através da URI""


Retorno
lOK Retorna .T. se o Get retornar o HTTP code 200.


Atenção

Na passagem do parâmetro cGetParam, deve-se ficar atento ao formato da string que será passada como parâmetro, pois a mesma segue o formato URI - Uniform Resource Identifiers: Query Component. Para tanto, utilize no valor do parâmetro a função Escape.

GetResult

Sintaxe
FWREST():GetResult()-> cResult

Descrição
Retorna o ultimo conteúdo valido retornado pela uma chamada ao método Get ou Post

Retorno
cResult Resultado da Operação

GetLastError

Sintaxe
FWREST():GetLastError()-> cErro

Descrição
Retorna o ultimo erro retornado pela uma chamada ao método Get ou Post

Retorno
cErro Erro da Operação 

Post

Sintaxe
FWREST():Post(<aHeadStr >)-> lOK

Descrição
Efetua o Comando POST, no Host e Path informados anteriormente.
Utilize o método getResult para pegar o resultado
Ou o método GetLastError para verificar o erro.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
aHeadStrArrayArray com parâmetros do head
X


Retorno
lOK Retorna .T. se conseguir fazer a conexão.

SetPostParams

Sintaxe
FWREST():SetPostParams(<cParams >)-> NIL

Descrição
Seta a string de parâmetro do Post

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
cParamsCaracteresParâmetros do Post
X

Put

Sintaxe
FWREST():Put(<aHeadStr >, <cPayLoad>, <cGETParms>)-> lOK

Descrição
Efetua o Comando Put, no Host e Path informados anteriormente.
Utilize o método getResult para pegar o resultado
Ou o método GetLastError para verificar o erro.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
aHeadStrArrayArray com parâmetros do head
X
cPayLoadCaractereCorresponde à StringList de parâmetros a serem enviados ao servidor HTTP""

cGETParmsCaractereCorresponde ao endereço HTTP, juntamente com a pasta e o documento solicitados ( lib 20230403 ou superior)""


Retorno
lOK Retorna .T. se o Get retornar o HTTP code 200 ou 201.

Delete

Sintaxe
FWREST():Delete(<aHeadStr >, <cPayLoad>, <cGETParms>)-> lOK

Descrição
Efetua o Comando DELETE, no Host e Path informados anteriormente.
Utilize o método getResult para pegar o resultado
Ou o método GetLastError para verificar o erro.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
aHeadStrArrayArray com parâmetros do head
X
cPayLoadCaractereCorresponde à StringList de parâmetros a serem enviados ao servidor HTTP""

cGETParmsCaractereCorresponde ao endereço HTTP, juntamente com a pasta e o documento solicitados ( lib 20230403 ou superior)""


Retorno
lOK Retorna .T. se o Get retornar o HTTP code 200 ou 201.



SetChkStatus

Sintaxe
FWRest():SetChkStatus(lChk)-> Nil

Descrição
Seta a variável de controle de checagem do HTTP Code, onde se informado falso, apenas retornamos o lOk como true para indicar que realizamos a conexão, ficando a critério do responsável validar o HTTP Code retornado pela requisição.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
lChkLógicoVariável de decisão sobre quem irá checar o retorno do HTTP Code.T.


Retorno
Nil

Método disponível a partir da Release 23 do Protheus 12.

GetChkStatus

Sintaxe
FWRest():GetChkStatus()->lChk

Descrição
Retorna o conteúdo do parâmetro lChkStatusCode que será utilizado nos métodos Get, Post, Put e Delete onde é feito a decisão de quem irá tratar o HTTP Code.

Retorno
lChkStatusCode - Variável de decisão de quem trata a checagem de HTTP Code

Método disponível a partir da Release 23 do Protheus 12.

GetHTTPCode

Sintaxe
FWRest():GetHTTPCode()

Descrição
Método que retorna o HTTPCode da requisição.

Retorno
cResult – Retorno HTTP Code da requisição

Método disponível a partir da Release 23 do Protheus 12.



SetGetParams

Sintaxe
FWRest():SetGetParams(cGetParams)

Descrição
Efetua o set de uma string de parâmetros, do tipo GET, que serão enviados ao servidor HTTP através da URI.

Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
cGetParamsCharactereString contendo o valor do parâmetro GET, utilizado na URI
X

Método disponível a partir da LIB 20201009

SetLegacySuccess

Sintaxe
FWREST():SetLegacySuccess(<lActive>)-> Logical

Descrição
Metodo de compatibilidade para range extendido do Status Code, quando desabilitado passa a ser considerado o range completo de códigos de sucesso (200 a 299).

Ex.: 

  • ::SetLegacySuccess(.F.) ) → o verbo utilizado retornará .T. se retornado Status Code de 200 a 299
  • ::SetLegacySuccess(.T.) ) → o verbo utilizado retornará .T. se retornado Status Code de 200 a 201


Parâmetros

NomeTipoDescriçãoDefaultObrigatórioReferência
lActiveLogicalIndica se mantem o comportamento legado (Status code 200 e 201).T.X.T. - 200 à 201
.F. - 200 à 299

Importante

Método disponível a partir da lib 20240812.





Exemplo:

user function tstFwRestTest()
local oRestClient as object

oRestClient := FWRest():New("http://code.google.com")
oRestClient:setPath("/p/json-path/")

if oRestClient:Get()
   ConOut(oRestClient:GetResult())
else
   ConOut(oRestClient:GetLastError())
endif

return


Exemplo de envio de arquivo .gz:

#include "protheus.ch"

//-------------------------------------------------------------------
/*/{Protheus.doc} x16165
Função para post na API /api/batch/contratos em
https://seusite.com.br, utilizando da classe
@sample U_x16165()
@author Daniel Mendes
@since 22/03/2019
@version 1.0
/*/
//-------------------------------------------------------------------
user function x16165()
local oRestClient as object
local cUrl as char
local cPath as char
local aHeadOut as array
local oFile as object

cUrl := "https://seusite.com.br"
cPath := "/api/batch/contratos"
aHeadOut := {}

Aadd(aHeadOut, "Authorization: Basic " + Encode64("app01:fTdUlDgdQQ4MRQhLahykiKhON6k97Zfly5SV6fwpa5zCE"))
Aadd(aHeadOut, "Content-Type: application/json")
Aadd(aHeadOut, "Content-Encoding: gzip")

oFile := FwFileReader():New("\contratos_20190316.gz")

if oFile:Open()
	oRestClient := FWRest():New(cUrl)

	oRestClient:SetPath(cPath)
	oRestClient:SetPostParams(Encode64(oFile:FullRead()))

	oFile:Close()

	if oRestClient:Post(aHeadOut)
		showResult(oRestClient:GetResult())
	else
		showResult(oRestClient:GetLastError())
	endif

	FreeObj(oRestClient)
endif

FreeObj(oFile)

return

//-------------------------------------------------------------------
/*/{Protheus.doc} showResult
Exibe o resultado do método POST, sendo em console ou tela

@param cValue String contendo o conteúdo que será exibido

@sample showResult("Teste")
@author Daniel Mendes
@since 22/03/2019
@version 1.0
/*/
//-------------------------------------------------------------------
static function showResult(cValue)
if IsBlind()
	Conout(cValue)
else
	MsgInfo(cValue)
endif
return


  • Sem rótulos

22 Comentários

  1. Usuário desconhecido (rubens.santos)

    Poderiam incluir um exemplo do método SetPostParams? Gostaria de saber qual o formato deve ser enviado para o método.

    1. Rubens, isso depende do servidor REST que você está consumindo. Geralmente você deve passar um JSON nesse parâmetro, por exemplo:

      cJSON := '{"parameter1":"value", "parameter2":"value"}'

      oRest:SetPostParams(cJSON)

  2. Bom dia, 

    Gostaria de saber se existe o method patch na classe FWREST ?

    1. Bom dia.

       

      Não é possível. O FWRest tem suporte apenas para os verbos: POST, GET, PUT e DELETE

  3. Existe alguma forma de ligar um TRACE para ser emitido no console?

    1. Bom dia.

      Para habilitar o trace inclua a chave FWTraceLog=1 na configuração do seu environment.

      Att.

  4. Bom dia.

    Para documentar, o método PUT tem um segundo parâmetro para setar a string JSon do Put.

    Exemplo: oRestClient:Put(aHeadStr, cJson)



     

  5. Prezados, existe algum comando em especial no FWREST para trabalhar com sites que exijam certificado(ssl - https)?

    1. Bom dia.

      O FWRest já encapsula o SSL, basta configura-lo no seu appserver.ini, internamente já será usando seu certificado.

      Att.

  6. Prezados,

    Observem o bloco de código abaixo:

    Consumo via FwRest()
    1. Local oRestClient := FWRest():New("http://localhost:7045")
    2. Local aHeader := {}
    3. aadd(aHeader,'Authorization:  BASIC Zmx1aWdjbG91ZDoxMjNAY2xvdWQ=')
    4. oRestClient:setPath("/sample/?startIndex=1&count=2")
    5. If oRestClient:Get(aHeader)


    Ao debugar o método Get [ WSMETHOD GET WSRECEIVE startIndex, count WSSERVICE sample ],

    Como obter o conteúdo do aHeader, informado na linha 5?

    Não o encontrei no Self, PathParam/EndPoint, QueryString e GetContent().

    Onde esse cara fica?

    Obrigado.


    1. Denison, tenta usar a função HTTPHeader("Authorization"), onde "Authorization" é a propriedade que deseja pegar o valor.

      1. Obrigado pelo esclarecimento da minha dúvida, Marllon! Abraços!

  7. Estou com problema quando o cliente retorna status 40X (401, 402, 403 e etc)

    O objeto da função retorna como erro interno e não retorna o corpo onde o cliente define a mensagem de erro:

    Exemplo: Status 401 Unathorized - 

    { "status" : 401, "Produto ja cadastrado!"}

    Eu preciso deste corpo para documentar a mensagem mas o objeto só retorna: Unathorized

    Varinfo do objeto:

    FWRest: varinfo(oRestClient): oRestClient -> OBJECT ( 8) [...]
    oRestClient:ACABECRET -> ARRAY ( 0) [...]
    oRestClient:CHOST -> C ( 26) [http://localhost:9100/rest]
    oRestClient:CINTERNALERROR -> C ( 14) [Unauthorized
    ]
    oRestClient:CPATH -> C ( 63) [/produtos/cadastrar?deposit=0000000001&token=axyzw0d32rtdaqutgf]
    oRestClient:CPOSTPARAMS -> C ( 0) []
    oRestClient:CRESULT -> U ( 1) [ ]
    oRestClient:NTIMEOUT -> N ( 15) [ 120.0000]
    oRestClient:ORESPONSEH -> OBJECT ( 4) [...]
    oRestClient:ORESPONSEH:AHEADERFIELDS -> ARRAY ( 0) [...]
    oRestClient:ORESPONSEH:CREASON -> U ( 1) [ ]
    oRestClient:ORESPONSEH:CSTATUSCODE -> U ( 1) [ ]
    oRestClient:ORESPONSEH:CVERSION -> U ( 1) [ ]


  8. Boa noite,
    Como faço a montagem da requisição REST que utiliza o protocolo de autenticação OAuth 2.0
    Poderia me enviar um exemplo.

    Att,

    1. Leonardo,

       

      Não precisei fazer ainda mas pelo que li no artigo abaixo, é uma sequência de chamadas para poder obter permissão de acesso as chamadas das APIs.

       

      Segue artigo:

      https://imasters.com.br/desenvolvimento/como-funciona-o-protocolo-oauth-2-0

       

      Substitui o FWREST() pela chamada do HTTPQUOTE, verifique no TDN:

       

      http://tdn.totvs.com/display/tec/HTTPQuote

       

      aadd(aHead, 'Content-Type: application/json')

      cRetorno := HTTPQuote( cURL, cMetodo, cGETParms, cJSon /*cPOSTParms*/, nTimeOut, aHead, @cHeaderRet )

       

      If  Empty( cRetorno )

      cRetorno := '{ "status" : ' + CValToChar(HttpGetStatus(@cDesc)) + ', "erro" : "' + cDesc + '" }'

      EndIf

  9. Bom dia,

    Estou requisitando um serviço, onde o 

    Content-Type: application/xml;charset=UTF-8 e não retorna o xml no GetResult() preciso de enviar mais algum parâmetro?

    RAW:

    HTTP/1.1 200 OK
    Date: Sun, 23 Dec 2018 03:18:24 GMT
    Content-Type: application/xml;charset=UTF-8
    Transfer-Encoding: chunked
    Connection: keep-alive
    Server: nginx/1.12.2
    X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS
    Access-Control-Allow-Headers: auth-token, api-token
    Set-Cookie: JSESSIONID=0B0E411769FAC545F64B0E865392C302; Path=/CenterWebApi

    <result>
    <resourceName>item</resourceName>
    <size>16</size>
    <entries>
    <entry id="53921915" link="/item/53921915.xml"/>
    <entry id="53921914" link="/item/53921914.xml"/>
    <entry id="53921911" link="/item/53921911.xml"/>
    <entry id="53921922" link="/item/53921922.xml"/>
    <entry id="53921923" link="/item/53921923.xml"/>
    <entry id="53921907" link="/item/53921907.xml"/>
    <entry id="53921909" link="/item/53921909.xml"/>
    <entry id="53921908" link="/item/53921908.xml"/>
    <entry id="53921910" link="/item/53921910.xml"/>
    <entry id="53921912" link="/item/53921912.xml"/>
    <entry id="53921913" link="/item/53921913.xml"/>
    <entry id="53921917" link="/item/53921917.xml"/>
    <entry id="53921918" link="/item/53921918.xml"/>
    <entry id="53921919" link="/item/53921919.xml"/>
    <entry id="53921920" link="/item/53921920.xml"/>
    <entry id="53921921" link="/item/53921921.xml"/>
    </entries>
    </result>

    Requisição:

    Local oRestClient := FWRest():New("http://center.umov.me/CenterWeb/api/"+cKeyApi+"/"+"item.xml")

    XML:

    <result>
    <resourceName>item</resourceName>
    <size>16</size>
    <entries>
    <entry id="53921915" link="/item/53921915.xml"/>
    <entry id="53921914" link="/item/53921914.xml"/>
    <entry id="53921911" link="/item/53921911.xml"/>
    <entry id="53921922" link="/item/53921922.xml"/>
    <entry id="53921923" link="/item/53921923.xml"/>
    <entry id="53921907" link="/item/53921907.xml"/>
    <entry id="53921909" link="/item/53921909.xml"/>
    <entry id="53921908" link="/item/53921908.xml"/>
    <entry id="53921910" link="/item/53921910.xml"/>
    <entry id="53921912" link="/item/53921912.xml"/>
    <entry id="53921913" link="/item/53921913.xml"/>
    <entry id="53921917" link="/item/53921917.xml"/>
    <entry id="53921918" link="/item/53921918.xml"/>
    <entry id="53921919" link="/item/53921919.xml"/>
    <entry id="53921920" link="/item/53921920.xml"/>
    <entry id="53921921" link="/item/53921921.xml"/>
    </entries>
    </result>

  10. Prezados,

    Ao realizar um Post ( lRet := oRest:Post(aHeader)), caso o método retorne o status 204 No Content, a thread leva cerca de 2 minutos para liberar a transação. No postman, o retorno é imediato. Seria uma deficiência da classe FwRest()? Há alguma forma de contornar essa situação? Adotamos como solução paliativa pedir ao proprietário da api modificar o status de 204 No Content para 200 Ok. Desta forma, a transação é liberada instantaneamente.
    Obrigado,

    Denison

  11. Denison boa tarde,


    Você pode setar manualmente oRest:nTimeOut := value em segundos.

    Segundo o pessoal de FrameWork o statusCode 204 é considerado uma meia resposta com sucesso, por isso que demora 2 minutos default, independente do verbo http sendo 204, vai demora 2 minutos o response.


    Outra alternativa seria, você utilizar HttpQuote(), nela você não vai ter esse problema.

    1. Marllon, mais uma vez muito obrigado pelo apoio!

  12. Buenas noches amigos. tengo una situación donde se envia al metodo POST el parametro REQUEST

    cJson := '{"request" : {"documentNumber": "FA2550","documentType": "A","customerName": "Julieta Aguirre","customerId": "AN586474","customerAddress": "Albrook","items": [{"code":"31","description": "Tratamiento","qty": "1","price": "20","tax":"7"}],"payments": [{"title": "Efectivo","amount": "40.00","type": "1"}]}}'

    oRestClt:SetPostParams(cJSon)

    , sin embargo h eintentado varias formas de poder enviar el parametro REQUEST a POST y el VALOR y no logro el retorno satisfactorio. esta correctala la manera de enviar el parametro REQUEST del POST y su valor o de que forma se deberia enviar este parametro al POST?


    Obrigado.

  13. cJson := '{"request" : {"documentNumber": "FA2550","documentType": "A","customerName": "Julieta Aguirre","customerId": "AN586474","customerAddress": "Albrook","items": [{"code":"31","description": "Tratamiento","qty": "1","price": 20,"tax":7}],"payments": [{"title": "Efectivo","amount": 40.00,"type": "1"}]}}'


    Os valores sem aspas!

  14. Bom dia,

    O método Post  esta retornando FALSO quando o retorno da API é 204 - NoContent. 

    Este retorno esta correto ?

    Foram utilizados binários e Rpo atualizados ?

    Obrigado,