- Criado por Rodrigo Antonio Godinho da Silva, última alteração por Bruno Alexandrino Pirolo em 15 jul, 2024
Classe: FWRest
Descrição
Classe Client de REST
New
Sintaxe
FWREST():New(<cHost >)-> NIL
Descrição
Construtor
Parâmetros
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| cHost | Caracteres | Endereç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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| cPath | Caracteres | Path 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| aHeadStr | Array | Array com parâmetros do head | X | ||
| cGetParam | Caracteres | Indica 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| aHeadStr | Array | Array 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| cParams | Caracteres | Parâ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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| aHeadStr | Array | Array com parâmetros do head | X | ||
| cPayLoad | Caractere | Corresponde à StringList de parâmetros a serem enviados ao servidor HTTP | "" | ||
| cGETParms | Caractere | Corresponde 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| aHeadStr | Array | Array com parâmetros do head | X | ||
| cPayLoad | Caractere | Corresponde à StringList de parâmetros a serem enviados ao servidor HTTP | "" | ||
| cGETParms | Caractere | Corresponde 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| lChk | Lógico | Variá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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| cGetParams | Charactere | String 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
| Nome | Tipo | Descrição | Default | Obrigatório | Referência |
| lActive | Logical | Indica 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
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas
22 Comentários
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.
Guilherme Spadaccia Leme
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)
Marllon Fernandes Da Silva
Bom dia,
Gostaria de saber se existe o method patch na classe FWREST ?
Guilherme Spadaccia Leme
Bom dia.
Não é possível. O FWRest tem suporte apenas para os verbos: POST, GET, PUT e DELETE
Diego Fernando Venturi
Existe alguma forma de ligar um TRACE para ser emitido no console?
Guilherme Spadaccia Leme
Bom dia.
Para habilitar o trace inclua a chave FWTraceLog=1 na configuração do seu environment.
Att.
Mauricio Canalle
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)
Rafael Diego Furquim de Oliveira
Prezados, existe algum comando em especial no FWREST para trabalhar com sites que exijam certificado(ssl - https)?
Guilherme Spadaccia Leme
Bom dia.
O FWRest já encapsula o SSL, basta configura-lo no seu appserver.ini, internamente já será usando seu certificado.
Att.
Denison Soares de Franca Nascimento
Prezados,
Observem o bloco de código abaixo:
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.
Marllon Fernandes Da Silva
Denison, tenta usar a função HTTPHeader("Authorization"), onde "Authorization" é a propriedade que deseja pegar o valor.
Denison Soares de Franca Nascimento
Obrigado pelo esclarecimento da minha dúvida, Marllon! Abraços!
Antonio Carlos Ferreira
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) [ ]
Leonardo Maria Pereira
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,
Antonio Carlos Ferreira
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
Diogo Melo Da Silva
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>
Denison Soares De Franca Nascimento
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
Marllon Fernandes Da Silva
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.
Denison Soares De Franca Nascimento
Marllon, mais uma vez muito obrigado pelo apoio!
Cesar Bautista Perea
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.
Antonio Carlos Ferreira
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!
Rafael Tenorio da Costa_
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,