restclient — n_pbt_restclient #

← Komponentenreferenz · Inhalt des Handbuchs

Ein HTTPS-Client für PowerBuilder, Version 10 eingeschlossen: GET, POST, PUT, PATCH, DELETE, Header, ein JSON-Körper, ein Datei-Download. Nativ — TLS, Proxy und Dekompression des Systems, und keine CORS-Mauer, weil die Anfrage nicht von einer Seite ausgeht.

▶ Live ansehen — Demoanwendung, Kachel REST client: die Antworten, der Code, der sie holt, und diese Seite nebeneinander (Internetverbindung erforderlich).

Kurzüberblick #

Schnellstart #

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

Jede HTTP-Methode liefert den Status, den der Server gewählt hat — ein 404 ist eine Antwort, kein Fehler — oder einen negativen Code, wenn die Anfrage nicht durchging: -5 ungültige URL oder ungültiger Header, Client-Zertifikat nicht gefunden, -4 Fehlschlag (kein Netz, unbekannter Name, Zeitüberschreitung, TLS, ein Textkörper über 64 MB — 16 MB in einem 32-Bit-Prozess; of_get_last_error() sagt, welcher), -6 im Demomodus abgelehnt. -2 bedeutet, dass der Client nicht angelegt werden konnte. Ein mit create erzeugtes Objekt genügt für synchrone Aufrufe; für die Ereignisse der asynchronen Aufrufe siehe unten „Wo die Events geschrieben werden“.

Warum nativ, und nicht die Seite #

Ein fetch() aus einer Seite der Bibliothek unterliegt CORS: jede API, die kein Access-Control-Allow-Origin sendet, ist ihm verschlossen — und Unternehmens-APIs senden es nicht. Die Anfrage geht daher von der DLL aus, über WinHTTP: das TLS des Systems mit seinen Zertifikaten, der konfigurierte Proxy, gzip. Was Sie verlieren: nichts; was Sie gewinnen: jede API.

Eigenschaften #

Konstanten: METHOD_GET, METHOD_POST, METHOD_PUT, METHOD_PATCH, METHOD_DELETE für of_request.

Methoden #

Beispiele #

Eine Liste lesen und durchgehen #

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

Ein Dokument herunterladen #

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

Eine API, die mit einem Fehler antwortet #

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

Eine Intranet-API mit Windows-Authentifizierung #

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

Eine vom Benutzer eingegebene Suche #

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

Eine durch OAuth2 geschützte API #

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

Eine Liste in einen 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())

Asynchron (ohne die Oberfläche einzufrieren) #

Während eines synchronen Aufrufs ist die Oberfläche bis zur Antwort eingefroren: das Fenster zeichnet sich nicht mehr neu und reagiert nicht mehr auf Klicks. Bei einem kurzen Aufruf ist das folgenlos; für jeden Aufruf, der dauern kann — ein langsamer Server, ein großer Körper, ein unsicheres Netz —, nehmen Sie die asynchrone API: die Anfrage läuft in einem Arbeitsthread, und ihre Antwort kommt später als Ereignis zurück. Synchron und asynchron teilen sich dieselbe Sitzung: das Cookie einer synchronen Anmeldung dient den folgenden asynchronen Aufrufen und umgekehrt; ein synchroner Aufruf wartet nie hinter den asynchronen Anfragen desselben Objekts.

Einrichtung — nichts zu verdrahten: die Komponente liefert die Antwort selbst in ue_response. of_open / of_close öffnen und schließen den Client (optional: die erste Anfrage öffnet ihn), of_clear_cookies vergisst die zwischen Anfragen behaltenen Cookies. Intern ruft eine Pumpe der Komponente of_process_events auf, um die Antworten abzuholen — Sie rufen sie nie auf.

Senden — of_request_async(method, url, body) oder die Kurzformen of_get_async, of_post_async, of_put_async, of_patch_async, of_delete_async liefern sofort eine Anfrage-ID — oder -5 sofort, ohne nachfolgendes Ereignis, für eine ungültige URL oder einen ungültigen Header (of_get_last_error() sagt warum, zum Beispiel „invalid URL: …“). Höchstens sechs Anfragen laufen gleichzeitig; die weiteren warten in einer Warteschlange. of_download_async(url, path) lädt in eine Datei herunter und of_upload(url, field, path) lädt eine Datei als multipart/form-data hoch — beide mit Fortschritt. of_cancel(id) stoppt eine Anfrage. Wiederholungen (il_max_retries, il_retry_backoff_ms) greifen bei 429/503/Netzausfall.

Empfangen — ue_response(al_id, al_status) (den Körper mit of_response_text(al_id) / of_status(al_id) IM Handler lesen), ue_failed(al_id, al_code, as_error), ue_progress(al_id, al_done, al_total). Eine ID gilt nur für das Objekt, das die Anfrage gesendet hat. Ein Laufzeitfehler in einem dieser Ereignisse wird nicht verschluckt: er erreicht das Ereignis SystemError der Anwendung wie jeder Skriptfehler, und die folgenden Antworten werden trotzdem geliefert.

Wo die Events geschrieben werden #

Ein mit create n_pbt_restclient erzeugtes Objekt dient den synchronen Aufrufen sehr gut — das tut der Schnellstart —, aber seine Ereignisse haben kein Skript: PowerBuilder kann ue_response nicht auf ein in einem Skript erzeugtes Objekt schreiben. Für die asynchronen Aufrufe gibt es zwei Wege:

• das in das Fenster eingefügte Objekt (oder das Benutzerobjekt): fügen Sie im Painter ein nichtvisuelles Objekt n_pbt_restclient ein und nennen Sie es inv_rest; seine Ereignisse ue_response, ue_failed und ue_progress werden dann wie die eines Steuerelements geskriptet, und es entsteht und vergeht mit dem Fenster — so macht es die Demoanwendung;
• ein Nachkomme: erben Sie von n_pbt_restclient (n_my_api), schreiben Sie ue_response in diesem Nachkommen und erzeugen Sie ihn mit create n_my_api.

Das Fenster, das den Client trägt, aus einem seiner Ereignisse zu schließen, ist erlaubt: die noch wartenden Antworten werden nicht zugestellt.

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

Bewährte Praxis #

• Ein Client pro API, mit seinem is_base_url und seinen einmal gesetzten Headern: der Aufrufcode trägt nur noch Pfad und Körper.
• Der Körper wird mit n_pbt_json gebaut, nie durch Verkettung: ein Anführungszeichen in einem Kundennamen zerstört nichts.
• Prüfen Sie den Status, dann den negativen Code: >= 200 und < 300 ist gut, >= 400 der Server hat abgelehnt, < 0 die Anfrage ist nicht abgegangen — of_get_last_error() sagt warum.
• Das Zeitlimit: standardmäßig 30 Sekunden; ein schwerer Bericht verdient mehr, eine Erreichbarkeitsprüfung weniger.
• Was dauern kann, läuft asynchron: ein synchroner Aufruf friert die Oberfläche bis zur Antwort ein.
• Eine Umleitung behält Ihre Anfrage: ein 301 oder 302 schreibt nur ein POST in ein GET um — ein PUT, PATCH oder DELETE wird unverändert erneut gesendet, Körper inklusive; ein 303 geht als GET ohne Körper weiter. Eine relative Location (?page=2, ../) wird aufgelöst, wie ein Browser es täte.
• Eine Umleitung auf einen anderen Ursprung nimmt nichts von Ihnen mit: keiner der mit of_set_header gesetzten Header (Token, API-Schlüssel) folgt ihr — nur Content-Type bleibt. Ein Ursprung ist ein Host, ein Port und ein Schema: eine auf https:// umgeleitete http://-API verliert ihr Token, schreiben Sie also https:// in is_base_url. Die Windows-Anmeldedaten (ib_windows_auth) und das Client-Zertifikat erhält nur Host und Port der Anfrage. Eine Umleitung HTTPS → HTTP wird abgelehnt.
• Prüfen Sie die Rückgabe von of_set_header, of_set_bearer und of_set_basic, wenn der Wert aus einer Eingabe oder einer Datei stammt: ein Zeilenumbruch oder ein Zeichen jenseits von Latin-1 (ein Header reist in Latin-1; nicht bei of_set_basic, dessen Paar als Base64 abgeht) wird dort abgelehnt (-5), und nichts wird gesetzt. Ein abgelehnter Header geht nie halb fertig ab.
• Windows-Anmeldedaten gehen nur ab, wenn Sie es verlangen: ib_windows_auth = true für eine Intranet-API mit Windows-Authentifizierung, nie bei einem Client, der mit dem Internet spricht.
• Ein Textkörper ist auf 64 MB begrenzt, 16 MB in einer 32-Bit-Anwendung: ein großer Export wird mit of_download / of_download_async gelesen, die ohne Grenze in eine Datei schreiben.
• Kodieren Sie, was der Benutzer eingegeben hat: die Abfrage einer URL geht so ab, wie sie geschrieben ist — ein # schneidet sie ab, ein & fügt einen Parameter hinzu, ein + wird zum Leerzeichen. Bauen Sie sie mit of_url, oder kodieren Sie einen Wert mit of_url_encode.
• Nie Anmeldedaten in der URL (https://user:pwd@…): die Anfrage wird abgelehnt (-5); nehmen Sie of_set_basic.
• Der User-Agent lautet PBToolboxAI/<Version>; of_set_header("User-Agent", …) ersetzt ihn, wenn eine API Ihren eigenen verlangt.

← Komponentenreferenz · Inhalt des Handbuchs