Get HTTP

funzione copia link

Scopo

La funzione permette di effettuare una richiesta HTTP verso un server web. Normalmente viene utilizzata per utilizzare una funzionalità messa a disposizione da un altro sito.

Sintassi

string Response = "" // Risposta del server
//
Response := Application.GetHTTP(Url, dati Post, Username, Password)

Argomenti

Url	E' un parametro di tipo stringa che indica l'URL del server da contattare. Se non inizia né per http:// né per https:// il sistema inserisce automaticamente http:// all'inizio.
Dati Post	E' un parametro opzionale di tipo IDMap. Vedi le note per ulteriori dettagli
Username	E' un parametro opzionale di tipo stringa. Se username e password vengono specificati il sistema invia i dati utente (username e password) insieme alla richiesta. Tale parametro è necessario se il server web richiede dati di autenticazione.
Password	E' un parametro opzionale di tipo stringa. Se username e password vengono specificati il sistema invia i dati utente (username e password) insieme alla richiesta. Tale parametro è necessario se il server web richiede dati di autenticazione.

Valore di ritorno

Se la risposta HTTP è di tipo TEXT, ovvero se il ContentType inizia con la stringa "text/", allora la funzione restituisce il testo della risposta come stringa. Se la risposta non è di tipo TEXT il sistema restituisce la risposta come BLOB. In questo caso è possibile utilizzare la funzione SaveBlobFile per estrarre il contenuto della risposta e salvarlo su file. Se l'applicazione non utilizza blob nativi il sistema, utilizzando il ContentType, calcola automaticamente un'estensione per il BLOB.

Esempio di codice

// *********************
// Effettua la richiesta
// *********************
public void Browser.BottoneVai()
{
  IDMap idm = null
  //
  // Faccio la chiamata e salvo la risposta in un file temporaneo
  int fileID = EsempiLB.freeFile()
  string sNomeFile = EsempiLB.path() + "/temp/" + toString(toInteger(random(...) * 1000000)) + ".html"
  EsempiLB.openFileForOutput(sNomeFile, fileID)
  EsempiLB.writeLine(fileID, getHTTP(Dati.Url, idm, Dati.Username, Dati.Password))
  EsempiLB.closeFile(fileID)
  //
  // Aggiungo il file temporaneo all'elenco di quelli dal eliminare a fine sessione
  EsempiLB.addTempFile(sNomeFile)
}

Multi-part

A partire dalla versione 26.5 cambia il modo in cui i parametri della mappa vengono trasmessi quando la richiesta contiene un file. Nessun parametro ID_ è nuovo: ID_POSTFILE, ID_MULTITYPE, ID_BODY e ID_BODYTYPE sono quelli già descritti sopra; è cambiato dove finiscono i valori degli altri parametri, cioè quelli che non iniziano con ID_.

I casi sono tre:

Richiesta multi-part, cioè ID_POSTFILE valorizzato insieme a ID_MULTITYPE oppure a ID_BODY: ogni parametro diventa una parte del messaggio, con la propria intestazione Content-Disposition: form-data; name="...", scritta prima della parte che porta il file. I parametri non vengono più aggiunti all'indirizzo. Fino alla versione 26.4 questi parametri venivano accodati alla query string se era valorizzato ID_BODY, e altrimenti andavano perduti senza alcuna segnalazione.
Richiesta con un file ma non multi-part, cioè ID_POSTFILE valorizzato senza ID_MULTITYPE né ID_BODY: il corpo del messaggio è occupato per intero dal file, quindi i parametri vengono accodati alla query string dell'indirizzo, che è l'unico posto dove possono stare. Fino alla versione 26.4 andavano perduti.
Richiesta senza file: i parametri costituiscono il corpo della richiesta, codificato come application/x-www-form-urlencoded, oppure vengono accodati alla query string dell'indirizzo se il corpo è già occupato da ID_BODY. Questo caso non è cambiato.

Composizione del messaggio multi-part

Il tipo del messaggio è quello indicato da ID_MULTITYPE; se non è specificato il sistema usa multipart/related. Il separatore delle parti (boundary) viene generato dal sistema. Le parti vengono scritte in quest'ordine:

una parte per ogni parametro della mappa che non inizia con ID_, con intestazione Content-Disposition: form-data; name="nome del parametro" e per contenuto il valore del parametro;
se è valorizzato ID_BODY, la parte che porta il corpo, sempre di nome body, che dichiara il tipo indicato da ID_BODYTYPE. Se ID_BODYTYPE non è specificato la parte non dichiara alcun tipo — per la RFC 2046 vale quindi text/plain — e il sistema segnala un avviso;
la parte che porta il file, sempre di nome file, con filename uguale al nome del file indicato da ID_POSTFILE e tipo application/octet-stream.

I nomi body e file sono fissi: è con quelli che il server destinatario deve leggere le due parti. Nei nomi dei parametri e nel nome del file gli a capo vengono tolti, mentre la barra rovescia e l'apice doppio vengono sostituiti con %5C e %22, perché spezzerebbero l'intestazione della parte.

Le parti del messaggio multi-part sono sempre codificate in UTF-8, anche quando ID_BODYTYPE dichiara un charset diverso: vale sia per ID_BODY sia per i parametri, su tutti i canali (server Java, server .NET, Android e iOS). Un ID_BODYTYPE come text/xml; charset=ISO-8859-1 viene riportato nell'intestazione della parte, ma non governa la codifica dei byte spediti.

ID_MULTITYPE senza ID_POSTFILE viene ignorato, perché senza un file da spedire il messaggio multi-part non viene composto; il sistema lo segnala con un avviso.

Esempio di codice

Invio di un file insieme ad alcuni campi, come farebbe la form di un browser:

  IDMap map = new()
  map.setValue("ID_POSTFILE", "PATH DEL FILE")
  map.setValue("ID_MULTITYPE", "multipart/form-data")
  map.setValue("idPratica", "12345")
  map.setValue("descrizione", "Contratto firmato")
  string resp = GetHTTP('URL DEL SERVER', map)

Il messaggio che parte è fatto così:

  Content-Type: multipart/form-data; boundary="<separatore>"

  --<separatore>
  Content-Disposition: form-data; name="idPratica"

  12345
  --<separatore>
  Content-Disposition: form-data; name="descrizione"

  Contratto firmato
  --<separatore>
  Content-Disposition: form-data; name="file"; filename="<nome del file>"
  Content-Type: application/octet-stream

  <contenuto del file>
  --<separatore>--

Limite del client web

Su client web ID_POSTFILE non può essere soddisfatto, perché il browser non è in grado di leggere un percorso del disco, e il messaggio multi-part non viene composto affatto: la richiesta parte senza il file e i parametri seguono le regole del caso 3. Il sistema lo segnala con un avviso nel DTT. Se il file deve partire dal browser occorre farlo spedire dal server, oppure usare l'applicazione nativa.

Se il parametro DatiPost non viene specificato o viene fornito il valore Null il sistema effettua una richiesta di tipo GET. Se, invece, il parametro viene specificato ed è diverso da Null il sistema effettua una richiesta di tipo POST.

Tale comportamento automatico può essere cambiato indicando manualmente il tipo di richiesta da effettuare inserendo un apposita chiave dentro alla mappa. Per esempio se si desidera effettuare una richiesta di questo tipo:

   http://doc.progamma.com/?ARTID=welcome

è possibile scrivere:

   string resp = GetHTTP('doc.progamma.com/?ARTID=welcome')

ma è anche possibile scrivere:

  IDMap map = new()
  map.setValue("ID_TYPE", "GET")
  map.setValue("ARTID", "welcome")
  string resp = GetHTTP('doc.progamma.com', map)

In questo secondo caso è stato inserito un apposito parametro nella mappa, ID_TYPE, per indicare che occorre effettuare una richiesta di tipo GET anche se è stata specificata la mappa. Il sistema, per le richieste di tipo GET, concatena tutti i parametri, eccetto quelli che iniziano con ID_, sull'URL adattandoli per il web se necessario. Se non fosse stato inserito il valore ID_TYPE nella mappa il sistema avrebbe utilizzato una richiesta di tipo POST ed avrebbe inserito il valore ARTID=welcome all'interno della richiesta e non sull'Url.

Il sistema, attualmente, utilizza i seguenti parametri:

ID_TYPE: tale parametro può valere GET o POST e serve al sistema per decidere quale tipo di richiesta effettuare. Come indicato sopra se il valore ID_TYPE non viene fornito e si specifica il parametro DatiPost il sistema utilizza POST.
ID_PROXYURL, ID_PROXYUSERNAME, ID_PROXYPASSWORD: da utilizzare se la richiesta deve essere effettuata utilizzando un server Proxy.
ID_RESPONSETYPE: tale parametro può valere TEXT o BLOB e serve al sistema per decidere come trattare la risposta; se non viene specificato la risposta viene trattata come testo se il ContentLength è =0 oppure se il ContentType inizia per "text/".
ID_HEADERS: questo parametro permette sia di specificare Header aggiuntivi da includere nella richiesta HTTP, sia di leggere gli Header della risposta.
Nel primo caso, può essere utile se il server necessita di Header particolari. Per esempio può essere utile se si desidera specificare lo User-Agent per far credere al server che la richiesta provenga da un browser particolare. Per farlo è sufficiente scrivere:
```
  IDMap map = new()
  map.setValue("ID_TYPE", "GET")
  map.setValue("ID_HEADERS", "User-Agent:Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_1 like Mac OS X; en-us) AppleWebKit/532.9 (KHTML, like Gecko) Version/4.0.5 Mobile/8B117 Safari/6531.22.7")
  string resp = GetHTTP('URL DEL SERVER', map)
```
In questo caso la richiesta viene effettuata facendo credere al server che il client sia un iPhone. Se occorre specificare più di un Header è sufficiente concatenarli e separare i vari header con il carattere ACAPO (\n).
Nel secondo caso è sufficiente scrivere:
```
IDArray headers = map.getObject("ID_HEADERS")
```
È possibile leggere gli Header della risposta solo se è stato specificato il parametro DatiPost perché è l'IDMap passata in tale parametro che conterrà gli Header.

A partire dalla versione 11.5 sono disponibili anche i seguenti parametri:

ID_AUTOPROXY: è possibile utilizzare questo parametro per indicare al sistema che deve utilizzare la propria configurazione del Proxy. Un esempio di implementazione è il seguente:
```
  IDMap map = new()
  map.setValue("ID_AUTOPROXY", "true")
  string resp = GetHTTP('URL DEL SERVER', map)
```
ID_BODY, ID_BODYTYPE: si è aggiunta la possibilità di specificare il BODY di una richiesta POST. ID_BODYTYPE permette di specificare il ContentType del BODY. Un esempio di codice è il seguente:
```
  IDMap map = new()
  map.setValue("ID_BODY", "CONTENUTO_DEL_BODY")
  map.setValue("ID_BODYTYPE", "CONTENTTYPE_DEL_BODY")
  string resp = GetHTTP('URL DEL SERVER', map)
```

A partire dalla versione 12.0 è disponibile anche il seguente parametro:

ID_TIMEOUT: è possibile utilizzare questo parametro per indicare al sistema quanti secondi è necessario attendere prima di annullare il tentativo di connessione. Normalmente viene utilizzato solo se il valore predefinito del sistema (30 secondi in applicazioni web C#/Java, 15 secondi in applicazioni web offline eseguite dentro alla shell nativa) non è quello desiderato. Un esempio di codice è il seguente:
```
  IDMap map = new()
  map.setValue("ID_TIMEOUT", 60)
  string resp = GetHTTP('URL DEL SERVER', map)
```

A partire dalla versione 12.1 sono disponibili anche i seguenti parametri:

ID_POSTFILE: si è aggiunta la possibilità di inviare un file in una richiesta POST. Un esempio di implementazione è il seguente:
```
  IDMap map = new()
  map.setValue("ID_POSTFILE", "PATH DEL FILE")
  string resp = GetHTTP('URL DEL SERVER', map)
```
ID_MULTITYPE: se si è utilizzato il parametro ID_POSTFILE, è possibile utilizzare questo parametro per indicare il content type del file. Normalmente viene utilizzato solo se il valore predefinito (multipart/related) non è quello desiderato. Un esempio di codice è il seguente:
```
  IDMap map = new()
  map.setValue("ID_MULTITYPE", "multipart/form-data")
  string resp = GetHTTP('URL DEL SERVER', map)
```
ID_NOERROR: è possibile utilizzare questo parametro per indicare al sistema che non deve generare errori. Un esempio di implementazione è il seguente:
```
  IDMap map = new()
  map.setValue("ID_NOERROR", -1)
  string resp = GetHTTP('URL DEL SERVER', map)
```
Se si utilizza la chiave ID_NOERROR e le si assegna il valore True il sistema, dopo aver effettuato la richiesta, aggiunge alla mappa DatiPost la chiave ID_RESPONSECODE il cui valore è il codice della risposta HTTP. In questo modo è possibile leggere sia il body che il codice della risposta delle richieste che generano errori (es: 404).
ID_SAVETO: è possibile utilizzare questo parametro per indicare la locazione su disco dove salvare un file ottenuto come risposta. Un esempio di implementazione è il seguente:
```
  IDMap map = new()
  map.setValue("ID_SAVETO", "PATH SUL DISCO DOVE SALVARE IL FILE")
  string resp = GetHTTP('URL DEL SERVER', map)
```

A partire dalla versione 15.5 (rimosso nella versione 21.0) è disponibile anche il seguente parametro:

ID_USETLS1.2: è possibile utilizzare questo parametro per indicare al sistema che la richiesta HTTPS deve essere effettuata utilizzando il protocollo TLS v1.2.
Questo protocollo è disponibile per le applicazioni che usano .NET 4.0 o Java a partire dalla versione 7. Un esempio di codice è il seguente:
```
  IDMap map = new()
  map.setValue("ID_USETLS1.2", true)
  string resp = GetHTTP('URL DEL SERVER', map)
```

A partire dalla versione 21.0 è disponibile anche il seguente parametro:

ID_USEDEFTLS: è possibile utilizzare questo parametro per indicare al sistema che la richiesta HTTPS deve essere effettuata utilizzando il protocollo di sicurezza di default. Se non specificato viene usato TLS 1.2.
Un esempio di codice è il seguente:
```
  IDMap map = new()
  map.setValue("ID_USEDEFTLS", true)
  string resp = GetHTTP('URL DEL SERVER', map)
```

Ultima modifica: 21/09/2026 / Validità: da 10.0.4300