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 #

// Local variables
n_pbt_restclient lnv_rest
n_pbt_json lnv_j
string ls_token, ls_customer
long ll_status

// One client for the API : its address and the token it sends (here read from the settings)
lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
ls_token = ProfileString("app.ini", "api", "token", "")
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.of_get_last_error())

// The client is no longer needed
destroy lnv_rest

Ogni metodo HTTP restituisce lo stato scelto dal server — un 404 è una risposta, non un errore — oppure un codice negativo quando la richiesta non è andata a buon fine: -5 URL o intestazione non validi, certificato client non trovato, -4 fallimento (nessuna rete, nome sconosciuto, tempo scaduto, TLS, un corpo di testo oltre 64 MB — 16 MB in un processo a 32 bit; of_get_last_error() dice quale), -6 rifiutato in modalità demo. -2 dice che il client non ha potuto essere creato. Un oggetto creato con create basta per le chiamate sincrone; per gli eventi delle chiamate asincrone, vedere «Dove scrivere gli event», più sotto.

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 #

// 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

Scaricare un 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.of_get_last_error())
end if

Un'API che risponde con un errore #

// Local variables
n_pbt_json lnv_j

// The status decides : 200 or 201 = created, 400 = the request was refused (is_last_request
// tells what it asked for, its secrets masked), 401 = the token expired, below 0 = the network failed
lnv_j.of_set_number(/*path*/ "order", /*value*/ 4152)
choose case lnv_rest.of_post(/*url*/ "/shipments", /*body*/ lnv_j.of_text())
	case 200, 201
	case 400
		MessageBox("API", lnv_rest.of_json_value(/*path*/ "message") + "~r~n~r~n" + lnv_rest.is_last_request)
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value(/*path*/ "message"))
	case is < 0
		MessageBox("Network", lnv_rest.of_get_last_error())
end choose

Un'API dell'intranet con autenticazione 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.of_get_last_error())
end if

// The client is no longer needed
destroy lnv_rest

Una ricerca digitata dall'utente #

// Local variables
string ls_names[], ls_values[]
long ll_status

// What the user typed may hold # & + : of_url encodes every name and every value
ls_names[1] = "q"
ls_values[1] = sle_search.text
ls_names[2] = "page"
ls_values[2] = "2"
ll_status = lnv_rest.of_get(/*url*/ lnv_rest.of_url(/*path*/ "/items", /*names*/ ls_names, /*values*/ ls_values))

Un'API protetta da OAuth2 #

// Local variables
n_pbt_restclient lnv_api

// One client for an API protected by OAuth2 (Azure AD, Keycloak, Salesforce...) : the token
// is asked once, then renewed by the client itself a minute before it expires
lnv_api = create n_pbt_restclient
lnv_api.is_base_url = "https://api.example.com"
if lnv_api.of_oauth_client_credentials(/*token_url*/ "https://login.example.com/oauth2/token", /*client*/ "my-app", /*secret*/ ProfileString("app.ini", "api", "secret", ""), /*scope*/ "orders.read") < 0 then
	MessageBox("API", lnv_api.of_get_last_error())
	return
end if

// Every request now carries the token
lnv_api.of_get(/*url*/ "/orders/4152")
destroy lnv_api

Un elenco in un DataStore #

// Local variables
datastore lds_orders
long ll_rows

// The open orders of the API straight into a DataStore, as Retrieve does from a database :
// one row per object, each member in the column of its name, the rows not modified
lds_orders = create datastore
lds_orders.DataObject = "d_orders"
ll_rows = lnv_rest.of_retrieve(/*target*/ lds_orders, /*url*/ "/orders?status=open", /*path*/ "items")
if ll_rows < 0 then MessageBox("API", lnv_rest.of_get_last_error())

Asincrono (senza bloccare l'interfaccia) #

Durante una chiamata sincrona l'interfaccia è bloccata fino alla risposta: la finestra non si ridisegna più e non risponde più ai clic. Per una chiamata breve non ha conseguenze; per ogni chiamata che può durare — un server lento, un corpo grande, una rete incerta —, usa l'API asincrona: la richiesta parte su un thread di lavoro e la sua risposta torna più tardi come evento. Sincrono e asincrono condividono la stessa sessione: il cookie impostato da un login sincrono serve alle chiamate asincrone che seguono, e viceversa; una chiamata sincrona non attende mai dietro le richieste asincrone dello stesso oggetto.

Preparazione — niente da collegare: il componente consegna da solo la risposta in ue_response. of_open / of_close aprono e chiudono il client (facoltativo: la prima richiesta lo apre), of_clear_cookies dimentica i cookie conservati tra una richiesta e l'altra. Internamente, una pompa del componente chiama of_process_events per drenare le risposte — non la 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 — oppure -5 subito, senza alcun evento dopo, per un URL o un'intestazione non validi (of_get_last_error() dice perché, per esempio «invalid URL: …»). Al massimo sei richieste partono insieme; le successive attendono il loro turno in una coda. of_download_async(url, path) scarica in un file e of_upload(url, field, path) invia un file in multipart/form-data — entrambi con avanzamento. of_cancel(id) ferma una richiesta. I tentativi (il_max_retries, il_retry_backoff_ms) ripetono su 429/503/guasto 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, al_code, as_error), ue_progress(al_id, al_done, al_total). Un id vale solo per l'oggetto che ha inviato la richiesta. Un errore di esecuzione in uno di questi eventi non viene inghiottito: risale all'evento SystemError dell'applicazione come ogni errore di script, e le risposte successive vengono consegnate comunque.

Dove scrivere gli event #

Un oggetto creato con create n_pbt_restclient serve benissimo le chiamate sincrone — è ciò che fa l'avvio rapido —, ma i suoi eventi non hanno script: PowerBuilder non permette di scrivere ue_response su un oggetto creato in uno script. Per le chiamate asincrone, due strade:

• l'oggetto posto nella finestra (o nell'oggetto utente): nel painter, inserite un oggetto non visuale n_pbt_restclient e chiamatelo inv_rest; i suoi eventi ue_response, ue_failed e ue_progress si scrivono allora come quelli di un controllo, e nasce e muore con la finestra — ciò che fa l'applicazione dimostrativa;
• un discendente: ereditate da n_pbt_restclient (n_my_api), scrivete ue_response in quel discendente e createlo con create n_my_api.

Chiudere da uno dei suoi eventi la finestra che porta il client è permesso: le risposte ancora in attesa non vengono consegnate.

// Local variables
long ll_id

// Async : the UI never freezes, and there is nothing to wire. inv_rest is the restclient
// placed in the window ; the request id comes back at once
ll_id = inv_rest.of_get_async(/*url*/ "https://api.example.com/orders/4152")

// Local variables
string ls_body

// Event ue_response of inv_rest : the answer arrives on its own, and it is read here
if al_status >= 200 and al_status < 300 then ls_body = this.of_response_text(/*id*/ al_id)

Buone pratiche #

• Un client per API, con il suo is_base_url e le sue intestazioni impostati 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 nel nome di un cliente non rompe nulla.
• Verifica lo stato, poi il codice negativo: >= 200 e < 300 va bene, >= 400 il server ha detto no, < 0 la richiesta non è partita — of_get_last_error() dice perché.
• Il tempo limite: 30 secondi per impostazione predefinita; un report pesante ne merita di più, un controllo di presenza di meno.
• Ciò che può durare va in asincrono: una chiamata sincrona blocca l'interfaccia fino alla risposta.
• Un reindirizzamento conserva la tua richiesta: un 301 o un 302 riscrive in GET solo un POST — un PUT, un PATCH o un DELETE viene rifatto così com'è, corpo compreso; un 303 riparte in GET senza corpo. Una Location relativa (?page=2, ../) è risolta come farebbe un browser.
• Un reindirizzamento verso un'altra origine non porta nulla di vostro: nessuna delle intestazioni impostate con of_set_header (token, chiave API) lo segue — resta solo Content-Type. Un'origine è un host, una porta e uno schema: un'API http:// reindirizzata verso https:// perde il suo token, scrivete quindi https:// in is_base_url. Le credenziali Windows (ib_windows_auth) e il certificato client sono dati solo all'host e alla porta della richiesta. Un reindirizzamento HTTPS → HTTP è rifiutato.
• Verifica il ritorno di of_set_header, of_set_bearer e of_set_basic quando il valore viene da un input o da un file: un a capo, o un carattere oltre il Latin-1 (un'intestazione viaggia in Latin-1; non per of_set_basic, la cui coppia parte in base64), vi è rifiutato (-5) e nulla viene impostato. Un'intestazione rifiutata non parte mai a metà.
• Le credenziali Windows partono solo se lo chiedi: ib_windows_auth = true per un'API dell'intranet con autenticazione Windows, mai su un client che parla con Internet.
• Un corpo di testo è limitato a 64 MB, 16 MB in un'applicazione a 32 bit: un export voluminoso si legge con of_download / of_download_async, che scrivono un file senza limiti.
• Codificate ciò che l'utente ha digitato: la query di un URL parte così come è scritta — un # la taglia, un & aggiunge un parametro, un + diventa uno spazio. Costruitela con of_url, o codificate un valore con of_url_encode.
• Mai credenziali nell'URL (https://user:pwd@…): la richiesta è rifiutata (-5); usate of_set_basic.
• Lo User-Agent vale PBToolboxAI/<versione>; of_set_header("User-Agent", …) lo sostituisce quando un'API esige il vostro.

← Riferimento dei componenti · Sommario della guida