restclient — n_pbt_restclient #

← Referência dos componentes · Índice do guia

Um cliente HTTPS para PowerBuilder, versão 10 incluída: GET, POST, PUT, PATCH, DELETE, cabeçalhos, um corpo JSON, a transferência de um ficheiro. Nativo — o TLS, o proxy e a descompressão do sistema, e nenhum muro CORS, porque o pedido não parte de uma página.

▶ Ver ao vivo — Aplicação de demonstração, mosaico REST client: as respostas, o código que as obtém e esta página, lado a lado (ligação à Internet necessária).

Em resumo #

Início rápido #

// Local variables
n_pbt_restclient lnv_rest
n_pbt_json lnv_j
long ll_status

// One client for the API : its address and the token it sends
lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
lnv_rest.of_set_bearer(/*token*/ ls_token)

// Read : the status comes back, the body waits in the object
ll_status = lnv_rest.of_get(/*url*/ "/orders/4152")
if ll_status = 200 then ls_customer = lnv_rest.of_json_value(/*path*/ "customer")

// Create : the body is built with n_pbt_json, never by hand
lnv_j.of_set_number(/*path*/ "order", /*value*/ 4152)
lnv_j.of_set_string(/*path*/ "status", /*value*/ "shipped")
ll_status = lnv_rest.of_post(/*url*/ "/shipments", /*body*/ lnv_j.of_text())
if ll_status < 0 then MessageBox("API", lnv_rest.is_last_error)

// The client is no longer needed
destroy lnv_rest

Cada método HTTP devolve o estado que o servidor escolheu — um 404 é uma resposta, não um erro — ou um código negativo quando o pedido não foi concluído: -5 URL ou cabeçalho inválido, certificado de cliente não encontrado, -4 falha (sem rede, nome desconhecido, tempo esgotado, TLS, um corpo de texto com mais de 64 MB — 16 MB num processo de 32 bits; is_last_error diz qual), -6 recusado em modo demo.

Porquê nativo, e não a página #

Um fetch() lançado a partir de uma página da biblioteca está sujeito a CORS: toda a API que não envie Access-Control-Allow-Origin fica-lhe fechada, e as API de empresa não o enviam. O pedido parte por isso da DLL, por WinHTTP: o TLS do sistema com os seus certificados, o proxy configurado, gzip. O que perde: nada; o que ganha: todas as API.

Propriedades #

Constantes: METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE para of_request.

Métodos #

Exemplos #

Ler uma lista e percorrê-la #

// Local variables
string ls_body, ls_id
n_pbt_json lnv_list
long ll_i

// One value : of_json_value("items/1/id"). The whole list : load the body into an
// n_pbt_json and walk it by path.
if lnv_rest.of_get(/*url*/ "/orders?status=open") = 200 then
	ls_body = lnv_rest.of_response_text()
	lnv_list.of_load(/*json*/ ls_body)
	for ll_i = 1 to lnv_list.of_count(/*path*/ "items")
		ls_id = lnv_list.of_get_string(/*path*/ "items/" + String(ll_i) + "/id")
	next
end if

Transferir um documento #

// Local variables
long ll_status

// Download the invoice to a file, then open it
ll_status = lnv_rest.of_download(/*url*/ "/orders/4152/invoice.pdf", /*path*/ "C:\temp\invoice-4152.pdf")
if ll_status = 200 then
	Run("C:\temp\invoice-4152.pdf")
elseif ll_status < 0 then
	MessageBox("Download", lnv_rest.is_last_error)
end if

Uma API que responde com erro #

// The status decides : 200 or 201 = created, 401 = the token expired,
// below 0 = the network failed
choose case lnv_rest.of_post(/*url*/ "/shipments", /*body*/ ls_body)
	case 200, 201
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value(/*path*/ "message"))
	case is < 0
		MessageBox("Network", lnv_rest.is_last_error)
end choose

Uma API de intranet com autenticação Windows #

// Local variables
n_pbt_restclient lnv_rest
long ll_status

// An IIS API of the intranet : the Windows session answers the server's challenge,
// nothing is typed. Off by default : switch it on for this client only.
lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://erp.intranet.local/api"
lnv_rest.ib_windows_auth = true

// A header refused (a line break in the value) returns -5 and is not set
if lnv_rest.of_set_header(/*name*/ "X-Client", /*value*/ "PowerBuilder") < 0 then return

// Read an order : 401 when the server refused the Windows account
ll_status = lnv_rest.of_get(/*url*/ "/orders/4152")
if ll_status = 401 then
	MessageBox("ERP", "Access denied")
elseif ll_status < 0 then
	MessageBox("ERP", lnv_rest.is_last_error)
end if

// The client is no longer needed
destroy lnv_rest

Assíncrono (sem congelar a interface) #

Durante uma chamada síncrona a interface fica congelada até à resposta: a janela deixa de se redesenhar e de responder aos cliques. Não tem consequências numa chamada curta; para qualquer chamada que possa demorar — um servidor lento, um corpo grande, uma rede incerta —, use a API assíncrona: o pedido parte numa thread de trabalho e a sua resposta volta mais tarde como evento. Síncrono e assíncrono partilham a mesma sessão: o cookie definido por um início de sessão síncrono serve as chamadas assíncronas que se seguem, e vice-versa; uma chamada síncrona nunca espera atrás dos pedidos assíncronos do mesmo objeto.

Preparação — nada a ligar: o componente entrega sozinho a resposta em ue_response. of_open / of_close abrem e fecham o cliente (facultativo: o primeiro pedido abre-o), of_clear_cookies esquece os cookies guardados de um pedido para o outro. Internamente, uma bomba do componente chama of_process_events para drenar as respostas — nunca a chama.

Enviar — of_request_async(method, url, body), ou os atalhos of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, devolvem de imediato um id de pedido — ou -5 de imediato, sem nenhum evento depois, para um URL ou um cabeçalho inválido (is_last_error diz porquê, por exemplo «invalid URL: …»). Seis pedidos no máximo partem ao mesmo tempo; os seguintes esperam a sua vez numa fila. of_download_async(url, path) transfere para um ficheiro e of_upload(url, field, path) envia um ficheiro em multipart/form-data — ambos com progresso. of_cancel(id) pára um pedido. As tentativas (il_max_retries, il_retry_backoff_ms) repetem em 429/503/falha de rede.

Receber — ue_response(al_id, al_status) (ler o corpo com of_response_text(al_id) / of_status(al_id) DENTRO do handler), ue_failed(al_id, al_code, as_error), ue_progress(al_id, al_done, al_total). Um id só vale para o objeto que enviou o pedido. Um erro de execução num destes eventos não é engolido: chega ao evento SystemError da aplicação como qualquer erro de script, e as respostas seguintes são entregues na mesma.

// Async : the UI never freezes, and there is nothing to wire.
ll_id = uo_rest.of_get_async(/*url*/ "https://api.example.com/orders/4152")

// The answer arrives on its own in the ue_response event of uo_rest :
IF al_status >= 200 AND al_status < 300 THEN
	ls_body = uo_rest.of_response_text(/*id*/ al_id)
END IF

Boas práticas #

• Um cliente por API, com o seu is_base_url e os seus cabeçalhos definidos uma vez: o código das chamadas só leva o caminho e o corpo.
• O corpo constrói-se com n_pbt_json, nunca por concatenação: uma aspa no nome de um cliente não parte nada.
• Teste o estado, depois o código negativo: >= 200 e < 300 está bem, >= 400 o servidor disse que não, < 0 o pedido não partiu — is_last_error diz porquê.
• O tempo limite: 30 segundos por predefinição; um relatório pesado merece mais, uma verificação de presença menos.
• O que pode demorar vai em assíncrono: uma chamada síncrona congela a interface até à resposta.
• Um redirecionamento mantém o seu pedido: um 301 ou um 302 só reescreve em GET um POST — um PUT, um PATCH ou um DELETE é refeito tal como está, corpo incluído; um 303 segue em GET sem corpo. Uma Location relativa (?page=2, ../) é resolvida como um navegador o faria.
• Um redirecionamento para outro anfitrião não leva nada seu: nenhum dos cabeçalhos definidos por of_set_header (token, chave de API) o segue — só fica Content-Type. Um redirecionamento HTTPS → HTTP é recusado.
• Teste o que of_set_header, of_set_bearer e of_set_basic devolvem quando o valor vem de uma introdução ou de um ficheiro: uma quebra de linha é aí recusada (-5) e nada é definido. Um cabeçalho recusado nunca parte a meio.
• As credenciais Windows só partem se o pedir: ib_windows_auth = true para uma API de intranet com autenticação Windows, nunca num cliente que fala com a Internet.
• Um corpo de texto está limitado a 64 MB, 16 MB numa aplicação de 32 bits: uma exportação volumosa lê-se com of_download / of_download_async, que escrevem um ficheiro sem limite.

← Referência dos componentes · Índice do guia