HTTPRequest
A classe HTTPRequest
permite-lhe tratar objectos HTTPRequest
que podem ser utilizados para configurar e enviar pedidos para um servidor HTTP, bem como para processar as respostas do servidor HTTP.
A classe HTTPRequest
está disponível a partir da loja de classes 4D
. Você cria e envia pedidos HTTP usando a função 4D.HTTPRequest.new() , que retorna um objecto HTTPRequest ``.
Histórico
Versão | Mudanças |
---|---|
v19 R6 | Classe adicionada |
Exemplo
Criar uma classe MyHttpRequestOptions
para as opções de pedido:
Class constructor($method : Text; $headers : Object; $body : Text)
This.method:=$method This.headers:=$headers This.body:=$body Function onResponse($request : 4D.HTTPRequest; $event : Object)
//Método My onResponse, se quiser manejar a petição de forma assincronica Function onError($request : 4D.HTTPRequest; $event : Object)
//Método My onError, se quiser manejar a petição de forma assincrônica
Pode agora criar o seu pedido:
var $headers : Object
$headers:=New object()
$headers["field1"]:="value1"
var myHttpRequestOptions : cs. MyHttpRequestOptions
myHttpRequestOptions := cs. MyHttpRequestOptions.new("GET"; $headers; "")
var $request : 4D.HTTPRequest
$request:=4D.HTTPRequest.new("www.google.com"; myHttpRequestOptions)
$request.wait() //If you want to handle the request synchronously
//Now pode usar $request.response para aceder ao resultado do pedido ou $request.error para verificar o erro que aconteceu.
Objeto HTTPRequest
Um objecto HTTPRequest é um objecto não partilhável.
Os objectos HTTPRequest fornecem as seguintes propriedades e funções:
dataType : Text o dataType passou no objecto opções ao chamar new(), "auto" se foi omitido |
encoding : Text a codificação passou nas opções [ ](#options-parameter) ao chamar new(), "UTF-8" se foi omitido |
errors : Collection a recolha de todos os erros, se pelo menos um erro tiver sido desencadeado |
headers : Object os cabeçalhos ` passaram no objecto [ opções`](#options-parameter) ao chamar new() |
method : Text o método ` passou no objecto [ opções`](#options-parameter) ao chamar new() |
protocol : Text o protocolo ` passou no objecto [ opções`](#options-parameter) ao chamar new() |
response : Object a resposta ao pedido, se tiver recebido pelo menos o código de estatuto, indefinido de outra forma |
returnResponseBody : Boolean o returnResponseBody passado no objeto opções ao chamar new() |
.terminate() aborta o pedido HTTP |
terminated : Boolean Verdadeiro se o pedido for terminado (após a chamada para onTerminate ), falso caso contrário |
timeout : Real o timeout passado no objeto opções ao chamar new() |
url : Text o URL do pedido HTTP |
.wait( { time : Real } ) : HTTPRequestClass aguarda a resposta do servidor |
4D.HTTPRequest.new()
Histórico
Versão | Mudanças |
---|---|
v20 | Validação TLS por padrão |
v19 R7 | Suporte às propriedades automaticRedirections e decodeData |
4D.HTTPRequest.new( url : Text { ; options : Object } ) : 4D.HTTPRequest
Parâmetro | Tipo | Descrição | |
---|---|---|---|
url | Text | -> | URL para onde enviar o pedido |
options | Object | -> | Pedir propriedades de configuração |
Resultados | 4D.HTTPRequest | <- | Novo objecto HTTPRequest |
|
Descrição
A função 4D.HTTPRequest.new()
cria e envia um pedido HTTP para o servidor HTTP definido em url com as opções definidas **, e devolve um objecto 4D.HTTPRequest
.
O objeto devolvido HTTPRequest
é utilizado para processar respostas do servidor HTTP e métodos de chamada.
Em url, passe o URL para onde pretende enviar o pedido. A sintaxe a utilizar é:
{http://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]
{https://}[{user}:[{password}]@]host[:{port}][/{path}][?{queryString}]
Se você omitir a parte do esquema (http://
ou https://
), será enviada uma solicitação https.
Por exemplo, pode passar as seguintes cordas:
http://www.myserver.com
www.myserver.com/path
http://www.myserver.com/path?name="jones"
https://www.myserver.com/login
http://123.45.67.89:8083
http://john:smith@123.45.67.89:8083
http://[2001:0db8:0000:0000:0000:ff00:0042:8329]
http://[2001:0db8:0000:0000:0000:ff00:0042:8329]:8080/index.html (**)
parâmetro options
No parâmetro opções , passe um objeto que possa conter as seguintes propriedades:
Propriedade | Tipo | Descrição | Por padrão |
---|---|---|---|
automaticRedirections | Parâmetros | Se true, os redirecionamentos serão realizados automaticamente (até 5 redirecionamentos são tratados, a resposta do 6. º redirecionamento é retornada, se houver) | True |
body | Diferente de | Corpo do pedido (requerido no caso de post ou put requests). Pode ser um texto, um blob, ou um objecto. O tipo de conteúdo é determinado a partir do tipo desta propriedade, a menos que seja colocado dentro dos cabeçalhos | indefinido |
certificatesFolder | Folder | Define a pasta de certificados de cliente activos | indefinido |
dataType | Text | Tipo de atributo do corpo de resposta. Valores: "texto", "blob", "objecto", ou "auto". Se "auto", o tipo do conteúdo do corpo será deduzido do seu tipo MIME (objecto para JSON, texto para texto, javascript, xml, mensagem http e forma codificada url, ou então um blob) | "auto" |
decodeData | Parâmetros | Se for verdade, os dados recebidos em onData callback não são compactados | False |
encoding | Text | Utilizado apenas em caso de pedidos com um body (métodos post ou put ). Codificação do conteúdo do corpo do pedido se for um texto, ignorado se o tipo de conteúdo for colocado dentro dos cabeçalhos | "UTF-8" |
headers | Object | Cabeçalhos do pedido. Sintaxe: headers.key=valor (valor pode ser uma Colecção se a mesma chave tiver de aparecer várias vezes) | Objecto vazio |
method | Text | "POST", "GET", ou outro método | "GET" |
minTLSVersion | Text | Define a versão mínima do TLS: "TLSv1_0 ", "TLSv1_1 ", "TLSv1_2 ", "TLSv1_3 " | "TLSv1_2 " |
onData | Function | Chamada de retorno quando os dados do corpo são recebidos. Recebe dois objectos como parâmetros (ver abaixo) | indefinido |
onError | Function | Chamada de retorno quando ocorre um erro. Recebe dois objectos como parâmetros (ver abaixo) | indefinido |
onHeaders | Function | Chamada de retorno quando os cabeçalhos são recebidos. Recebe dois objectos como parâmetros (ver abaixo) | indefinido |
onResponse | Function | Chamada de retorno quando uma resposta é recebida. Recebe dois objectos como parâmetros (ver abaixo) | indefinido |
onTerminate | Function | Chamada de retorno quando o pedido estiver terminado. Recebe dois objectos como parâmetros (ver abaixo) | indefinido |
protocol | Text | "auto" ou "HTTP1". "auto" significa HTTP1 na implementação actual | "auto" |
proxyAuthentication | authentication-object | Autenticação por procuração de tratamento de objectos | indefinido |
serverAuthentication | authentication-object | Autenticação do servidor de tratamento de objectos | indefinido |
returnResponseBody | Parâmetros | Se falso, o corpo de resposta não é devolvido na resposta objecto. Devolve um erro se falso e onData é indefinido | True |
timeout | Real | Tempo de espera em segundos. Indefinido = sem timeout | Indefinido |
validateTLSCertificate | Parâmetros | Se false, 4D não valida o certificado TLS e não retorna um erro se ele for inválido (i.e. expirado, auto-assinado...). Importante: Na implementação actual, a Autoridade de Certificação em si não é verificada. | True |
Funções Callback
Todas as funções de chamada de retorno recebem dois parâmetros de objectos:
Parâmetro | Tipo |
---|---|
$param1 | objeto HTTPRequest |
$param2 | Event objecto |
Aqui está a sequência de chamadas de retorno:
onHeaders
é sempre chamado uma vezonData
é chamado zero ou várias vezes (não chamado se o pedido não tiver um corpo)Se não ocorreu nenhum erro,
onResponse
é sempre chamado uma vezSe ocorrer um erro,
onError
é executado uma vez (e encerra o pedido)onTerminate
é sempre executado uma vez
objecto evento
Um evento `` objecto é devolvido quando uma função de retorno de chamada é chamada. Contém as seguintes propriedades:
Propriedade | Tipo | Descrição |
---|---|---|
.data | blob | Dados recebidos. É sempre indefinido excepto no onData callback |
.type | text | Tipo de evento. Possíveis valores: "resposta", "erro", "cabeçalhos", "dados", ou "terminar |
authentication-object
Um objecto de autenticação lida com o options.serverAuthentication
ou options.proxyAuthentication
propriedade. Pode conter as seguintes propriedades:
Propriedade | Tipo | Descrição | Por padrão |
---|---|---|---|
name | Text | Nome utilizado para autenticação | indefinido |
senha | Text | Senha utilizada para autenticação | indefinido |
method | Text | Método utilizado para autenticação: "basic", "digest", "auto". | "auto" |
HTTP Parse message
Histórico
Versão | Mudanças |
---|---|
v20 R4 | Adicionado |
HTTP Parse message( data : Text ) : Object
HTTP Parse message( data : Blob ) : Object
Parâmetro | Tipo | Descrição | |
---|---|---|---|
data | Text, Blob | -> | Dados a serem analisados |
Resultados | Object | <- | Objeto, cada propriedade é uma parte dos dados de várias partes |
|
Descrição
O comando HTTP Parse message
analisa um texto ou blob multipart/form-data (mensagem HTTP "response") e extrai o conteúdo para um objeto. Cada propriedade do objeto retornado corresponde a uma parte dos dados multipartes.
HTTP em si, é um protocolo de comunicação sem estado. Neste quadro, os clientes iniciam uma comunicação enviando mensagens "request" aos servidores, especificando detalhes como método, alvo, cabeçalhos, conteúdo, etc. Os servidores, respondem com mensagens de "resposta" que incluem os mesmos detalhes. HTTP Parse message
analisa a mensagem "request" ou de "response" em um objeto bem organizado.
Exemplo
No exemplo a seguir, analisamos os dados de um arquivo de texto que contém solicitações HTTP.
Aqui está o conteúdo do arquivo:
POST /batch/gmail/v1/ HTTP/1.1
Accept-Encoding: gzip, deflate
Authorization: Bearer xxxxxx
Connection: Close
Content-Length: 442
Content-Type: multipart/mixed; boundary=batch_19438756D576A14ABA87C112F56B9396; charset=UTF-8
Date: Wed, 29 Nov 2023 13:51:35 GMT
Host: gmail.googleapis.com
User-Agent: 4D/20.4.0
--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item1>
GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58689824c92?format=raw HTTP/1.1
--batch_19438756D576A14ABA87C112F56B9396
Content-Type: application/http
Content-ID: <item2>
GET https://gmail.googleapis.com/gmail/v1/users/me/messages/18c1b58642b28e2b?format=raw HTTP/1.1
--batch_19438756D576A14ABA87C112F56B9396--
Para analisar o arquivo:
var $message : Text:=File("/RESOURCES/HTTPrequest.txt").getText()
var $parsedMessage : Object:=HTTP Parse message($message)
//$parsedMessage= {
//headers:{"User-Agent":"4D/20.4.0",...},
//parts:[{"contentType":"application/http","contentID":"item1",...}],
//requestLine:"POST /batch/gmail/v1/ HTTP/1.1"
//}
.dataType
dataType : Text
Descrição
A propriedade .dataType
contém o dataType
passou no objecto opções
ao chamar new(), "auto" se foi omitido.
.encoding
encoding : Text
Descrição
A propriedade .encoding
contém a codificação passou nas opções [
](#options-parameter) ao chamar new(), "UTF-8" se foi omitido.
.errors
errors : Collection
Descrição
A propriedade .errors
contém a recolha de todos os erros, se pelo menos um erro tiver sido desencadeado.
Aqui está o conteúdo da propriedade .errors
:
Propriedade | Tipo | Descrição | |
---|---|---|---|
errors | Collection | pilha de erros 4D em caso de erro | |
[].errCode | Number | Código de erro 4D | |
[].message | Text | Descrição do erro 4D | |
[].componentSignature | Text | Assinatura da componente interna que devolveu o erro |
.headers
headers : Object
Descrição
A propriedade .headers
contém os cabeçalhos ` passaram no objecto [
opções`](#options-parameter) ao chamar new(). Se foi omitido, contém um objecto vazio.
.method
method : Text
Descrição
A propriedade .method
contém o método ` passou no objecto [
opções`](#options-parameter) ao chamar new(). Se foi omitido, contém "GET".
.protocol
protocol : Text
Descrição
A propriedade .protocol
contém o protocolo ` passou no objecto [
opções`](#options-parameter) ao chamar new(). Se foi omitido ou se "auto" foi utilizado, contém a versão do protocolo utilizado.
.response
Histórico
Versão | Mudanças |
---|---|
v19 R8 | .headers devolve nomes em minúsculas. Novo propriedade .rawHeaders |
response : Object
Descrição
O sítio .resposta
contém a resposta ao pedido, se tiver recebido pelo menos o código de estatuto, indefinido de outra forma.
Uma resposta
objecto é um objecto não partilhável. Contém as seguintes propriedades:
Propriedade | Tipo | Descrição |
---|---|---|
.body | Diferente de | Corpo da resposta. O tipo da mensagem é definido de acordo com a propriedade dataType . Indefinido se o corpo ainda não tiver sido recebido |
.headers | Object | Cabeçalhos da resposta. Os nomes dos cabeçalhos são devolvidos em minúsculas. <headername>.key = valor (valor pode ser uma colecção se a mesma chave aparecer várias vezes). Indefinido se os cabeçalhos ainda não tiverem sido recebidos. |
.status | Number | Código de estado da resposta |
.statusText | Text | Mensagem que explica o código de estado |
.rawHeaders | Object | Cabeçalhos da resposta. Os nomes dos cabeçalhos são devolvidos intactos (com o seu caso original). <headerName>.key = valor (valor pode ser uma colecção se a mesma chave aparecer várias vezes). Indefinido se os cabeçalhos ainda não tiverem sido recebidos. |
.returnResponseBody
returnResponseBody : Boolean
Descrição
A propriedade .returnResponseBody
contém o returnResponseBody
passado no objeto opções
ao chamar new(). Se foi omitido, contém True.
.terminate()
.terminate()
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Não exige nenhum parâmetro |
|
Descrição
Esta função é thread segura.
A função .terminate()
aborta o pedido HTTP. Desencadeia o evento onTerminate
.
.terminated
terminated : Boolean
Descrição
A propriedade .terminated
contém Verdadeiro se o pedido for terminado (após a chamada para onTerminate
), falso caso contrário.
.timeout
timeout : Real
Descrição
A propriedade .timeout
contém o timeout
passado no objeto opções
ao chamar new(). Se foi omitido, contém Indefinido.
.url
url : Text
Descrição
A propriedade .url
contém o URL do pedido HTTP.
.wait()
.wait( { time : Real } ) : HTTPRequestClass
Parâmetro | Tipo | Descrição | |
---|---|---|---|
time | Real | -> | Tempo máximo em segundos para esperar pela resposta |
Resultados | 4D.HTTPRequest | <- | HTTPRequest object |
|
Descrição
Esta função é thread segura.
A função wait()
aguarda a resposta do servidor.
Se for passado um parâmetro tempo , a função esperará no máximo o número definido de segundos.
Se a resposta do servidor já tiver chegado, a função regressa imediatamente.