restclient — n_pbt_restclient #

← Référence des composants · Sommaire du guide

Un client HTTPS pour PowerBuilder, la version 10 comprise : GET, POST, PUT, PATCH, DELETE, les en-têtes, un corps JSON, le téléchargement d'un fichier. Natif — le TLS, le proxy et la décompression du système, et aucun mur CORS, parce que la requête ne part pas d'une page.

▶ Le voir en vrai — Application de démonstration, tuile REST client : les réponses, le code qui les obtient et cette page, côte à côte (connexion Internet requise).

En bref #

Démarrage rapide #

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

Chaque méthode HTTP rend le statut que le serveur a choisi — un 404 est une réponse, pas une erreur — ou un code négatif quand la requête n'a pas abouti : -5 URL ou en-tête invalide, certificat client introuvable, -4 échec (pas de réseau, nom inconnu, délai dépassé, TLS, corps de texte de plus de 64 Mo — 16 Mo dans un processus 32 bits ; is_last_error dit lequel), -6 refusé en mode démo.

Pourquoi natif, et pas la page #

Un fetch() lancé depuis une page de la bibliothèque est soumis à CORS : toute API qui n'envoie pas Access-Control-Allow-Origin lui est fermée, et les API d'entreprise ne l'envoient pas. La requête part donc de la DLL, par WinHTTP : le TLS du système et ses certificats, le proxy configuré, gzip. Ce que vous perdez : rien ; ce que vous gagnez : toutes les API.

Propriétés #

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

Méthodes #

Exemples #

Lire une liste et la parcourir #

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

Télécharger un document #

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

Une API qui répond en erreur #

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

Une API d'intranet en authentification 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

Asynchrone (sans figer l'interface) #

Pendant un appel synchrone, l'interface est figée jusqu'à la réponse : la fenêtre ne se redessine plus et ne répond plus aux clics. C'est sans conséquence pour un appel court ; pour tout appel qui peut durer — un serveur lent, un gros corps, un réseau incertain —, prenez l'API asynchrone : la requête part sur un fil de travail et sa réponse revient plus tard en événement. Synchrone et asynchrone partagent la même session : le cookie posé par une connexion synchrone sert aux appels asynchrones qui suivent, et inversement ; un appel synchrone n'attend jamais derrière les requêtes asynchrones du même objet.

Mise en place — rien à câbler : le composant livre la réponse tout seul dans ue_response. of_open / of_close ouvrent et ferment le client (facultatif : la première requête l'ouvre), of_clear_cookies oublie les cookies gardés d'une requête à l'autre. En interne, un pump du composant appelle of_process_events pour drainer les réponses — vous ne l'appelez jamais.

Envoyer — of_request_async(method, url, body), ou les raccourcis of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, rendent aussitôt un id de requête — ou -5 tout de suite, sans aucun événement ensuite, pour une URL ou un en-tête invalide (is_last_error dit pourquoi, par exemple « invalid URL: … »). Six requêtes au plus partent en même temps ; les suivantes attendent leur tour dans une file. of_download_async(url, path) télécharge vers un fichier et of_upload(url, field, path) téléverse un fichier en multipart/form-data — les deux avec progression. of_cancel(id) arrête une requête. Les tentatives (il_max_retries, il_retry_backoff_ms) rejouent sur 429/503/panne réseau.

Recevoir — ue_response(al_id, al_status) (lire le corps avec of_response_text(al_id) / of_status(al_id) DANS le gestionnaire), ue_failed(al_id, al_code, as_error), ue_progress(al_id, al_done, al_total). Un id ne vaut que pour l'objet qui a envoyé la requête. Une erreur d'exécution dans l'un de ces événements n'est pas avalée : elle remonte à l'événement SystemError de l'application comme toute erreur de script, et les réponses suivantes sont livrées quand même.

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

Bonnes pratiques #

• Un client par API, avec son is_base_url et ses en-têtes posés une fois : le code des appels ne porte plus que le chemin et le corps.
• Le corps se construit avec n_pbt_json, jamais par concaténation : un guillemet dans un nom de client ne casse rien.
• Testez le statut, puis le code négatif : >= 200 et < 300 c'est bon, >= 400 le serveur a répondu non, < 0 la requête n'est pas partie — is_last_error dit pourquoi.
• Le délai : 30 secondes par défaut ; un rapport lourd en mérite plus, un contrôle de présence moins.
• Ce qui peut durer part en asynchrone : un appel synchrone fige l'interface jusqu'à la réponse.
• Une redirection garde votre requête : une 301 ou une 302 ne réécrit en GET qu'un POST — un PUT, un PATCH ou un DELETE est refait tel quel, corps compris ; une 303 repart en GET sans corps. Une Location relative (?page=2, ../) est résolue comme un navigateur le ferait.
• Une redirection vers un autre hôte n'emporte rien de vous : aucun des en-têtes posés par of_set_header (jeton, clé d'API) ne la suit — seul Content-Type reste. Une redirection HTTPS → HTTP est refusée.
• Testez le retour de of_set_header, of_set_bearer et of_set_basic quand la valeur vient d'une saisie ou d'un fichier : un saut de ligne y est refusé (-5) et rien n'est posé. Un en-tête refusé ne part jamais à moitié.
• Les identifiants Windows ne partent que si vous le demandez : ib_windows_auth = true pour une API d'intranet en authentification Windows, jamais sur un client qui parle à Internet.
• Un corps de texte est plafonné à 64 Mo, 16 Mo dans une application 32 bits : un export volumineux se lit avec of_download / of_download_async, qui écrivent un fichier sans limite.

← Référence des composants · Sommaire du guide