[object Object]
3 years ago
committed by
GitHub
GitHub
168 changed files with 6037 additions and 956 deletions
@ -0,0 +1,16 @@ |
|||||
|
version: 2 |
||||
|
updates: |
||||
|
# GitHub Actions |
||||
|
- package-ecosystem: "github-actions" |
||||
|
directory: "/" |
||||
|
schedule: |
||||
|
interval: "daily" |
||||
|
commit-message: |
||||
|
prefix: ⬆ |
||||
|
# Python |
||||
|
- package-ecosystem: "pip" |
||||
|
directory: "/" |
||||
|
schedule: |
||||
|
interval: "daily" |
||||
|
commit-message: |
||||
|
prefix: ⬆ |
||||
|
After Width: | Height: | Size: 199 KiB |
|
After Width: | Height: | Size: 163 KiB |
|
After Width: | Height: | Size: 169 KiB |
|
After Width: | Height: | Size: 160 KiB |
|
After Width: | Height: | Size: 156 KiB |
|
After Width: | Height: | Size: 161 KiB |
|
After Width: | Height: | Size: 166 KiB |
|
After Width: | Height: | Size: 221 KiB |
|
After Width: | Height: | Size: 199 KiB |
|
After Width: | Height: | Size: 165 KiB |
|
After Width: | Height: | Size: 214 KiB |
|
After Width: | Height: | Size: 181 KiB |
|
After Width: | Height: | Size: 153 KiB |
|
After Width: | Height: | Size: 107 KiB |
|
After Width: | Height: | Size: 127 KiB |
|
After Width: | Height: | Size: 52 KiB |
|
After Width: | Height: | Size: 91 KiB |
|
After Width: | Height: | Size: 105 KiB |
|
After Width: | Height: | Size: 106 KiB |
|
After Width: | Height: | Size: 14 KiB |
|
After Width: | Height: | Size: 26 KiB |
|
After Width: | Height: | Size: 159 KiB |
|
After Width: | Height: | Size: 106 KiB |
|
After Width: | Height: | Size: 34 KiB |
@ -0,0 +1,28 @@ |
|||||
|
# Déploiement - Intro |
||||
|
|
||||
|
Le déploiement d'une application **FastAPI** est relativement simple. |
||||
|
|
||||
|
## Que signifie le déploiement |
||||
|
|
||||
|
**Déployer** une application signifie effectuer les étapes nécessaires pour la rendre **disponible pour les |
||||
|
utilisateurs**. |
||||
|
|
||||
|
Pour une **API Web**, cela implique normalement de la placer sur une **machine distante**, avec un **programme serveur** |
||||
|
qui offre de bonnes performances, une bonne stabilité, _etc._, afin que vos **utilisateurs** puissent **accéder** à |
||||
|
l'application efficacement et sans interruption ni problème. |
||||
|
|
||||
|
Ceci contraste avec les étapes de **développement**, où vous êtes constamment en train de modifier le code, de le casser |
||||
|
et de le réparer, d'arrêter et de redémarrer le serveur de développement, _etc._ |
||||
|
|
||||
|
## Stratégies de déploiement |
||||
|
|
||||
|
Il existe plusieurs façons de procéder, en fonction de votre cas d'utilisation spécifique et des outils que vous |
||||
|
utilisez. |
||||
|
|
||||
|
Vous pouvez **déployer un serveur** vous-même en utilisant une combinaison d'outils, vous pouvez utiliser un **service |
||||
|
cloud** qui fait une partie du travail pour vous, ou encore d'autres options possibles. |
||||
|
|
||||
|
Je vais vous montrer certains des principaux concepts que vous devriez probablement avoir à l'esprit lors du déploiement |
||||
|
d'une application **FastAPI** (bien que la plupart de ces concepts s'appliquent à tout autre type d'application web). |
||||
|
|
||||
|
Vous verrez plus de détails à avoir en tête et certaines des techniques pour le faire dans les sections suivantes. ✨ |
||||
@ -0,0 +1,79 @@ |
|||||
|
# Histoire, conception et avenir |
||||
|
|
||||
|
Il y a quelque temps, <a href="https://github.com/tiangolo/fastapi/issues/3#issuecomment-454956920" class="external-link" target="_blank">un utilisateur de **FastAPI** a demandé</a> : |
||||
|
|
||||
|
> Quelle est l'histoire de ce projet ? Il semble être sorti de nulle part et est devenu génial en quelques semaines [...]. |
||||
|
|
||||
|
Voici un petit bout de cette histoire. |
||||
|
|
||||
|
## Alternatives |
||||
|
|
||||
|
Je crée des API avec des exigences complexes depuis plusieurs années (Machine Learning, systèmes distribués, jobs asynchrones, bases de données NoSQL, etc), en dirigeant plusieurs équipes de développeurs. |
||||
|
|
||||
|
Dans ce cadre, j'ai dû étudier, tester et utiliser de nombreuses alternatives. |
||||
|
|
||||
|
L'histoire de **FastAPI** est en grande partie l'histoire de ses prédécesseurs. |
||||
|
|
||||
|
Comme dit dans la section [Alternatives](alternatives.md){.internal-link target=\_blank} : |
||||
|
|
||||
|
<blockquote markdown="1"> |
||||
|
|
||||
|
**FastAPI** n'existerait pas sans le travail antérieur d'autres personnes. |
||||
|
|
||||
|
Il y a eu de nombreux outils créés auparavant qui ont contribué à inspirer sa création. |
||||
|
|
||||
|
J'ai évité la création d'un nouveau framework pendant plusieurs années. J'ai d'abord essayé de résoudre toutes les fonctionnalités couvertes par **FastAPI** en utilisant de nombreux frameworks, plug-ins et outils différents. |
||||
|
|
||||
|
Mais à un moment donné, il n'y avait pas d'autre option que de créer quelque chose qui offre toutes ces fonctionnalités, en prenant les meilleures idées des outils précédents, et en les combinant de la meilleure façon possible, en utilisant des fonctionnalités du langage qui n'étaient même pas disponibles auparavant (annotations de type pour Python 3.6+). |
||||
|
|
||||
|
</blockquote> |
||||
|
|
||||
|
## Recherche |
||||
|
|
||||
|
En utilisant toutes les alternatives précédentes, j'ai eu la chance d'apprendre de toutes, de prendre des idées, et de les combiner de la meilleure façon que j'ai pu trouver pour moi-même et les équipes de développeurs avec lesquelles j'ai travaillé. |
||||
|
|
||||
|
Par exemple, il était clair que l'idéal était de se baser sur les annotations de type Python standard. |
||||
|
|
||||
|
De plus, la meilleure approche était d'utiliser des normes déjà existantes. |
||||
|
|
||||
|
Ainsi, avant même de commencer à coder **FastAPI**, j'ai passé plusieurs mois à étudier les spécifications d'OpenAPI, JSON Schema, OAuth2, etc. Comprendre leurs relations, leurs similarités et leurs différences. |
||||
|
|
||||
|
## Conception |
||||
|
|
||||
|
Ensuite, j'ai passé du temps à concevoir l'"API" de développeur que je voulais avoir en tant qu'utilisateur (en tant que développeur utilisant FastAPI). |
||||
|
|
||||
|
J'ai testé plusieurs idées dans les éditeurs Python les plus populaires : PyCharm, VS Code, les éditeurs basés sur Jedi. |
||||
|
|
||||
|
D'après la dernière <a href="https://www.jetbrains.com/research/python-developers-survey-2018/#development-tools" class="external-link" target="_blank">Enquête Développeurs Python</a>, cela couvre environ 80% des utilisateurs. |
||||
|
|
||||
|
Cela signifie que **FastAPI** a été spécifiquement testé avec les éditeurs utilisés par 80% des développeurs Python. Et comme la plupart des autres éditeurs ont tendance à fonctionner de façon similaire, tous ses avantages devraient fonctionner pour pratiquement tous les éditeurs. |
||||
|
|
||||
|
Ainsi, j'ai pu trouver les meilleurs moyens de réduire autant que possible la duplication du code, d'avoir la complétion partout, les contrôles de type et d'erreur, etc. |
||||
|
|
||||
|
Le tout de manière à offrir la meilleure expérience de développement à tous les développeurs. |
||||
|
|
||||
|
## Exigences |
||||
|
|
||||
|
Après avoir testé plusieurs alternatives, j'ai décidé que j'allais utiliser <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">**Pydantic**</a> pour ses avantages. |
||||
|
|
||||
|
J'y ai ensuite contribué, pour le rendre entièrement compatible avec JSON Schema, pour supporter différentes manières de définir les déclarations de contraintes, et pour améliorer le support des éditeurs (vérifications de type, autocomplétion) sur la base des tests effectués dans plusieurs éditeurs. |
||||
|
|
||||
|
Pendant le développement, j'ai également contribué à <a href="https://www.starlette.io/" class="external-link" target="_blank">**Starlette**</a>, l'autre exigence clé. |
||||
|
|
||||
|
## Développement |
||||
|
|
||||
|
Au moment où j'ai commencé à créer **FastAPI** lui-même, la plupart des pièces étaient déjà en place, la conception était définie, les exigences et les outils étaient prêts, et la connaissance des normes et des spécifications était claire et fraîche. |
||||
|
|
||||
|
## Futur |
||||
|
|
||||
|
À ce stade, il est déjà clair que **FastAPI** et ses idées sont utiles pour de nombreuses personnes. |
||||
|
|
||||
|
Elle a été préférée aux solutions précédentes parce qu'elle convient mieux à de nombreux cas d'utilisation. |
||||
|
|
||||
|
De nombreux développeurs et équipes dépendent déjà de **FastAPI** pour leurs projets (y compris moi et mon équipe). |
||||
|
|
||||
|
Mais il y a encore de nombreuses améliorations et fonctionnalités à venir. |
||||
|
|
||||
|
**FastAPI** a un grand avenir devant lui. |
||||
|
|
||||
|
Et [votre aide](help-fastapi.md){.internal-link target=\_blank} est grandement appréciée. |
||||
@ -0,0 +1,464 @@ |
|||||
|
<p align="center"> |
||||
|
<a href="https://fastapi.tiangolo.com"><img src="https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png" alt="FastAPI"></a> |
||||
|
</p> |
||||
|
<p align="center"> |
||||
|
<em>תשתית FastAPI, ביצועים גבוהים, קלה ללמידה, מהירה לתכנות, מוכנה לסביבת ייצור</em> |
||||
|
</p> |
||||
|
<p align="center"> |
||||
|
<a href="https://github.com/tiangolo/fastapi/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster" target="_blank"> |
||||
|
<img src="https://github.com/tiangolo/fastapi/workflows/Test/badge.svg?event=push&branch=master" alt="Test"> |
||||
|
</a> |
||||
|
<a href="https://codecov.io/gh/tiangolo/fastapi" target="_blank"> |
||||
|
<img src="https://img.shields.io/codecov/c/github/tiangolo/fastapi?color=%2334D058" alt="Coverage"> |
||||
|
</a> |
||||
|
<a href="https://pypi.org/project/fastapi" target="_blank"> |
||||
|
<img src="https://img.shields.io/pypi/v/fastapi?color=%2334D058&label=pypi%20package" alt="Package version"> |
||||
|
</a> |
||||
|
<a href="https://pypi.org/project/fastapi" target="_blank"> |
||||
|
<img src="https://img.shields.io/pypi/pyversions/fastapi.svg?color=%2334D058" alt="Supported Python versions"> |
||||
|
</a> |
||||
|
</p> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
**תיעוד**: <a href="https://fastapi.tiangolo.com" target="_blank">https://fastapi.tiangolo.com</a> |
||||
|
|
||||
|
**קוד**: <a href="https://github.com/tiangolo/fastapi" target="_blank">https://github.com/tiangolo/fastapi</a> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
FastAPI היא תשתית רשת מודרנית ומהירה (ביצועים גבוהים) לבניית ממשקי תכנות יישומים (API) עם פייתון 3.6+ בהתבסס על רמזי טיפוסים סטנדרטיים. |
||||
|
|
||||
|
תכונות המפתח הן: |
||||
|
|
||||
|
- **מהירה**: ביצועים גבוהים מאוד, בקנה אחד עם NodeJS ו - Go (תודות ל - Starlette ו - Pydantic). [אחת מתשתיות הפייתון המהירות ביותר](#performance). |
||||
|
|
||||
|
- **מהירה לתכנות**: הגבירו את מהירות פיתוח התכונות החדשות בכ - %200 עד %300. \* |
||||
|
- **פחות שגיאות**: מנעו כ - %40 משגיאות אנוש (מפתחים). \* |
||||
|
- **אינטואיטיבית**: תמיכת עורך מעולה. <abbr title="ידועה גם כהשלמה אוטומטית או IntelliSense">השלמה</abbr> בכל מקום. פחות זמן ניפוי שגיאות. |
||||
|
- **קלה**: מתוכננת להיות קלה לשימוש וללמידה. פחות זמן קריאת תיעוד. |
||||
|
- **קצרה**: מזערו שכפול קוד. מספר תכונות מכל הכרזת פרמטר. פחות שגיאות. |
||||
|
- **חסונה**: קבלו קוד מוכן לסביבת ייצור. עם תיעוד אינטרקטיבי אוטומטי. |
||||
|
- **מבוססת סטנדרטים**: מבוססת על (ותואמת לחלוטין ל -) הסטדנרטים הפתוחים לממשקי תכנות יישומים: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> (ידועים לשעבר כ - Swagger) ו - <a href="https://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>. |
||||
|
|
||||
|
<small>\* הערכה מבוססת על בדיקות של צוות פיתוח פנימי שבונה אפליקציות בסביבת ייצור.</small> |
||||
|
|
||||
|
## נותני חסות |
||||
|
|
||||
|
<!-- sponsors --> |
||||
|
|
||||
|
{% if sponsors %} |
||||
|
{% for sponsor in sponsors.gold -%} |
||||
|
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
||||
|
{% endfor -%} |
||||
|
{%- for sponsor in sponsors.silver -%} |
||||
|
<a href="{{ sponsor.url }}" target="_blank" title="{{ sponsor.title }}"><img src="{{ sponsor.img }}" style="border-radius:15px"></a> |
||||
|
{% endfor %} |
||||
|
{% endif %} |
||||
|
|
||||
|
<!-- /sponsors --> |
||||
|
|
||||
|
<a href="https://fastapi.tiangolo.com/fastapi-people/#sponsors" class="external-link" target="_blank">נותני חסות אחרים</a> |
||||
|
|
||||
|
## דעות |
||||
|
|
||||
|
"_[...] I'm using **FastAPI** a ton these days. [...] I'm actually planning to use it for all of my team's **ML services at Microsoft**. Some of them are getting integrated into the core **Windows** product and some **Office** products._" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Kabir Khan - <strong>Microsoft</strong> <a href="https://github.com/tiangolo/fastapi/pull/26" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
"_We adopted the **FastAPI** library to spawn a **REST** server that can be queried to obtain **predictions**. [for Ludwig]_" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala - <strong>Uber</strong> <a href="https://eng.uber.com/ludwig-v0-2/" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
"_**Netflix** is pleased to announce the open-source release of our **crisis management** orchestration framework: **Dispatch**! [built with **FastAPI**]_" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Kevin Glisson, Marc Vilanova, Forest Monsen - <strong>Netflix</strong> <a href="https://netflixtechblog.com/introducing-dispatch-da4b8a2a8072" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
"_I’m over the moon excited about **FastAPI**. It’s so fun!_" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Brian Okken - <strong><a href="https://pythonbytes.fm/episodes/show/123/time-to-right-the-py-wrongs?time_in_sec=855" target="_blank">Python Bytes</a> podcast host</strong> <a href="https://twitter.com/brianokken/status/1112220079972728832" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
"_Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted **Hug** to be - it's really inspiring to see someone build that._" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Timothy Crosley - <strong><a href="https://www.hug.rest/" target="_blank">Hug</a> creator</strong> <a href="https://news.ycombinator.com/item?id=19455465" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
"_If you're looking to learn one **modern framework** for building REST APIs, check out **FastAPI** [...] It's fast, easy to use and easy to learn [...]_" |
||||
|
|
||||
|
"_We've switched over to **FastAPI** for our **APIs** [...] I think you'll like it [...]_" |
||||
|
|
||||
|
<div style="text-align: right; margin-right: 10%;">Ines Montani - Matthew Honnibal - <strong><a href="https://explosion.ai" target="_blank">Explosion AI</a> founders - <a href="https://spacy.io" target="_blank">spaCy</a> creators</strong> <a href="https://twitter.com/_inesmontani/status/1144173225322143744" target="_blank"><small>(ref)</small></a> - <a href="https://twitter.com/honnibal/status/1144031421859655680" target="_blank"><small>(ref)</small></a></div> |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## **Typer**, ה - FastAPI של ממשקי שורת פקודה (CLI). |
||||
|
|
||||
|
<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a> |
||||
|
|
||||
|
אם אתם בונים אפליקציית <abbr title="ממשק שורת פקודה">CLI</abbr> לשימוש במסוף במקום ממשק רשת, העיפו מבט על <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>. |
||||
|
|
||||
|
**Typer** היא אחותה הקטנה של FastAPI. ומטרתה היא להיות ה - **FastAPI של ממשקי שורת פקודה**. ⌨️ 🚀 |
||||
|
|
||||
|
## תלויות |
||||
|
|
||||
|
פייתון 3.6+ |
||||
|
|
||||
|
FastAPI עומדת על כתפי ענקיות: |
||||
|
|
||||
|
- <a href="https://www.starlette.io/" class="external-link" target="_blank">Starlette</a> לחלקי הרשת. |
||||
|
- <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> לחלקי המידע. |
||||
|
|
||||
|
## התקנה |
||||
|
|
||||
|
<div dir="ltr" class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install fastapi |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
תצטרכו גם שרת ASGI כגון <a href="https://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> או <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>. |
||||
|
|
||||
|
<div dir="ltr" class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install "uvicorn[standard]" |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
## דוגמא |
||||
|
|
||||
|
### צרו אותה |
||||
|
|
||||
|
- צרו קובץ בשם `main.py` עם: |
||||
|
|
||||
|
```Python |
||||
|
from typing import Union |
||||
|
|
||||
|
from fastapi import FastAPI |
||||
|
|
||||
|
app = FastAPI() |
||||
|
|
||||
|
|
||||
|
@app.get("/") |
||||
|
def read_root(): |
||||
|
return {"Hello": "World"} |
||||
|
|
||||
|
|
||||
|
@app.get("/items/{item_id}") |
||||
|
def read_item(item_id: int, q: Union[str, None] = None): |
||||
|
return {"item_id": item_id, "q": q} |
||||
|
``` |
||||
|
|
||||
|
<details markdown="1"> |
||||
|
<summary>או השתמשו ב - <code>async def</code>...</summary> |
||||
|
|
||||
|
אם הקוד שלכם משתמש ב - `async` / `await`, השתמשו ב - `async def`: |
||||
|
|
||||
|
```Python hl_lines="9 14" |
||||
|
from typing import Union |
||||
|
|
||||
|
from fastapi import FastAPI |
||||
|
|
||||
|
app = FastAPI() |
||||
|
|
||||
|
|
||||
|
@app.get("/") |
||||
|
async def read_root(): |
||||
|
return {"Hello": "World"} |
||||
|
|
||||
|
|
||||
|
@app.get("/items/{item_id}") |
||||
|
async def read_item(item_id: int, q: Union[str, None] = None): |
||||
|
return {"item_id": item_id, "q": q} |
||||
|
``` |
||||
|
|
||||
|
**שימו לב**: |
||||
|
|
||||
|
אם אינכם יודעים, בדקו את פרק "ממהרים?" על <a href="https://fastapi.tiangolo.com/async/#in-a-hurry" target="_blank">`async` ו - `await` בתיעוד</a>. |
||||
|
|
||||
|
</details> |
||||
|
|
||||
|
### הריצו אותה |
||||
|
|
||||
|
התחילו את השרת עם: |
||||
|
|
||||
|
<div dir="ltr" class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ uvicorn main:app --reload |
||||
|
|
||||
|
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
||||
|
INFO: Started reloader process [28720] |
||||
|
INFO: Started server process [28722] |
||||
|
INFO: Waiting for application startup. |
||||
|
INFO: Application startup complete. |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
<details markdown="1"> |
||||
|
<summary>על הפקודה <code>uvicorn main:app --reload</code>...</summary> |
||||
|
|
||||
|
הפקודה `uvicorn main:app` מתייחסת ל: |
||||
|
|
||||
|
- `main`: הקובץ `main.py` (מודול פייתון). |
||||
|
- `app`: האובייקט שנוצר בתוך `main.py` עם השורה <code dir="ltr">app = FastAPI()</code>. |
||||
|
- <code dir="ltr">--reload</code>: גרמו לשרת להתאתחל לאחר שינויים בקוד. עשו זאת רק בסביבת פיתוח. |
||||
|
|
||||
|
</details> |
||||
|
|
||||
|
### בדקו אותה |
||||
|
|
||||
|
פתחו את הדפדפן שלכם בכתובת <a href="http://127.0.0.1:8000/items/5?q=somequery" class="external-link" target="_blank">http://127.0.0.1:8000/items/5?q=somequery</a>. |
||||
|
|
||||
|
אתם תראו תגובת JSON: |
||||
|
|
||||
|
```JSON |
||||
|
{"item_id": 5, "q": "somequery"} |
||||
|
``` |
||||
|
|
||||
|
כבר יצרתם API ש: |
||||
|
|
||||
|
- מקבל בקשות HTTP בנתיבים `/` ו - <code dir="ltr">/items/{item_id}</code>. |
||||
|
- שני ה _נתיבים_ מקבלים _בקשות_ `GET` (ידועות גם כ*מתודות* HTTP). |
||||
|
- ה _נתיב_ <code dir="ltr">/items/{item_id}</code> כולל \*פרמטר נתיב\_ `item_id` שאמור להיות `int`. |
||||
|
- ה _נתיב_ <code dir="ltr">/items/{item_id}</code> \*פרמטר שאילתא\_ אופציונלי `q`. |
||||
|
|
||||
|
### תיעוד API אינטרקטיבי |
||||
|
|
||||
|
כעת פנו לכתובת <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
||||
|
|
||||
|
אתם תראו את התיעוד האוטומטי (מסופק על ידי <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank">Swagger UI</a>): |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### תיעוד אלטרנטיבי |
||||
|
|
||||
|
כעת פנו לכתובת <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
||||
|
|
||||
|
אתם תראו תיעוד אלטרנטיבי (מסופק על ידי <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank">ReDoc</a>): |
||||
|
|
||||
|
 |
||||
|
|
||||
|
## שדרוג לדוגמא |
||||
|
|
||||
|
כעת ערכו את הקובץ `main.py` כך שיוכל לקבל גוף מבקשת `PUT`. |
||||
|
|
||||
|
הגדירו את הגוף בעזרת רמזי טיפוסים סטנדרטיים, הודות ל - `Pydantic`. |
||||
|
|
||||
|
```Python hl_lines="4 9-12 25-27" |
||||
|
from typing import Union |
||||
|
|
||||
|
from fastapi import FastAPI |
||||
|
from pydantic import BaseModel |
||||
|
|
||||
|
app = FastAPI() |
||||
|
|
||||
|
|
||||
|
class Item(BaseModel): |
||||
|
name: str |
||||
|
price: float |
||||
|
is_offer: Union[bool, None] = None |
||||
|
|
||||
|
|
||||
|
@app.get("/") |
||||
|
def read_root(): |
||||
|
return {"Hello": "World"} |
||||
|
|
||||
|
|
||||
|
@app.get("/items/{item_id}") |
||||
|
def read_item(item_id: int, q: Union[str, None] = None): |
||||
|
return {"item_id": item_id, "q": q} |
||||
|
|
||||
|
|
||||
|
@app.put("/items/{item_id}") |
||||
|
def update_item(item_id: int, item: Item): |
||||
|
return {"item_name": item.name, "item_id": item_id} |
||||
|
``` |
||||
|
|
||||
|
השרת אמול להתאתחל אוטומטית (מאחר והוספתם <code dir="ltr">--reload</code> לפקודת `uvicorn` שלמעלה). |
||||
|
|
||||
|
### שדרוג התיעוד האינטרקטיבי |
||||
|
|
||||
|
כעת פנו לכתובת <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>. |
||||
|
|
||||
|
- התיעוד האוטומטי יתעדכן, כולל הגוף החדש: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
- לחצו על הכפתור "Try it out", הוא יאפשר לכם למלא את הפרמטרים ולעבוד ישירות מול ה - API. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
- אחר כך לחצו על הכפתור "Execute", האתר יתקשר עם ה - API שלכם, ישלח את הפרמטרים, ישיג את התוצאות ואז יראה אותן על המסך: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### שדרוג התיעוד האלטרנטיבי |
||||
|
|
||||
|
כעת פנו לכתובת <a href="http://127.0.0.1:8000/redoc" class="external-link" target="_blank">http://127.0.0.1:8000/redoc</a>. |
||||
|
|
||||
|
- התיעוד האלטרנטיבי גם יראה את פרמטר השאילתא והגוף החדשים. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### סיכום |
||||
|
|
||||
|
לסיכום, אתם מכריזים ** פעם אחת** על טיפוסי הפרמטרים, גוף וכו' כפרמטרים לפונקציה. |
||||
|
|
||||
|
אתם עושים את זה עם טיפוסי פייתון מודרניים. |
||||
|
|
||||
|
אתם לא צריכים ללמוד תחביר חדש, מתודות או מחלקות של ספרייה ספיציפית, וכו' |
||||
|
|
||||
|
רק **פייתון 3.6+** סטנדרטי. |
||||
|
|
||||
|
לדוגמא, ל - `int`: |
||||
|
|
||||
|
```Python |
||||
|
item_id: int |
||||
|
``` |
||||
|
|
||||
|
או למודל `Item` מורכב יותר: |
||||
|
|
||||
|
```Python |
||||
|
item: Item |
||||
|
``` |
||||
|
|
||||
|
...ועם הכרזת הטיפוס האחת הזו אתם מקבלים: |
||||
|
|
||||
|
- תמיכת עורך, כולל: |
||||
|
- השלמות. |
||||
|
- בדיקת טיפוסים. |
||||
|
- אימות מידע: |
||||
|
- שגיאות ברורות ואטומטיות כאשר מוכנס מידע לא חוקי . |
||||
|
- אימות אפילו לאובייקטי JSON מקוננים. |
||||
|
- <abbr title="ידועה גם כ: פרסור, סיריאליזציה">המרה</abbr> של מידע קלט: המרה של מידע שמגיע מהרשת למידע וטיפוסים של פייתון. קורא מ: |
||||
|
- JSON. |
||||
|
- פרמטרי נתיב. |
||||
|
- פרמטרי שאילתא. |
||||
|
- עוגיות. |
||||
|
- כותרות. |
||||
|
- טפסים. |
||||
|
- קבצים. |
||||
|
- <abbr title="ידועה גם כ: פרסור, סיריאליזציה">המרה</abbr> של מידע פלט: המרה של מידע וטיפוסים מפייתון למידע רשת (כ - JSON): |
||||
|
- המירו טיפוסי פייתון (`str`, `int`, `float`, `bool`, `list`, etc). |
||||
|
- עצמי `datetime`. |
||||
|
- עצמי `UUID`. |
||||
|
- מודלי בסיסי נתונים. |
||||
|
- ...ורבים אחרים. |
||||
|
- תיעוד API אוטומטי ואינטרקטיבית כולל שתי אלטרנטיבות לממשק המשתמש: |
||||
|
- Swagger UI. |
||||
|
- ReDoc. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
בחזרה לדוגמאת הקוד הקודמת, **FastAPI** ידאג: |
||||
|
|
||||
|
- לאמת שיש `item_id` בנתיב בבקשות `GET` ו - `PUT`. |
||||
|
- לאמת שה - `item_id` הוא מטיפוס `int` בבקשות `GET` ו - `PUT`. |
||||
|
- אם הוא לא, הלקוח יראה שגיאה ברורה ושימושית. |
||||
|
- לבדוק האם קיים פרמטר שאילתא בשם `q` (קרי `http://127.0.0.1:8000/items/foo?q=somequery`) לבקשות `GET`. |
||||
|
- מאחר והפרמטר `q` מוגדר עם <code dir="ltr"> = None</code>, הוא אופציונלי. |
||||
|
- לולא ה - `None` הוא היה חובה (כמו הגוף במקרה של `PUT`). |
||||
|
- לבקשות `PUT` לנתיב <code dir="ltr">/items/{item_id}</code>, לקרוא את גוף הבקשה כ - JSON: |
||||
|
- לאמת שהוא כולל את מאפיין החובה `name` שאמור להיות מטיפוס `str`. |
||||
|
- לאמת שהוא כולל את מאפיין החובה `price` שחייב להיות מטיפוס `float`. |
||||
|
- לבדוק האם הוא כולל את מאפיין הרשות `is_offer` שאמור להיות מטיפוס `bool`, אם הוא נמצא. |
||||
|
- כל זה יעבוד גם לאובייקט JSON מקונן. |
||||
|
- להמיר מ - JSON ול- JSON אוטומטית. |
||||
|
- לתעד הכל באמצעות OpenAPI, תיעוד שבו יוכלו להשתמש: |
||||
|
- מערכות תיעוד אינטרקטיביות. |
||||
|
- מערכות ייצור קוד אוטומטיות, להרבה שפות. |
||||
|
- לספק ישירות שתי מערכות תיעוד רשתיות. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
רק גרדנו את קצה הקרחון, אבל כבר יש לכם רעיון של איך הכל עובד. |
||||
|
|
||||
|
נסו לשנות את השורה: |
||||
|
|
||||
|
```Python |
||||
|
return {"item_name": item.name, "item_id": item_id} |
||||
|
``` |
||||
|
|
||||
|
...מ: |
||||
|
|
||||
|
```Python |
||||
|
... "item_name": item.name ... |
||||
|
``` |
||||
|
|
||||
|
...ל: |
||||
|
|
||||
|
```Python |
||||
|
... "item_price": item.price ... |
||||
|
``` |
||||
|
|
||||
|
...וראו איך העורך שלכם משלים את המאפיינים ויודע את הטיפוסים שלהם: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
לדוגמא יותר שלמה שכוללת עוד תכונות, ראו את ה<a href="https://fastapi.tiangolo.com/tutorial/">מדריך - למשתמש</a>. |
||||
|
|
||||
|
**התראת ספוילרים**: המדריך - למשתמש כולל: |
||||
|
|
||||
|
- הכרזה על **פרמטרים** ממקורות אחרים ושונים כגון: **כותרות**, **עוגיות**, **טפסים** ו - **קבצים**. |
||||
|
- איך לקבוע **מגבלות אימות** בעזרת `maximum_length` או `regex`. |
||||
|
- דרך חזקה וקלה להשתמש ב**<abbr title="ידועה גם כרכיבים, משאבים, ספקים, שירותים, מוזרקים">הזרקת תלויות</abbr>**. |
||||
|
- אבטחה והתאמתות, כולל תמיכה ב - **OAuth2** עם **JWT** והתאמתות **HTTP Basic**. |
||||
|
- טכניקות מתקדמות (אבל קלות באותה מידה) להכרזת אובייקטי JSON מקוננים (תודות ל - Pydantic). |
||||
|
- אינטרקציה עם **GraphQL** דרך <a href="https://strawberry.rocks" class="external-link" target="_blank">Strawberry</a> וספריות אחרות. |
||||
|
- תכונות נוספות רבות (תודות ל - Starlette) כגון: |
||||
|
- **WebSockets** |
||||
|
- בדיקות קלות במיוחד מבוססות על `requests` ו - `pytest` |
||||
|
- **CORS** |
||||
|
- **Cookie Sessions** |
||||
|
- ...ועוד. |
||||
|
|
||||
|
## ביצועים |
||||
|
|
||||
|
בדיקות עצמאיות של TechEmpower הראו שאפליקציות **FastAPI** שרצות תחת Uvicorn הן <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">מתשתיות הפייתון המהירות ביותר</a>, רק מתחת ל - Starlette ו - Uvicorn עצמן (ש - FastAPI מבוססת עליהן). (\*) |
||||
|
|
||||
|
כדי להבין עוד על הנושא, ראו את הפרק <a href="https://fastapi.tiangolo.com/benchmarks/" class="internal-link" target="_blank">Benchmarks</a>. |
||||
|
|
||||
|
## תלויות אופציונליות |
||||
|
|
||||
|
בשימוש Pydantic: |
||||
|
|
||||
|
- <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - <abbr title="המרת המחרוזת שמגיעה מבקשת HTTP למידע פייתון">"פרסור"</abbr> JSON. |
||||
|
- <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - לאימות כתובות אימייל. |
||||
|
|
||||
|
בשימוש Starlette: |
||||
|
|
||||
|
- <a href="https://requests.readthedocs.io" target="_blank"><code>requests</code></a> - דרוש אם ברצונכם להשתמש ב - `TestClient`. |
||||
|
- <a href="https://jinja.palletsprojects.com" target="_blank"><code>jinja2</code></a> - דרוש אם ברצונכם להשתמש בברירת המחדל של תצורת הטמפלייטים. |
||||
|
- <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - דרוש אם ברצונכם לתמוך ב <abbr title="המרת המחרוזת שמגיעה מבקשת HTTP למידע פייתון">"פרסור"</abbr> טפסים, באצמעות <code dir="ltr">request.form()</code>. |
||||
|
- <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - דרוש אם ברצונכם להשתמש ב - `SessionMiddleware`. |
||||
|
- <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - דרוש אם ברצונכם להשתמש ב - `SchemaGenerator` של Starlette (כנראה שאתם לא צריכים את זה עם FastAPI). |
||||
|
- <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - דרוש אם ברצונכם להשתמש ב - `UJSONResponse`. |
||||
|
|
||||
|
בשימוש FastAPI / Starlette: |
||||
|
|
||||
|
- <a href="https://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - לשרת שטוען ומגיש את האפליקציה שלכם. |
||||
|
- <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - דרוש אם ברצונכם להשתמש ב - `ORJSONResponse`. |
||||
|
|
||||
|
תוכלו להתקין את כל אלו באמצעות <code dir="ltr">pip install "fastapi[all]"</code>. |
||||
|
|
||||
|
## רשיון |
||||
|
|
||||
|
הפרויקט הזה הוא תחת התנאים של רשיון MIT. |
||||
@ -0,0 +1,145 @@ |
|||||
|
site_name: FastAPI |
||||
|
site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production |
||||
|
site_url: https://fastapi.tiangolo.com/he/ |
||||
|
theme: |
||||
|
name: material |
||||
|
custom_dir: overrides |
||||
|
palette: |
||||
|
- media: '(prefers-color-scheme: light)' |
||||
|
scheme: default |
||||
|
primary: teal |
||||
|
accent: amber |
||||
|
toggle: |
||||
|
icon: material/lightbulb |
||||
|
name: Switch to light mode |
||||
|
- media: '(prefers-color-scheme: dark)' |
||||
|
scheme: slate |
||||
|
primary: teal |
||||
|
accent: amber |
||||
|
toggle: |
||||
|
icon: material/lightbulb-outline |
||||
|
name: Switch to dark mode |
||||
|
features: |
||||
|
- search.suggest |
||||
|
- search.highlight |
||||
|
- content.tabs.link |
||||
|
icon: |
||||
|
repo: fontawesome/brands/github-alt |
||||
|
logo: https://fastapi.tiangolo.com/img/icon-white.svg |
||||
|
favicon: https://fastapi.tiangolo.com/img/favicon.png |
||||
|
language: he |
||||
|
repo_name: tiangolo/fastapi |
||||
|
repo_url: https://github.com/tiangolo/fastapi |
||||
|
edit_uri: '' |
||||
|
plugins: |
||||
|
- search |
||||
|
- markdownextradata: |
||||
|
data: data |
||||
|
nav: |
||||
|
- FastAPI: index.md |
||||
|
- Languages: |
||||
|
- en: / |
||||
|
- az: /az/ |
||||
|
- de: /de/ |
||||
|
- es: /es/ |
||||
|
- fa: /fa/ |
||||
|
- fr: /fr/ |
||||
|
- he: /he/ |
||||
|
- id: /id/ |
||||
|
- it: /it/ |
||||
|
- ja: /ja/ |
||||
|
- ko: /ko/ |
||||
|
- nl: /nl/ |
||||
|
- pl: /pl/ |
||||
|
- pt: /pt/ |
||||
|
- ru: /ru/ |
||||
|
- sq: /sq/ |
||||
|
- sv: /sv/ |
||||
|
- tr: /tr/ |
||||
|
- uk: /uk/ |
||||
|
- zh: /zh/ |
||||
|
markdown_extensions: |
||||
|
- toc: |
||||
|
permalink: true |
||||
|
- markdown.extensions.codehilite: |
||||
|
guess_lang: false |
||||
|
- mdx_include: |
||||
|
base_path: docs |
||||
|
- admonition |
||||
|
- codehilite |
||||
|
- extra |
||||
|
- pymdownx.superfences: |
||||
|
custom_fences: |
||||
|
- name: mermaid |
||||
|
class: mermaid |
||||
|
format: !!python/name:pymdownx.superfences.fence_code_format '' |
||||
|
- pymdownx.tabbed: |
||||
|
alternate_style: true |
||||
|
- attr_list |
||||
|
- md_in_html |
||||
|
extra: |
||||
|
analytics: |
||||
|
provider: google |
||||
|
property: UA-133183413-1 |
||||
|
social: |
||||
|
- icon: fontawesome/brands/github-alt |
||||
|
link: https://github.com/tiangolo/fastapi |
||||
|
- icon: fontawesome/brands/discord |
||||
|
link: https://discord.gg/VQjSZaeJmf |
||||
|
- icon: fontawesome/brands/twitter |
||||
|
link: https://twitter.com/fastapi |
||||
|
- icon: fontawesome/brands/linkedin |
||||
|
link: https://www.linkedin.com/in/tiangolo |
||||
|
- icon: fontawesome/brands/dev |
||||
|
link: https://dev.to/tiangolo |
||||
|
- icon: fontawesome/brands/medium |
||||
|
link: https://medium.com/@tiangolo |
||||
|
- icon: fontawesome/solid/globe |
||||
|
link: https://tiangolo.com |
||||
|
alternate: |
||||
|
- link: / |
||||
|
name: en - English |
||||
|
- link: /az/ |
||||
|
name: az |
||||
|
- link: /de/ |
||||
|
name: de |
||||
|
- link: /es/ |
||||
|
name: es - español |
||||
|
- link: /fa/ |
||||
|
name: fa |
||||
|
- link: /fr/ |
||||
|
name: fr - français |
||||
|
- link: /he/ |
||||
|
name: he |
||||
|
- link: /id/ |
||||
|
name: id |
||||
|
- link: /it/ |
||||
|
name: it - italiano |
||||
|
- link: /ja/ |
||||
|
name: ja - 日本語 |
||||
|
- link: /ko/ |
||||
|
name: ko - 한국어 |
||||
|
- link: /nl/ |
||||
|
name: nl |
||||
|
- link: /pl/ |
||||
|
name: pl |
||||
|
- link: /pt/ |
||||
|
name: pt - português |
||||
|
- link: /ru/ |
||||
|
name: ru - русский язык |
||||
|
- link: /sq/ |
||||
|
name: sq - shqip |
||||
|
- link: /sv/ |
||||
|
name: sv - svenska |
||||
|
- link: /tr/ |
||||
|
name: tr - Türkçe |
||||
|
- link: /uk/ |
||||
|
name: uk - українська мова |
||||
|
- link: /zh/ |
||||
|
name: zh - 汉语 |
||||
|
extra_css: |
||||
|
- https://fastapi.tiangolo.com/css/termynal.css |
||||
|
- https://fastapi.tiangolo.com/css/custom.css |
||||
|
extra_javascript: |
||||
|
- https://fastapi.tiangolo.com/js/termynal.js |
||||
|
- https://fastapi.tiangolo.com/js/custom.js |
||||
@ -0,0 +1,80 @@ |
|||||
|
# Tutorial - Pedoman Pengguna - Pengenalan |
||||
|
|
||||
|
Tutorial ini menunjukan cara menggunakan ***FastAPI*** dengan semua fitur-fiturnya, tahap demi tahap. |
||||
|
|
||||
|
Setiap bagian dibangun secara bertahap dari bagian sebelumnya, tetapi terstruktur untuk memisahkan banyak topik, sehingga kamu bisa secara langsung menuju ke topik spesifik untuk menyelesaikan kebutuhan API tertentu. |
||||
|
|
||||
|
Ini juga dibangun untuk digunakan sebagai referensi yang akan datang. |
||||
|
|
||||
|
Sehingga kamu dapat kembali lagi dan mencari apa yang kamu butuhkan dengan tepat. |
||||
|
|
||||
|
## Jalankan kode |
||||
|
|
||||
|
Semua blok-blok kode dapat dicopy dan digunakan langsung (Mereka semua sebenarnya adalah file python yang sudah teruji). |
||||
|
|
||||
|
Untuk menjalankan setiap contoh, copy kode ke file `main.py`, dan jalankan `uvicorn` dengan: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ uvicorn main:app --reload |
||||
|
|
||||
|
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
||||
|
<span style="color: green;">INFO</span>: Started reloader process [28720] |
||||
|
<span style="color: green;">INFO</span>: Started server process [28722] |
||||
|
<span style="color: green;">INFO</span>: Waiting for application startup. |
||||
|
<span style="color: green;">INFO</span>: Application startup complete. |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
**SANGAT disarankan** agar kamu menulis atau meng-copy kode, meng-editnya dan menjalankannya secara lokal. |
||||
|
|
||||
|
Dengan menggunakannya di dalam editor, benar-benar memperlihatkan manfaat dari FastAPI, melihat bagaimana sedikitnya kode yang harus kamu tulis, semua pengecekan tipe, pelengkapan otomatis, dll. |
||||
|
|
||||
|
--- |
||||
|
|
||||
|
## Install FastAPI |
||||
|
|
||||
|
Langkah pertama adalah dengan meng-install FastAPI. |
||||
|
|
||||
|
Untuk tutorial, kamu mungkin hendak meng-instalnya dengan semua pilihan fitur dan dependensinya: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ pip install "fastapi[all]" |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
...yang juga termasuk `uvicorn`, yang dapat kamu gunakan sebagai server yang menjalankan kodemu. |
||||
|
|
||||
|
!!! catatan |
||||
|
Kamu juga dapat meng-instalnya bagian demi bagian. |
||||
|
|
||||
|
Hal ini mungkin yang akan kamu lakukan ketika kamu hendak men-deploy aplikasimu ke tahap produksi: |
||||
|
|
||||
|
``` |
||||
|
pip install fastapi |
||||
|
``` |
||||
|
|
||||
|
Juga install `uvicorn` untk menjalankan server" |
||||
|
|
||||
|
``` |
||||
|
pip install "uvicorn[standard]" |
||||
|
``` |
||||
|
|
||||
|
Dan demikian juga untuk pilihan dependensi yang hendak kamu gunakan. |
||||
|
|
||||
|
## Pedoman Pengguna Lanjutan |
||||
|
|
||||
|
Tersedia juga **Pedoman Pengguna Lanjutan** yang dapat kamu baca nanti setelah **Tutorial - Pedoman Pengguna** ini. |
||||
|
|
||||
|
**Pedoman Pengguna Lanjutan**, dibangun atas hal ini, menggunakan konsep yang sama, dan mengajarkan kepadamu beberapa fitur tambahan. |
||||
|
|
||||
|
Tetapi kamu harus membaca terlebih dahulu **Tutorial - Pedoman Pengguna** (apa yang sedang kamu baca sekarang). |
||||
|
|
||||
|
Hal ini didesain sehingga kamu dapat membangun aplikasi lengkap dengan hanya **Tutorial - Pedoman Pengguna**, dan kemudian mengembangkannya ke banyak cara yang berbeda, tergantung dari kebutuhanmu, menggunakan beberapa ide-ide tambahan dari **Pedoman Pengguna Lanjutan**. |
||||
@ -0,0 +1,24 @@ |
|||||
|
# ユーザーガイド 応用編 |
||||
|
|
||||
|
## さらなる機能 |
||||
|
|
||||
|
[チュートリアル - ユーザーガイド](../tutorial/){.internal-link target=_blank}により、**FastAPI**の主要な機能は十分に理解できたことでしょう。 |
||||
|
|
||||
|
以降のセクションでは、チュートリアルでは説明しきれなかったオプションや設定、および機能について説明します。 |
||||
|
|
||||
|
!!! tip "豆知識" |
||||
|
以降のセクションは、 **必ずしも"応用編"ではありません**。 |
||||
|
|
||||
|
ユースケースによっては、その中から解決策を見つけられるかもしれません。 |
||||
|
|
||||
|
## 先にチュートリアルを読む |
||||
|
|
||||
|
[チュートリアル - ユーザーガイド](../tutorial/){.internal-link target=_blank}の知識があれば、**FastAPI**の主要な機能を利用することができます。 |
||||
|
|
||||
|
以降のセクションは、すでにチュートリアルを読んで、その主要なアイデアを理解できていることを前提としています。 |
||||
|
|
||||
|
## テスト駆動開発のコース |
||||
|
|
||||
|
このセクションの内容を補完するために脱初心者用コースを受けたい場合は、**TestDriven.io**による、<a href="https://testdriven.io/courses/tdd-fastapi/" class="external-link" target="_blank">Test-Driven Development with FastAPI and Docker</a>を確認するのがよいかもしれません。 |
||||
|
|
||||
|
現在、このコースで得られた利益の10%が**FastAPI**の開発のために寄付されています。🎉 😄 |
||||
@ -0,0 +1,156 @@ |
|||||
|
# NoSQL (分散 / ビッグデータ) Databases |
||||
|
|
||||
|
**FastAPI** はあらゆる <abbr title="分散データベース (Big Data)や 'Not Only SQL'">NoSQL</abbr>と統合することもできます。 |
||||
|
|
||||
|
ここでは<abbr title="ここでのドキュメントとは、キーと値を持つJSONオブジェクト（ディクショナリー）をあらわし、これらの値は他のJSONオブジェクトや配列（リスト）、数値、文字列、真偽値などにすることができます。">ドキュメント</abbr>ベースのNoSQLデータベースである**<a href="https://www.couchbase.com/" class="external-link" target="_blank">Couchbase</a>**を使用した例を見てみましょう。 |
||||
|
|
||||
|
他にもこれらのNoSQLデータベースを利用することが出来ます: |
||||
|
|
||||
|
* **MongoDB** |
||||
|
* **Cassandra** |
||||
|
* **CouchDB** |
||||
|
* **ArangoDB** |
||||
|
* **ElasticSearch** など。 |
||||
|
|
||||
|
!!! tip "豆知識" |
||||
|
**FastAPI**と**Couchbase**を使った公式プロジェクト・ジェネレータがあります。すべて**Docker**ベースで、フロントエンドやその他のツールも含まれています: <a href="https://github.com/tiangolo/full-stack-fastapi-couchbase" class="external-link" target="_blank">https://github.com/tiangolo/full-stack-fastapi-couchbase</a> |
||||
|
|
||||
|
## Couchbase コンポーネントの Import |
||||
|
|
||||
|
まずはImportしましょう。今はその他のソースコードに注意を払う必要はありません。 |
||||
|
|
||||
|
```Python hl_lines="3-5" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
## "document type" として利用する定数の定義 |
||||
|
|
||||
|
documentで利用する固定の`type`フィールドを用意しておきます。 |
||||
|
|
||||
|
これはCouchbaseで必須ではありませんが、後々の助けになるベストプラクティスです。 |
||||
|
|
||||
|
```Python hl_lines="9" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
## `Bucket` を取得する関数の追加 |
||||
|
|
||||
|
**Couchbase**では、bucketはdocumentのセットで、様々な種類のものがあります。 |
||||
|
|
||||
|
Bucketは通常、同一のアプリケーション内で互いに関係を持っています。 |
||||
|
|
||||
|
リレーショナルデータベースの世界でいう"database"(データベースサーバではなく特定のdatabase)と類似しています。 |
||||
|
|
||||
|
**MongoDB** で例えると"collection"と似た概念です。 |
||||
|
|
||||
|
次のコードでは主に `Bucket` を利用してCouchbaseを操作します。 |
||||
|
|
||||
|
この関数では以下の処理を行います: |
||||
|
|
||||
|
* **Couchbase** クラスタ(1台の場合もあるでしょう)に接続 |
||||
|
* タイムアウトのデフォルト値を設定 |
||||
|
* クラスタで認証を取得 |
||||
|
* `Bucket` インスタンスを取得 |
||||
|
* タイムアウトのデフォルト値を設定 |
||||
|
* 作成した`Bucket`インスタンスを返却 |
||||
|
|
||||
|
```Python hl_lines="12-21" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
## Pydantic モデルの作成 |
||||
|
|
||||
|
**Couchbase**のdocumentは実際には単にJSONオブジェクトなのでPydanticを利用してモデルに出来ます。 |
||||
|
|
||||
|
### `User` モデル |
||||
|
|
||||
|
まずは`User`モデルを作成してみましょう: |
||||
|
|
||||
|
```Python hl_lines="24-28" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
このモデルは*path operation*に使用するので`hashed_password`は含めません。 |
||||
|
|
||||
|
### `UserInDB` モデル |
||||
|
|
||||
|
それでは`UserInDB`モデルを作成しましょう。 |
||||
|
|
||||
|
こちらは実際にデータベースに保存されるデータを保持します。 |
||||
|
|
||||
|
`User`モデルの持つ全ての属性に加えていくつかの属性を追加するのでPydanticの`BaseModel`を継承せずに`User`のサブクラスとして定義します: |
||||
|
|
||||
|
```Python hl_lines="31-33" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
!!! note "備考" |
||||
|
データベースに保存される`hashed_password`と`type`フィールドを`UserInDB`モデルに保持させていることに注意してください。 |
||||
|
|
||||
|
しかしこれらは(*path operation*で返却する)一般的な`User`モデルには含まれません |
||||
|
|
||||
|
## user の取得 |
||||
|
|
||||
|
それでは次の関数を作成しましょう: |
||||
|
|
||||
|
* username を取得する |
||||
|
* username を利用してdocumentのIDを生成する |
||||
|
* 作成したIDでdocumentを取得する |
||||
|
* documentの内容を`UserInDB`モデルに設定する |
||||
|
|
||||
|
*path operation関数*とは別に、`username`(またはその他のパラメータ)からuserを取得することだけに特化した関数を作成することで、より簡単に複数の部分で再利用したり<abbr title="コードで書かれた自動テストで、他のコードが正しく動作しているかどうかをチェックするもの。">ユニットテスト</abbr>を追加することができます。 |
||||
|
|
||||
|
```Python hl_lines="36-42" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
### f-strings |
||||
|
|
||||
|
`f"userprofile::{username}"` という記載に馴染みがありませんか？これは Python の"<a href="https://docs.python.org/3/glossary.html#term-f-string" class="external-link" target="_blank">f-string</a>"と呼ばれるものです。 |
||||
|
|
||||
|
f-stringの`{}`の中に入れられた変数は、文字列の中に展開/注入されます。 |
||||
|
|
||||
|
### `dict` アンパック |
||||
|
|
||||
|
`UserInDB(**result.value)`という記載に馴染みがありませんか？<a href="https://docs.python.org/3/glossary.html#term-argument" class="external-link" target="_blank">これは`dict`の"アンパック"</a>と呼ばれるものです。 |
||||
|
|
||||
|
これは`result.value`の`dict`からそのキーと値をそれぞれ取りキーワード引数として`UserInDB`に渡します。 |
||||
|
|
||||
|
例えば`dict`が下記のようになっていた場合: |
||||
|
|
||||
|
```Python |
||||
|
{ |
||||
|
"username": "johndoe", |
||||
|
"hashed_password": "some_hash", |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
`UserInDB`には次のように渡されます: |
||||
|
|
||||
|
```Python |
||||
|
UserInDB(username="johndoe", hashed_password="some_hash") |
||||
|
``` |
||||
|
|
||||
|
## **FastAPI** コードの実装 |
||||
|
|
||||
|
### `FastAPI` app の作成 |
||||
|
|
||||
|
```Python hl_lines="46" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
### *path operation関数*の作成 |
||||
|
|
||||
|
私たちのコードはCouchbaseを呼び出しており、<a href="https://docs.couchbase.com/python-sdk/2.5/async-programming.html#asyncio-python-3-5" class="external-link" target="_blank">実験的なPython <code>await</code></a>を使用していないので、私たちは`async def`ではなく通常の`def`で関数を宣言する必要があります。 |
||||
|
|
||||
|
また、Couchbaseは単一の`Bucket`オブジェクトを複数の<abbr title="プログラムによって実行される一連のコードのことで、同時に、または間隔をおいて他のコードも実行されることがあります。">スレッド</abbr>で使用しないことを推奨していますので、単に直接Bucketを取得して関数に渡すことが出来ます。 |
||||
|
|
||||
|
```Python hl_lines="49-53" |
||||
|
{!../../../docs_src/nosql_databases/tutorial001.py!} |
||||
|
``` |
||||
|
|
||||
|
## まとめ |
||||
|
|
||||
|
他のサードパーティ製のNoSQLデータベースを利用する場合でも、そのデータベースの標準ライブラリを利用するだけで利用できます。 |
||||
|
|
||||
|
他の外部ツール、システム、APIについても同じことが言えます。 |
||||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue