restclient — n_pbt_restclient #

← Riferimento dei componenti · Sommario della guida

Un client HTTPS per PowerBuilder, versione 10 compresa: GET, POST, PUT, PATCH, DELETE, intestazioni, un corpo JSON, il download di un file. Nativo — TLS, proxy e decompressione del sistema, e nessun muro CORS, perché la richiesta non parte da una pagina.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro REST client: le risposte, il codice che le ottiene e questa pagina, fianco a fianco (connessione Internet richiesta).

In breve #

Avvio rapido #

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

Ogni metodo HTTP restituisce lo stato scelto dal server — un 404 è una risposta, non un errore — o un codice negativo quando la richiesta non è andata a buon fine: -5 URL non valido, -4 fallimento (niente rete, nome sconosciuto, timeout, TLS; is_last_error dice quale), -6 rifiutato in modalità demo.

Perché nativo, e non la pagina #

Un fetch() lanciato da una pagina della libreria è soggetto a CORS: ogni API che non invia Access-Control-Allow-Origin gli è chiusa, e le API aziendali non lo inviano. La richiesta parte quindi dalla DLL, tramite WinHTTP: il TLS del sistema con i suoi certificati, il proxy configurato, gzip. Ciò che perdi: nulla; ciò che guadagni: tutte le API.

Proprietà #

Costanti: METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE per of_request.

Metodi #

Esempi #

Leggere un elenco e scorrerlo #

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

Scaricare un 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

Un'API che risponde con un errore #

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

Asincrono (nessun blocco dell'interfaccia) #

Le chiamate sincrone qui sopra bloccano lo script (l'interfaccia resta viva ma la riga attende). L'API asincrona non blocca nemmeno lo script: la richiesta parte su un thread di lavoro e la risposta torna più tardi come evento.

Impostazione — niente da collegare: il componente consegna la risposta da solo in ue_response. of_open / of_close aprono e chiudono il client (facoltativo: la prima chiamata async lo apre), of_clear_cookies dimentica i cookie tenuti tra le richieste. Internamente il pump del componente chiama of_process_events per distribuire le risposte — non lo chiami mai.

Inviare — of_request_async(method, url, body), o le scorciatoie of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, restituiscono subito un id di richiesta. of_download_async(url, path) scarica in un file e of_upload(url, field, path) carica un file come multipart/form-data — entrambi con progresso. of_cancel(id) ferma una richiesta in volo. I tentativi (il_max_retries, il_retry_backoff_ms) rigiocano su 429/503/errore di rete.

Ricevere — ue_response(al_id, al_status) (leggere il corpo con of_response_text(al_id) / of_status(al_id) DENTRO il gestore), 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

Buone pratiche #

• Un client per API, con il suo is_base_url e le sue intestazioni impostate una volta: il codice delle chiamate porta solo il percorso e il corpo.
• Il corpo si costruisce con n_pbt_json, mai per concatenazione: una virgoletta in un nome di cliente non rompe nulla.
• Controlla lo stato, poi il codice negativo: >= 200 e < 300 va bene, >= 400 il server ha detto no, < 0 la richiesta non è partita — is_last_error dice perché.
• Il timeout: 30 secondi per impostazione predefinita; un report pesante ne merita di più, un controllo di presenza di meno.

← Riferimento dei componenti · Sommario della guida