Uso delle diverse classi HTTP e delle loro funzioni
È possibile accedere ai servizi REST mediante le richieste HTTP. Per implementare una richiesta HTTP, è necessario usare un verbo HTTP.
I verbi seguenti sono quelli più usati nei servizi REST:
GET (per leggere dati)
POST (per creare dati)
PUT (per aggiornare/sostituire dati)
PATCH (per aggiornare/modificare dati)
DELETE (per eliminare dati)
Classe HttpClient
La classe HttpClient fornisce una classe base per l'invio di richieste HTTP e la ricezione di risposte HTTP da una risorsa identificata da un URI.
DefaultRequestHeaders(): ottiene le intestazioni di richiesta predefinite che devono essere inviate con ogni richiesta.
SetBaseAddress(Uri): imposta l'indirizzo di base dell'URI usato quando si inviano richieste.
Get(Uri, HttpResponseMessage): invia una richiesta GET per ottenere la risorsa identificata dall'URI della richiesta.
Post(Uri, HttpContent, HttpResponseMessage): invia una richiesta POST all'URI specificato.
Put(Uri, HttpContent, HttpResponseMessage): invia una richiesta PUT all'URI specificato.
Delete(Uri, HttpResponseMessage): invia una richiesta DELETE all'URI specificato.
Send(HttpRequestMessage, HttpResponseMessage): invia una richiesta HTTP. Nella variabile HttpRequestMessage, si deve specificare l'URI e il verbo da usare.
Clear(): imposta la variabile HttpClient sul valore predefinito.
Timeout(): ottiene o imposta il tempo di attesa in secondi prima del timeout della richiesta. Il timeout è un valore intero.
AddCertificate(Certificate, Password): aggiunge un certificato alla classe HttpClient. È necessario fornire un certificato con codifica base64.
UseResponseCookies(UseResponseCookies): quando questa opzione è impostata su true, il client allega automaticamente i cookie ricevuti dalla risposta a tutte le richieste successive.
Quando si specifica un URI, è possibile usare due approcci. Il primo approccio consiste nel richiedere dati dal seguente URL:
https://jsonplaceholder.typicode.com/posts
Dopodiché è possibile usare SetBaseAddress con la classe HttpClient per eseguire più richieste.
var
client: HttpClient;
responseMessage: HttpResponseMessage;
begin
client.SetBaseAddress('https://jsonplaceholder.typicode.com/');
client.Get('posts', responseMessage);
end;
Il secondo approccio è invece usato quando si richiedono i dati una sola volta. In tal caso, è possibile inserire l'URI completo nella funzione Get.
var
client: HttpClient;
responseMessage: HttpResponseMessage;
begin
client.Get('https://jsonplaceholder.typicode.com/posts', responseMessage);
end;
Classe HttpHeaders
La classe HttpHeaders contiene una raccolta di intestazioni e i relativi valori. Le intestazioni HttpHeaders vengono inviate con ogni richiesta e risposta e sono usate per inviare informazioni supplementari sulla richiesta o sul modo in cui la risposta deve essere formattata per il client.
Alcune intestazioni HttpHeaders comuni sono Authorization (usata per inviare credenziali di autenticazione), Content-Type (il tipo di supporto del corpo della richiesta), User-Agent (la stringa dell'agente utente, il nome del browser) e Accept-Charset (i set di caratteri accettabili).
È possibile ottenere intestazioni HttpHeaders usando la proprietà DefaultRequestHeaders della classe HttpClient.
var
client: HttpClient;
headers: HttpHeaders;
content: HttpContent;
responseMessage: HttpResponseMessage;
begin
headers := client.DefaultRequestHeaders();
headers.Add('Content-Type','application-json');
client.Post('https://jsonplaceholder.typicode.com/posts', content,
responseMessage);
end;
Add(Key, Value): imposta il valore specificato per il nome di intestazione fornito.
Clear(): imposta la variabile HttpHeaders sul valore predefinito.
Contains(Key): verifica se una variabile HttpHeaders contiene una proprietà con la chiave specificata.
GetValues(Key, Array of Text): ottiene i valori per la chiave specificata. I valori vengono restituiti nella matrice di testo.
Remove(Key): rimuove la chiave e i valori correlati dall'oggetto HttpHeaders.
Classe HttpResponseMessage
La classe HttpResponseMessage rappresenta un messaggio di risposta HTTP. Un messaggio di risposta è il risultato di un'azione HTTP (Get, Post, Put, Delete). Viene restituito nel parametro HttpResponseMessage.
var
client: HttpClient;
responseMessage: HttpResponseMessage;
begin
client.Get('https://jsonplaceholder.typicode.com/posts', responseMessage);
end;
Content(): ottiene il contenuto (HttpContent) della risposta HTTP.
Headers(): ottiene le intestazioni HTTP della richiesta HTTP.
HttpStatusCode(): ottiene il codice di stato della risposta HTTP.
IsSuccessStatusCode(): ottiene un valore che indica se la risposta HTTP ha avuto esito positivo.
ReasonPhrase(): ottiene la frase per il motivo che è in genere inviata con il codice di stato. È possibile usare questa variabile per fornire informazioni supplementari all'utente quando una richiesta non riesce.
Codici di errore di stato HTTP comuni
Quando viene chiamato un endpoint del servizio Web, si riceve sempre un codice di stato HTTP come parte della risposta. È possibile recuperarlo in AL chiamando la procedura HttpStatusCode(), che fa parte della classe HttpResponseMessage.
I codici di stato possono essere suddivisi in cinque categorie:
1xx: codici informativi. La richiesta è stata ricevuta e il processo continua.
2xx: il server ha ricevuto e accettato correttamente la richiesta. Un codice di stato 200 indica OK, mentre 201 viene spesso usato quando un record è stato creato.
3xx: codici usati per indicare che la risorsa richiesta è stata spostata o reindirizzata in un'altra posizione.
4xx: si è verificato un errore sul lato client. La richiesta contiene un errore. Questo codice può variare da 400 (Richiesta non valida), ad esempio quando si usano dati/struttura JSON errati, 401 (Accesso negato) quando si usano credenziali errate, 403 (Non consentito) a 404 (Non trovato), quando la risorsa non può essere individuata a causa di un errore nell'URL.
5xx: si è verificato un errore sul lato server. Un codice di stato 500 (errore interno del server) indica che il server non è stato in grado di elaborare la richiesta a causa di una condizione imprevista. Un errore 503 indica che il servizio è inattivo e non disponibile.
Il modo più semplice per gestire questi codici di stato consiste nell'usare la procedura IsSuccessStatusCode() su HttpResponseMessage. Viene restituito un valore booleano che specifica se la richiesta ha restituito un errore o meno.
Classe HttpContent
La classe HttpContent rappresenta un corpo HTTP e intestazioni del contenuto. Si usa come corpo per inviare informazioni oppure come corpo della risposta. È possibile usare la proprietà Content nelle classe HttpRequestMessage (con una richiesta) o nella classe HttpResponseMessage (con una risposta).
Clear(): imposta l'oggetto HttpContent su un valore predefinito.
GetHeaders(HttpHeaders): ottiene le intestazioni HTTP del contenuto. Il risultato viene restituito nel parametro HttpHeaders.
ReadAs(Result): legge il contenuto nel testo o nel flusso fornito. Il risultato può essere di tipo Text o InStream.
WriteFrom(Value): imposta la variabile HttpContent sul testo o flusso fornito.
Classe HttpRequestMessage
La classe HttpRequestMessage rappresenta un messaggio di richiesta HTTP. Un messaggio di richiesta è la classe usata per inviare una richiesta.
[Ok := ] HttpClient.Send(HttpRequestMessage, HttpResponseMessage);
Content(): ottiene/imposta il contenuto della richiesta HTTP.
GetRequestUri(): ottiene l'URI usato per la richiesta HTTP.
Method(): ottiene o imposta il tipo di metodo. È necessario specificare un verbo HTTP usato con questa richiesta.
SetRequestUri(RequestUri): imposta l'URI usato per la richiesta HTTP.
var
client: HttpClient;
requestMessage: HttpRequestMessage;
responseMessage: HttpResponseMessage;
begin
requestMessage.Method('GET');
requestMessage.SetRequestUri('https://jsonplaceholder.typicode.com/posts');
client.Send(requestMessage, responseMessage);
end;