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 #

n_pbt_restclient lnv_rest
n_pbt_json lnv_j
long ll_status

lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
lnv_rest.of_set_bearer(ls_token)

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

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

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 passou: -5 URL inválido, -4 falha (sem rede, nome desconhecido, tempo esgotado, TLS; 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 #

string ls_body
if lnv_rest.of_get("/orders?status=open") = 200 then
	ls_body = lnv_rest.of_response_text()
	// One value : of_json_value. The whole list : n_pbt_utils.of_json_get_payload and
	// of_json_get_str on each object, or your own parser on ls_body.
end if

Transferir um documento #

long ll_status
ll_status = lnv_rest.of_download("/orders/4152/invoice.pdf", "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 #

choose case lnv_rest.of_post("/shipments", ls_body)
	case 200, 201
		// created
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value("message"))
	case is < 0
		MessageBox("Network", lnv_rest.is_last_error)
end choose

Assíncrono (sem congelar a interface) #

As chamadas síncronas acima bloqueiam o script (a interface fica viva mas a linha espera). A API assíncrona nem sequer bloqueia o script: o pedido corre num fio de trabalho e a resposta volta mais tarde como evento.

Preparação — nada a ligar: o componente entrega a resposta sozinho em ue_response. of_open / of_close abrem e fecham o cliente (facultativo: o primeiro pedido async abre-o), of_clear_cookies esquece os cookies guardados entre pedidos. Internamente o pump do componente chama of_process_events para distribuir as respostas — nunca o 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. of_download_async(url, path) descarrega para um ficheiro e of_upload(url, field, path) envia um ficheiro como multipart/form-data — ambos com progresso. of_cancel(id) para um pedido em curso. 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 tratador), ue_failed(al_id, as_error), ue_progress(al_id, al_done, al_total).

// Async : the UI never freezes, and there is nothing to wire.
ll_id = uo_rest.of_get_async("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(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ó transporta o caminho e o corpo.
• O corpo constrói-se com n_pbt_json, nunca por concatenação: uma aspa num nome de cliente não parte nada.
• Teste o estado, depois o código negativo: >= 200 e < 300 está bem, >= 400 o servidor disse não, < 0 o pedido não partiu — is_last_error diz porquê.
• O tempo limite: 30 segundos por defeito; um relatório pesado merece mais, uma verificação de presença menos.

← Referência dos componentes · Índice do guia