2.2.8. Parametri di query (Query Parameters)
2.2.8. Parametri di query (Query Parameters)
Se la porzione query dell'URI obiettivo di una richiesta usa parametri di modulo HTML nel formato definito nella Sezione 5 ("application/x-www-form-urlencoded") di [HTMLURL], il componente derivato @query-param consente di indirizzare questi singoli parametri di query. I parametri di query DEVONO essere analizzati secondo la Sezione 5.1 ("application/x-www-form-urlencoded parsing") di [HTMLURL], producendo un elenco di tuple (nameString, valueString). Il parametro RICHIESTO name di ciascun identificatore di componente contiene il nameString codificato di un singolo parametro di query come valore String. Il valore del componente di un singolo parametro nominato è il valueString codificato di quel singolo parametro di query. PIÙ parametri di query con nomi diversi POSSONO essere inclusi nei componenti coperti. I singoli parametri nominati POSSONO comparire in qualsiasi ordine nei componenti coperti, indipendentemente dall'ordine nella stringa di query.
Il valore del parametro name e il valore del componente di un singolo parametro nominato sono calcolati tramite il seguente processo:
-
Analizzare il nameString o valueString del parametro di query nominato definito dalla Sezione 5.1 ("application/x-www-form-urlencoded parsing") di [HTMLURL]; questo è il valore dopo la decodifica degli ottetti percent-encoded.
-
Codificare il nameString o valueString usando il processo "percent-encode after encoding" definito dalla Sezione 5.2 ("application/x-www-form-urlencoded serializing") di [HTMLURL]; ciò produce una stringa ASCII [ASCII].
-
Restituire la stringa ASCII.
Si noti che il valore del componente non include caratteri ? iniziali, caratteri = né caratteri & di separazione. I parametri di query nominati con valueString vuoto hanno stringa vuota come valore del componente. Si noti che, a causa di inconsistenze nelle implementazioni, alcune librerie di analisi dei parametri di query eliminano tali valori vuoti.
Se un parametro di query è nominato come componente coperto ma non compare nei parametri di query, ciò DEVE causare un errore nella generazione della base della firma.
Ad esempio, per la seguente richiesta:
GET /path?param=value&foo=bar&baz=batman&qux= HTTP/1.1 Host: www.example.com
Indicare i parametri di query nominati baz, qux e param produrrebbe i seguenti valori del componente @query-param:
baz: batman
qux: una stringa vuota
param: value
e le seguenti righe della base della firma, con (SP) che indica un singolo carattere spazio finale prima del valore di componente vuoto:
"@query-param";name="baz": batman "@query-param";name="qux":(SP) "@query-param";name="param": value
Questo componente derivato ha alcune limitazioni. In particolare, gli algoritmi forniti nella Sezione 5 ("application/x-www-form-urlencoded") di [HTMLURL] supportano solo parametri di query usando codifica UTF-8 con escape percentuale. Altre codifiche non sono supportate. Inoltre, più istanze di un parametro nominato non sono supportate in modo affidabile sul campo. Se un nome di parametro compare più volte in una richiesta, il parametro di query nominato NON DEVE essere incluso. Se parametri multipli sono comuni in un'applicazione, è RACCOMANDATO firmare l'intera stringa di query usando l'identificatore di componente @query definito nella Sezione 2.2.7.
Il processo di codifica consente parametri di query che includono newline o altri caratteri problematici nei loro valori, o con codifiche alternative come l'uso del carattere più (+) per rappresentare spazi. Per i parametri di query in questo messaggio:
NOTA: a capo con '' secondo RFC 8792
GET /parameters?var=this%20is%20a%20big%0Amultiline%20value&
bar=with+plus+whitespace&fa%C3%A7ade%22%3A%20=something HTTP/1.1
Host: www.example.com
Date: Tue, 20 Apr 2021 02:07:56 GMT
I valori risultanti sono codificati come segue:
"@query-param";name="var": this%20is%20a%20big%0Amultiline%20value "@query-param";name="bar": with%20plus%20whitespace "@query-param";name="fa%C3%A7ade%22%3A%20": something
Se la codifica non fosse applicata, i valori risultanti sarebbero:
"@query-param";name="var": this is a big multiline value "@query-param";name="bar": with plus whitespace "@query-param";name="façade": ": something
Questa stringa di base contiene caratteri che violano i vincoli su nomi e valori dei componenti ed è quindi non valida.