La chiave, esercizi spiegati
Cinque esempi, dalla chiave al fornitore che la perde
- 30 minuti di lettura
Cinque esempi, dal più semplice. Dentro ci sono gli stessi pezzi della teoria: la chiave, il .env, l'header, il controllore. Ognuno ha lo stesso ritmo:
- Prevedi: leggi il codice e scrivi su un foglio cosa risponde. Prima di aprire la risposta.
- In italiano: cosa fa il programma, a parole.
- Passo per passo: cosa succede a ogni richiesta.
- Cosa portiamo a casa: la cosa da ricordare.
Per provarli: una cartella nuova per ogni esempio, con il venv acceso e pip install "fastapi[standard]" httpx python-dotenv. Il codice lo salvi in un file; il server si accende con fastapi dev nome_del_file.py e le richieste si lanciano da un secondo terminale con curl. Le chiavi che vedrai tu saranno diverse da queste: la tua si fa con secrets, e non si copia.
A · Fare la chiave, metterla nel .env
Il tabellone di Piazza Query chiederà i ritardi al server della Linea Menta, e il server gli deve dare una chiave. Prima di tutto, la chiave. Poi il posto dove tenerla.
python3 -c "import secrets; print(secrets.token_bytes(16))"
python3 -c "import secrets; print(secrets.token_bytes(16).hex())"
python3 -c "import secrets; print(secrets.token_hex(16))"
python3 -c "import secrets; print(len(secrets.token_hex(16)))"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
b'\x8e\x11\xe6\xf7y5\x05"\xd4\x85\x9d\x01@Mfa'
6c29d3bd3af684114b2630bb9fcd6bd1
e827e537567ccb05485c02f331af8f17
32Ogni riga è diversa dalle altre, e la tua sarà diversa da queste. La prima sono 16 byte grezzi: non si possono scrivere in un file di testo. La seconda li scrive in esadecimale (.hex()): 2 caratteri per byte. La terza fa le due cose insieme. La quarta conta: 32 caratteri.
Adesso la chiave va nel file .env, con il suo nome, e Python la legge da lì:
python3 -c "import secrets; print('CHIAVE_RITARDI=' + secrets.token_hex(16))" > .env
ls
ls -a
cat .envimport os
from dotenv import load_dotenv
print(os.environ.get("CHIAVE_RITARDI"))
load_dotenv()
print(os.environ.get("CHIAVE_RITARDI"))Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
(il primo ls non mostra niente)
.
..
.env
CHIAVE_RITARDI=8e208e36d1e875e4c6257437675fbd31E il programma:
None
8e208e36d1e875e4c6257437675fbd31ls non mostra il file, perché comincia con un punto: ls -a sì. E la chiave arriva nell'ambiente solo dopo load_dotenv(): prima, os.environ.get dà None.
In italiano.
secretstira fuori byte a caso, etoken_hex(16)li scrive come 32 caratteri leggibili.- Il comando di terminale ci attacca davanti
CHIAVE_RITARDI=e scrive la riga nel file.env(il>). - Il programma Python, all'inizio, non sa niente della chiave.
load_dotenv()apre il.enve copia le sue righe nell'ambiente. - Da quel momento
os.environ.get("CHIAVE_RITARDI")dà la chiave.
Passo per passo.
| Riga | Cosa succede | Cosa c'è in os.environ |
|---|---|---|
print(os.environ.get("CHIAVE_RITARDI")) | niente è stato caricato | CHIAVE_RITARDI non c'è: None |
load_dotenv() | legge il .env, riga per riga | ora CHIAVE_RITARDI c'è |
print(os.environ.get("CHIAVE_RITARDI")) | la variabile c'è | la chiave |
Cosa portiamo a casa. La chiave si fa con secrets e si tiene nel .env, non nel codice. Il codice dice solo come si chiama la variabile; il valore sta nel file che resta sul tuo computer.
B · Cosa arriva al parametro
Prima di scrivere il controllore, guardiamo cosa riceve un parametro letto dall'header. Un'API di prova ha tre rotte, che si limitano a rimandare indietro quello che ricevono. Cambia solo la riga del parametro.
from fastapi import FastAPI, Header
app = FastAPI(title="Cosa arriva al parametro")
@app.get("/con-default")
def con_default(chiave: str | None = Header(default=None, alias="X-API-Key")) -> dict:
return {"chiave": chiave}
@app.get("/senza-default")
def senza_default(chiave: str = Header(alias="X-API-Key")) -> dict:
return {"chiave": chiave}
@app.get("/senza-alias")
def senza_alias(chiave: str | None = Header(default=None)) -> dict:
return {"chiave": chiave}Quattro richieste, per ognuna delle tre rotte: con X-API-Key: abc123; senza header; con un header che si chiama chiave: abc123; con l'header X-API-Key presente ma vuoto.
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/con-default -H "X-API-Key: abc123"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/con-default
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/con-default -H "chiave: abc123"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/con-default -H "X-API-Key;"(-H "X-API-Key;", con il punto e virgola, è il modo di curl per mandare un header vuoto.) E lo stesso per /senza-default e /senza-alias.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
/con-default:
{"chiave":"abc123"} → 200
{"chiave":null} → 200
{"chiave":null} → 200
{"chiave":""} → 200/senza-default:
{"chiave":"abc123"} → 200
{"detail":[{"type":"missing","loc":["header","X-API-Key"],"msg":"Field required","input":null}]} → 422
{"detail":[{"type":"missing","loc":["header","X-API-Key"],"msg":"Field required","input":null}]} → 422
{"chiave":""} → 200/senza-alias:
{"chiave":null} → 200
{"chiave":null} → 200
{"chiave":"abc123"} → 200
{"chiave":null} → 200Tre cose da guardare. Su /senza-default, senza header: 422, e il corpo è l'errore di FastAPI, non un tuo messaggio. Su /senza-alias, la chiave arriva solo con l'header che si chiama chiave: senza alias il nome dell'header è quello del parametro. E con l'header vuoto chiave non è None: è la stringa vuota "".
In italiano. FastAPI guarda il parametro. Header(…) gli dice di cercare tra gli header. Il nome che cerca è l'alias, se c'è; altrimenti il nome del parametro. Se l'header non c'è, usa il default; se non c'è nemmeno quello, la richiesta è incompleta e risponde 422 da solo.
Passo per passo.
| Rotta | X-API-Key: abc123 | nessun header | chiave: abc123 | X-API-Key vuoto |
|---|---|---|---|---|
/con-default | "abc123" | None | None | "" |
/senza-default | "abc123" | 422 | 422 | "" |
/senza-alias | None | None | "abc123" | None |
Cosa portiamo a casa. default=None e alias="X-API-Key" servono tutti e due. Senza il primo, il tuo 401 non esce mai (esce un 422). Senza il secondo, il parametro cerca un header che nessuno manda. E None e "" sono due cose diverse: un header vuoto c'è, solo che non dice niente.
C · Il controllore del tabellone
Ora il controllore vero. Il server della Linea Menta dà i ritardi dei treni, e li apre solo al tabellone di Piazza Query, che ha la sua chiave nel .env.
import os
from dotenv import load_dotenv
from fastapi import Depends, FastAPI, Header, HTTPException
load_dotenv()
CHIAVE_RITARDI = os.environ["CHIAVE_RITARDI"]
RITARDI = {"M12": 4, "M14": 0, "M16": 11}
app = FastAPI(title="I ritardi della Linea Menta")
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_RITARDI:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return "Tabellone di Piazza Query"
@app.get("/ritardi")
def leggi_ritardi(cliente: str = Depends(controlla_chiave)) -> dict:
return {"cliente": cliente, "ritardi": RITARDI}Nel .env: CHIAVE_RITARDI=e41b7c09d2a65f38b0c1947ad6e25f83. Cinque richieste: senza header; con l'header vuoto; con la chiave giusta meno l'ultimo carattere; con la chiave giusta; con la chiave giusta tutta in maiuscolo.
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/ritardi
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key;"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: e41b7c09d2a65f38b0c1947ad6e25f8"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: e41b7c09d2a65f38b0c1947ad6e25f83"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: E41B7C09D2A65F38B0C1947AD6E25F83"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"detail":"Manca la chiave"} → 401
{"detail":"Chiave sbagliata"} → 401
{"detail":"Chiave sbagliata"} → 401
{"cliente":"Tabellone di Piazza Query","ritardi":{"M12":4,"M14":0,"M16":11}} → 200
{"detail":"Chiave sbagliata"} → 401Solo la quarta passa. Le due chiavi quasi giuste (una lettera in meno, tutto in maiuscolo) sono sbagliate come quella a caso: un confronto con != è esatto. E l'header vuoto non è «mancante»: è una chiave sbagliata.
In italiano. Prima dell'if, FastAPI ha già letto l'header e messo il suo valore in chiave. Il controllore fa due domande: c'è? è quella giusta? Se una risposta è «no», si ferma con il suo 401. Se passa, restituisce il nome del cliente, e quel nome arriva nel parametro cliente della rotta.
Passo per passo.
| Richiesta | chiave | chiave is None | chiave != CHIAVE_RITARDI | Risposta |
|---|---|---|---|---|
| nessun header | None | sì | non si guarda | 401 Manca la chiave |
| header vuoto | "" | no | sì | 401 Chiave sbagliata |
| una lettera in meno | "e41b…25f8" | no | sì | 401 Chiave sbagliata |
| quella giusta | "e41b…25f83" | no | no | 200, cliente vale "Tabellone di Piazza Query" |
| tutta in maiuscolo | "E41B…25F83" | no | sì | 401 Chiave sbagliata |
Cosa portiamo a casa. Il controllore è una funzione che o ferma (raise) o consegna (return). Le due domande vanno in questo ordine: se non guardi prima None, il confronto con la chiave giusta ti dà un 401 sbagliato per un header che non c'era.
D · Il programma che chiama
Adesso dall'altra parte. Valdora Ricambi ha un programma che ogni notte legge le scorte dal server del magazzino (quello della teoria, acceso). La chiave gliel'ha data il magazzino, a mano: Valdora l'ha messa nel suo .env.
import os
import httpx
from dotenv import load_dotenv
load_dotenv()
CHIAVE = os.environ["CHIAVE_MAGAZZINO"]
risposta = httpx.get("http://127.0.0.1:8000/magazzino", headers={"X-API-Key": CHIAVE})
print(risposta.status_code)
print(risposta.json())Tre notti. La prima, con la chiave giusta nel .env. La seconda, con una chiave sbagliata (un carattere cambiato). La terza, senza il file .env.
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
200
{'fornitore': 'Valdora Ricambi', 'scorte': {'guarnizione-P12': 140, 'fusibile-F5': 62, 'faro-led-M': 9}}401
{'detail': 'Chiave sbagliata'}Traceback (most recent call last):
File "~/fornitore/fornitore.py", line 7, in <module>
CHIAVE = os.environ["CHIAVE_MAGAZZINO"]
~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
File "<frozen os>", line 714, in __getitem__
KeyError: 'CHIAVE_MAGAZZINO'Nella terza il programma non arriva nemmeno a chiamare il server: si ferma alla riga 7, perché la variabile non c'è. Nella seconda, invece, il programma gira bene e chi dice no è il server: il programma stampa il suo 401. (Il percorso del file, nel traceback, sarà quello del tuo computer.)
In italiano.
load_dotenv()carica il.envdi Valdora nell'ambiente.os.environ["CHIAVE_MAGAZZINO"]prende la chiave, con le quadre: se manca, il programma si ferma qui con unKeyError.httpx.get(…)manda la richiesta.headers=è un dizionario: la chiave sta nell'headerX-API-Key, non nell'indirizzo.risposta.status_codeè il codice,risposta.json()il corpo come dizionario Python.
Passo per passo.
| Notte | Il .env di Valdora | Cosa manda il programma | Cosa risponde il server |
|---|---|---|---|
| prima | la chiave giusta | X-API-Key: 6085… | 200 e le scorte |
| seconda | una chiave diversa | X-API-Key: 6085…b | 401 Chiave sbagliata |
| terza | non c'è | niente: il programma si ferma prima | niente |
Cosa portiamo a casa. Il client mette la chiave nell'header, e la prende dall'ambiente, non dal codice. E il 401 che stampa il programma è la risposta del server: leggilo, perché dice «Manca» o «sbagliata».
E · Una chiave per impresa, e una chiave persa
Il calendario delle pulizie dei treni lo leggono tre imprese, ognuna con la sua chiave. L'elenco è un dizionario chiave → impresa.
from fastapi import Depends, FastAPI, Header, HTTPException
# chiave -> impresa. Chiavi finte, per imparare: in un programma vero stanno nel .env o nel database.
CHIAVI = {
"chiave-lucente-3f9a": "Pulizie Lucente",
"chiave-rapida-b71c": "Nettezza Rapida",
"chiave-argento-52de": "Argento Servizi",
}
TURNI = {"M12": "notte", "M14": "mattina", "M16": "notte"}
app = FastAPI(title="Il calendario delle pulizie")
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
impresa = CHIAVI.get(chiave)
if impresa is None:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return impresa
@app.get("/pulizie")
def leggi_pulizie(impresa: str = Depends(controlla_chiave)) -> dict:
return {"impresa": impresa, "turni": TURNI}Nettezza Rapida perde la sua chiave: la lascia su un sedile di un treno. Il magazzino la toglie dall'elenco (cancella la riga "chiave-rapida-b71c": …) e il server riparte. Le tre richieste, con le tre chiavi, prima e dopo:
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-lucente-3f9a"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-rapida-b71c"
curl -s -w " → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-argento-52de"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Prima di togliere la riga:
{"impresa":"Pulizie Lucente","turni":{"M12":"notte","M14":"mattina","M16":"notte"}} → 200
{"impresa":"Nettezza Rapida","turni":{"M12":"notte","M14":"mattina","M16":"notte"}} → 200
{"impresa":"Argento Servizi","turni":{"M12":"notte","M14":"mattina","M16":"notte"}} → 200Dopo:
{"impresa":"Pulizie Lucente","turni":{"M12":"notte","M14":"mattina","M16":"notte"}} → 200
{"detail":"Chiave sbagliata"} → 401
{"impresa":"Argento Servizi","turni":{"M12":"notte","M14":"mattina","M16":"notte"}} → 200Ogni chiave apre come la sua impresa (il return dice chi è). Dopo, la chiave persa non apre più, e le altre due non si sono accorte di niente.
In italiano.
- Il controllore legge l'header e, se manca, 401.
- Cerca la chiave nel dizionario, con
get: l'impresa, oppureNone. - Se è
None, la chiave non è di nessuno: 401. Altrimenti restituisce l'impresa, e la rotta sa chi chiama.
Passo per passo.
| Richiesta | CHIAVI.get(chiave) | Risposta |
|---|---|---|
chiave-lucente-3f9a | "Pulizie Lucente" | 200, impresa è "Pulizie Lucente" |
chiave-rapida-b71c (prima) | "Nettezza Rapida" | 200 |
chiave-rapida-b71c (dopo) | None | 401 Chiave sbagliata |
chiave-argento-52de | "Argento Servizi" | 200 |
Cosa portiamo a casa. Una chiave per programma: chi perde la sua, la si toglie, e gli altri continuano. Con una chiave sola per tutti, avresti dovuto cambiarla e riscriverla in tre programmi. Col get invece delle quadre, una chiave che non c'è dà un 401 e non un errore del server.