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 #

n_pbt_restclient lnv_rest
n_pbt_json lnv_j
long ll_status

lnv_rest = create n_pbt_restclient
lnv_rest.is_base_url = "https://api.example.com"
lnv_rest.of_set_bearer(ls_token)

// Read : the status comes back, the body waits in the object
ll_status = lnv_rest.of_get("/orders/4152")
if ll_status = 200 then ls_customer = lnv_rest.of_json_value("customer")

// Create : the body is built with n_pbt_json, never by hand
lnv_j.of_set_number("order", 4152)
lnv_j.of_set_string("status", "shipped")
ll_status = lnv_rest.of_post("/shipments", lnv_j.of_text())
if ll_status < 0 then MessageBox("API", lnv_rest.is_last_error)

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 durchkam: -5 ungültige URL, -4 Fehlschlag (kein Netz, unbekannter Name, Zeitüberschreitung, TLS; is_last_error sagt welcher), -6 im Demomodus verweigert.

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 #

string ls_body
if lnv_rest.of_get("/orders?status=open") = 200 then
	ls_body = lnv_rest.of_response_text()
	// One value : of_json_value. The whole list : n_pbt_utils.of_json_get_payload and
	// of_json_get_str on each object, or your own parser on ls_body.
end if

Ein Dokument herunterladen #

long ll_status
ll_status = lnv_rest.of_download("/orders/4152/invoice.pdf", "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

Eine API, die mit einem Fehler antwortet #

choose case lnv_rest.of_post("/shipments", ls_body)
	case 200, 201
		// created
	case 401
		MessageBox("API", "Token expired : " + lnv_rest.of_json_value("message"))
	case is < 0
		MessageBox("Network", lnv_rest.is_last_error)
end choose

Asynchron (kein UI-Einfrieren) #

Die synchronen Aufrufe oben blockieren das Skript (die UI bleibt lebendig, aber die Zeile wartet). Die asynchrone API blockiert nicht einmal das Skript: die Anfrage läuft auf einem Arbeitsthread und ihre Antwort kommt später als Ereignis.

Einrichtung — nichts zu verdrahten: die Komponente liefert die Antwort selbst in ue_response. of_open / of_close öffnen und schließen den Client (optional: der erste async-Aufruf öffnet ihn), of_clear_cookies vergisst die zwischen Anfragen gehaltenen Cookies. Intern ruft der Pump der Komponente of_process_events auf, um die Antworten zu leeren — Sie rufen es 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. of_download_async(url, path) lädt in eine Datei, of_upload(url, field, path) lädt eine Datei als multipart/form-data hoch — beide mit Fortschritt. of_cancel(id) stoppt eine laufende Anfrage. Wiederholungen (il_max_retries, il_retry_backoff_ms) bei 429/503/Netzfehler.

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, as_error), ue_progress(al_id, al_done, al_total).

// Async : the UI never freezes, and there is nothing to wire.
ll_id = uo_rest.of_get_async("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(al_id)
END IF

Bewährte Praxis #

• Ein Client pro API, mit einmal gesetzter is_base_url und Headern: der Aufrufcode trägt nur noch Pfad und Körper.
• Der Körper wird mit n_pbt_json gebaut, nie per Verkettung: ein Anführungszeichen in einem Kundennamen zerstört nichts.
• Erst den Status prüfen, dann den negativen Code: >= 200 und < 300 ist gut, >= 400 der Server hat nein gesagt, < 0 die Anfrage ist nicht losgegangen — is_last_error sagt warum.
• Das Timeout: 30 Sekunden standardmäßig; ein schwerer Bericht verdient mehr, ein Health-Check weniger.

← Komponentenreferenz · Inhalt des Handbuchs