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

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 ; of_get_last_error() dit lequel), -6 refusé en mode démo. -2 dit que le client n'a pas pu être créé. Un objet créé par create suffit pour le synchrone ; pour les événements de l'asynchrone, voyez « Où écrire les événements », plus bas.

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

Une API qui répond en erreur #

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

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

// The client is no longer needed
destroy lnv_rest

Une recherche saisie par l'utilisateur #

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

Une API protégée par 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

Une liste dans 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())

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 (of_get_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.

Où écrire les événements #

Un objet créé par create n_pbt_restclient sert très bien le synchrone — c'est ce que fait le démarrage rapide —, mais ses événements n'ont aucun script : PowerBuilder ne permet pas d'écrire ue_response sur un objet créé dans un script. Pour l'asynchrone, deux voies :

• l'objet posé dans la fenêtre (ou l'objet utilisateur) : dans le peintre, insérez un objet non visuel n_pbt_restclient et nommez-le inv_rest ; ses événements ue_response, ue_failed et ue_progress se scriptent alors comme ceux d'un contrôle, et il naît et meurt avec la fenêtre — c'est ce que fait l'application de démonstration ;
• un descendant : héritez de n_pbt_restclient (n_my_api), écrivez ue_response dans ce descendant, et créez-le par create n_my_api.

Fermer la fenêtre qui porte le client depuis l'un de ses événements est permis : les réponses qui attendaient encore ne sont pas livrées.

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

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 — of_get_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 une autre origine 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 origine, c'est un hôte, un port et un schéma : une API http:// redirigée vers https:// perd son jeton, écrivez donc https:// dans is_base_url. Les identifiants Windows (ib_windows_auth) et le certificat client ne sont donnés qu'à l'hôte et au port de la requête. 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, ou un caractère au-delà du Latin-1 (un en-tête voyage en Latin-1 ; pas pour of_set_basic, dont la paire part en base64), 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.
• Encodez ce que l'utilisateur a tapé : la requête d'une URL part telle qu'écrite — un # la coupe, un & ajoute un paramètre, un + devient une espace. Construisez-la avec of_url, ou encodez une valeur avec of_url_encode.
• Jamais d'identifiants dans l'URL (https://user:mdp@…) : la requête est refusée (-5) ; prenez of_set_basic.
• Le User-Agent vaut PBToolboxAI/<version> ; of_set_header("User-Agent", …) le remplace quand une API exige le vôtre.

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