6.4 KiB

Raw Blame History

WebSockets

Vous pouvez utiliser API WebSockets avec FastAPI.

Installer `websockets`

Vous devez créer un environnement virtuel{.internal-link target=_blank}, l'activer, et installer websockets (une bibliothèque Python qui facilite l'utilisation du protocole « WebSocket ») :

$ pip install websockets

---> 100%

Client WebSocket

En production

Dans votre système de production, vous avez probablement un frontend créé avec un framework moderne comme React, Vue.js ou Angular.

Et pour communiquer en utilisant WebSockets avec votre backend, vous utiliseriez probablement les outils fournis par votre frontend.

Ou vous pouvez avoir une application mobile native qui communique directement avec votre backend WebSocket, en code natif.

Ou vous pouvez avoir toute autre façon de communiquer avec l'endpoint WebSocket.

Mais pour cet exemple, nous utiliserons un document HTML très simple avec un peu de JavaScript, le tout dans une longue chaîne.

Cela, bien entendu, n'est pas optimal et vous ne l'utiliseriez pas en production.

En production, vous auriez l'une des options ci-dessus.

Mais c'est la façon la plus simple de se concentrer sur la partie serveur des WebSockets et d'avoir un exemple fonctionnel :

{* ../../docs_src/websockets_/tutorial001_py310.py hl[2,6:38,41:43] *}

Créer un `websocket`

Dans votre application FastAPI, créez un websocket :

{* ../../docs_src/websockets_/tutorial001_py310.py hl[1,46:47] *}

/// note | Détails techniques

Vous pourriez aussi utiliser from starlette.websockets import WebSocket.

FastAPI fournit le même WebSocket directement, simplement pour vous faciliter la vie en tant que développeur. Mais il provient directement de Starlette.

///

Attendre des messages et envoyer des messages

Dans votre route WebSocket, vous pouvez await des messages et envoyer des messages.

{* ../../docs_src/websockets_/tutorial001_py310.py hl[48:52] *}

Vous pouvez recevoir et envoyer des données binaires, texte et JSON.

Essayer

Si votre fichier s'appelle main.py, exécutez votre application avec :

$ fastapi dev main.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Ouvrez votre navigateur à l'adresse http://127.0.0.1:8000.

Vous verrez une page simple comme :

Vous pouvez saisir des messages dans le champ de saisie et les envoyer :

Et votre application FastAPI avec WebSockets vous répondra :

Vous pouvez envoyer (et recevoir) de nombreux messages :

Et tous utiliseront la même connexion WebSocket.

Utiliser `Depends` et autres

Dans les endpoints WebSocket, vous pouvez importer depuis fastapi et utiliser :

Depends
Security
Cookie
Header
Path
Query

Ils fonctionnent de la même manière que pour les autres endpoints/chemins d'accès FastAPI :

{* ../../docs_src/websockets_/tutorial002_an_py310.py hl[68:69,82] *}

/// info

Comme il s'agit d'un WebSocket, il n'est pas vraiment logique de lever une HTTPException, nous levons plutôt une WebSocketException.

Vous pouvez utiliser un code de fermeture parmi les codes valides définis dans la spécification.

///

Essayez les WebSockets avec des dépendances

Si votre fichier s'appelle main.py, exécutez votre application avec :

$ fastapi dev main.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Ouvrez votre navigateur à l'adresse http://127.0.0.1:8000.

Là, vous pouvez définir :

« Item ID », utilisé dans le chemin.
« Token » utilisé comme paramètre de requête.

/// tip | Astuce

Notez que le token de requête sera géré par une dépendance.

///

Avec cela, vous pouvez connecter le WebSocket puis envoyer et recevoir des messages :

Gérer les déconnexions et plusieurs clients

Lorsqu'une connexion WebSocket est fermée, l'instruction await websocket.receive_text() lèvera une exception WebSocketDisconnect, que vous pouvez ensuite intercepter et gérer comme dans cet exemple.

{* ../../docs_src/websockets_/tutorial003_py310.py hl[79:81] *}

Pour l'essayer :

Ouvrez l'application dans plusieurs onglets du navigateur.
Écrivez des messages depuis ceux-ci.
Puis fermez l'un des onglets.

Cela lèvera l'exception WebSocketDisconnect, et tous les autres clients recevront un message comme :

Client #1596980209979 left the chat

/// tip | Astuce

L'application ci-dessus est un exemple minimal et simple pour montrer comment gérer et diffuser des messages à plusieurs connexions WebSocket.

Mais gardez à l'esprit que, comme tout est géré en mémoire, dans une seule liste, cela ne fonctionnera que tant que le processus s'exécute et uniquement avec un seul processus.

Si vous avez besoin de quelque chose de facile à intégrer avec FastAPI mais plus robuste, pris en charge par Redis, PostgreSQL ou autres, consultez encode/broadcaster.

///

Plus d'informations

Pour en savoir plus sur les options, consultez la documentation de Starlette concernant :

6.4 KiB Raw Blame History