restclient — n_pbt_restclient #

← Referencia de componentes · Índice de la guía

Un cliente HTTPS para PowerBuilder, versión 10 incluida: GET, POST, PUT, PATCH, DELETE, cabeceras, un cuerpo JSON, la descarga de un archivo. Nativo — el TLS, el proxy y la descompresión del sistema, y ningún muro CORS, porque la petición no sale de una página.

▶ Verlo en vivo — Aplicación de demostración, mosaico REST client: las respuestas, el código que las obtiene y esta página, lado a lado (se requiere conexión a Internet).

En resumen #

Inicio rápido #

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

Cada método HTTP devuelve el estado que el servidor eligió — un 404 es una respuesta, no un error — o un código negativo cuando la petición no llegó a buen puerto: -5 URL o cabecera no válida, certificado de cliente no encontrado, -4 fallo (sin red, nombre desconocido, tiempo agotado, TLS, un cuerpo de texto de más de 64 MB — 16 MB en un proceso de 32 bits; of_get_last_error() dice cuál), -6 rechazado en modo demo. -2 dice que el cliente no pudo crearse. Un objeto creado con create basta para las llamadas síncronas; para los eventos de las asíncronas, vea «Dónde escribir los eventos», más abajo.

Por qué nativo, y no la página #

Un fetch() lanzado desde una página de la biblioteca está sujeto a CORS: toda API que no envíe Access-Control-Allow-Origin le queda cerrada, y las API de empresa no lo envían. La petición sale por tanto de la DLL, por WinHTTP: el TLS del sistema con sus certificados, el proxy configurado, gzip. Lo que pierde: nada; lo que gana: todas las API.

Propiedades #

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

Métodos #

Ejemplos #

Leer una lista y recorrerla #

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

Descargar 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

Una API que responde con error #

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

Una API de intranet con autenticación de 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 búsqueda escrita por el usuario #

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

Una API protegida por 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

Una lista en 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())

Asíncrono (sin congelar la interfaz) #

Durante una llamada síncrona la interfaz queda congelada hasta la respuesta: la ventana ya no se redibuja ni responde a los clics. No tiene consecuencias en una llamada corta; para toda llamada que pueda tardar — un servidor lento, un cuerpo grande, una red incierta —, use la API asíncrona: la petición sale en un hilo de trabajo y su respuesta vuelve más tarde como evento. Síncrono y asíncrono comparten la misma sesión: la cookie puesta por un inicio de sesión síncrono sirve a las llamadas asíncronas que siguen, y viceversa; una llamada síncrona nunca espera detrás de las peticiones asíncronas del mismo objeto.

Preparación — nada que conectar: el componente entrega la respuesta solo en ue_response. of_open / of_close abren y cierran el cliente (opcional: la primera petición lo abre), of_clear_cookies olvida las cookies guardadas entre peticiones. Internamente, una bomba del componente llama a of_process_events para drenar las respuestas — usted nunca la llama.

Enviar — of_request_async(method, url, body), o los atajos of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async, devuelven al instante un id de petición — o -5 al instante, sin ningún evento después, para una URL o una cabecera no válida (of_get_last_error() dice por qué, por ejemplo «invalid URL: …»). Seis peticiones como máximo salen a la vez; las siguientes esperan su turno en una cola. of_download_async(url, path) descarga a un archivo y of_upload(url, field, path) sube un archivo en multipart/form-data — ambos con progreso. of_cancel(id) detiene una petición. Los reintentos (il_max_retries, il_retry_backoff_ms) repiten en 429/503/fallo de red.

Recibir — ue_response(al_id, al_status) (leer el cuerpo con of_response_text(al_id) / of_status(al_id) DENTRO del manejador), ue_failed(al_id, al_code, as_error), ue_progress(al_id, al_done, al_total). Un id solo vale para el objeto que envió la petición. Un error de ejecución en uno de estos eventos no se traga: llega al evento SystemError de la aplicación como cualquier error de script, y las respuestas siguientes se entregan igualmente.

Dónde escribir los eventos #

Un objeto creado con create n_pbt_restclient sirve muy bien para las llamadas síncronas — es lo que hace el inicio rápido —, pero sus eventos no tienen script: PowerBuilder no permite escribir ue_response en un objeto creado en un script. Para las llamadas asíncronas, dos vías:

• el objeto colocado en la ventana (o en el objeto de usuario): en el pintor, inserte un objeto no visual n_pbt_restclient y llámelo inv_rest; sus eventos ue_response, ue_failed y ue_progress se programan entonces como los de un control, y nace y muere con la ventana — lo que hace la aplicación de demostración;
• un descendiente: herede de n_pbt_restclient (n_my_api), escriba ue_response en ese descendiente y créelo con create n_my_api.

Cerrar la ventana que lleva el cliente desde uno de sus eventos está permitido: las respuestas que aún esperaban no se entregan.

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

Buenas prácticas #

• Un cliente por API, con su is_base_url y sus cabeceras puestas una vez: el código de las llamadas solo lleva la ruta y el cuerpo.
• El cuerpo se construye con n_pbt_json, nunca por concatenación: una comilla en el nombre de un cliente no rompe nada.
• Pruebe el estado, luego el código negativo: >= 200 y < 300 está bien, >= 400 el servidor dijo que no, < 0 la petición no salió — of_get_last_error() dice por qué.
• El tiempo límite: 30 segundos por defecto; un informe pesado merece más, una comprobación de presencia menos.
• Lo que puede tardar va en asíncrono: una llamada síncrona congela la interfaz hasta la respuesta.
• Una redirección conserva su petición: un 301 o un 302 solo reescribe en GET un POST — un PUT, un PATCH o un DELETE se rehace tal cual, cuerpo incluido; un 303 sigue en GET sin cuerpo. Una Location relativa (?page=2, ../) se resuelve como lo haría un navegador.
• Una redirección hacia otro origen no se lleva nada suyo: ninguna de las cabeceras puestas con of_set_header (token, clave de API) la sigue — solo queda Content-Type. Un origen es un host, un puerto y un esquema: una API http:// redirigida a https:// pierde su token, así que escriba https:// en is_base_url. Las credenciales de Windows (ib_windows_auth) y el certificado de cliente solo se dan al host y al puerto de la petición. Una redirección HTTPS → HTTP se rechaza.
• Pruebe lo que devuelven of_set_header, of_set_bearer y of_set_basic cuando el valor viene de una entrada o de un archivo: un salto de línea, o un carácter más allá del Latin-1 (una cabecera viaja en Latin-1; no para of_set_basic, cuyo par sale en base64), se rechaza (-5) y no se pone nada. Una cabecera rechazada nunca sale a medias.
• Las credenciales de Windows solo salen si usted lo pide: ib_windows_auth = true para una API de intranet con autenticación de Windows, nunca en un cliente que habla con Internet.
• Un cuerpo de texto está limitado a 64 MB, 16 MB en una aplicación de 32 bits: una exportación voluminosa se lee con of_download / of_download_async, que escriben un archivo sin límite.
• Codifique lo que el usuario escribió: la consulta de una URL sale tal como está escrita — un # la corta, un & añade un parámetro, un + se vuelve un espacio. Constrúyala con of_url, o codifique un valor con of_url_encode.
• Nunca credenciales en la URL (https://user:pwd@…): la petición se rechaza (-5); use of_set_basic.
• El User-Agent vale PBToolboxAI/<versión>; of_set_header("User-Agent", …) lo sustituye cuando una API exige el suyo.

← Referencia de componentes · Índice de la guía