fastAPI入門

fastAPI is 何？

• python向けのAPIサーバー構築用ライブラリです。pythonでバックエンドを組むにはDjangoなどが有名ですが、fastAPIは以下のような特徴があります
  • 「早い」「覚えやすい」「新しい（最新python表記を使用）」 の三拍子
  • 参考（fastAPIの特徴）

この記事 is 何？

• 下記の書籍の内容（１～４章）をベースにfastAPIの使い方をまとめています（必要に応じて書籍外の情報も入れています）
  【対象本】「Building Data Science Applications with FastAPI」
  • FastAPI本。ベースライブラリPydanticの使い方や一般的なWebサイト構築に必要な要素等を紹介。「OpenCVを使ったリアルタイム😇認識」など実用的なWebアプリが多いのもうれしいところ

fastAPI入門

python環境構築

• 以下のパッケージを入れればfastAPIを使えるようになる
  • pip install fastapi uvicorn[standard]
• 動作確認用にHTTPieを使う
  • 他のREST APIツールでもOK
  • テストによる動作確認を行う場合はfastAPIの機能「TestClient」を使うのが便利

FastAPIの基本（RESTfulAPIの開発）

• 【サーバー起動方法】uvicorn ソースファイル名:サーバー変数名 --host 0.0.0.0
  • host指定しないとリモートからアクセスできない
  • /docs にAPIドキュメントページが自動作成される
• ルート変数も型ヒントを使ってサクッと指定可能
  
  • 型指定にpythonのEnumクラスを指定すれば値をEnum要素に限定可能
  • fastapi.Path (初期値,条件)をルート変数初期値として入れればルート変数の値を制限可能
    • 引数例
      • lt,gt,le,ge (値域)
      • min_length,max_length (最小／最大値)
      • regex(正規表現)
• URLパラメータ
  • URL内に該当変数が無ければURLパラメータ扱いになる
  • PathではなくQuery()を使用。引数はfastapi.Pathと似た感じ(どちらも内部でpydanticを使っているから)
    
• req body
  • Body()を使用（引数はPath()等と同じ）
• Pydantic
  • Path()/Query()/Body()など関数はいずれも内部でPydanticを使っている（型ヒントを拡張したデータチェック）
  • BaseModelによるフィールド定義(下図)
    • TypeScriptの型エイリアス風？
      
• フォーム
  • Body()ではJsonを受け渡してたが、フォームからのエンコードデータを受け取る場合はForm()
• ファイルアップロード:File()
• ファイルアップロード(続き)
  • デフォルトだとアップロードファイルはメモリ内に格納される
    
  • bytesの代わりにUploadFile型ヒントを使うとpython通常のファイルと似た扱いのデータを取得できる(メタデータなどにアクセス可)
    
• HeaderとCookie
  • Header()とCookie()で指定可能(下図コードではクッキーは無指定)
    
• Requestオブジェクト
  • Header/Cookie/Methodなど、リクエストに関するいろんなデータを取得できる
    

Responseのカスタマイズ

• これまでは受け取ったオブジェクトをそのまま返していたが、ここからはカスタマイズして返す方法を紹介
• 状態コードの変更
  • postデコレータに引数status_codeを設定
    
    • レスポンス結果例
      
  • 関数内で変更する場合はResponseオブジェクトのプロパティstatus_codeに設定
• エラーコードのraise
  • 関数内でエラーと判定した際にHTTPException()によりエラーを発生
• Responseデータの種別
  • JSONResponse : Responseのサブクラス通常はシリアライズするデータをこれに入れるだけ
  • HTMLResponse : HTMLを返す場合はこちら
  • PlainTextResponse(生文字)
  • RedirectResponse(リダイレクト用)
  • StreamingResponse(ストリームバイトデータ)
  • FileResponse(自動でファイル返信用パスの生成)
• Responseクラスの使い方
  • メソッドデコレータの引数response_classに上記クラス指定
  • HTMLとPlainTextは文字列を返すだけ
  • RedirectはRedirectResponse(リダイレクト先)を返す
  • FileはFileResponse(返すファイルのローカルパス)を返す
  • それ以外にもカスタマイズしたデータをResponse()で返す事も可能

複数ルーターの設定

• ルーターファイルを 複数用意し、アプリ側で統合可能。
  • まず、ルーターファイルを複数作成（それぞれパスは"/"から指定)
  • アプリ側で ”FastAPIインスタンス”.include_router(”importしたルーター”, prefix="/URLプレフィックス")

pydanticデータモデル

概要

• ここまででFastAPI様々なRestAPI要求を処理する例を見てきた

• 以降、fastAPIの屋台骨でもあるpydanticモデル(BaseModelを継承したクラスによるデータ構造定義)について詳しい使い方を紹介する
  

• [復習] 基本はBaseModelを継承したクラスのメンバーに型ヒントを付けるだけ。型の自由度は高い（プリミティブ型だけでなくEnumやListやdateなども入れられる)

  • 違反したデータを入れるとエラーとともに違反した内容を返してくれる

• さらには、他のpydanicモデルをメンバーとして登録可能
  

• 必須ではないフィールドにはOptional型を指定

  • python3.10以降ではUnion型ヒント(|表記)でNoneと併記する方を推奨
    

• デフォルト値を設定することも可能

  • 当然ながらデフォルト値は初期化したタイミングの値を保持し続ける。動的に値を生成する方法は後述

• Field検証

  • 第3章ではAPI関数の引数の型ヒントで文字列長や値の検証を行ったが、モデルフィールドでField()を使って同様の検証を行う事が可能
    
  • Fieldで使える検証項目はこちらを参照

• 動的なデフォルト値

  • Field(default_factory=関数) で指定可能
    

• URLやEmailアドレス型

  • pydanticにはEmail文字列型(EmailStr)、URL文字列型(HttpUrl)があり手動でのsyntaxチェック不要
    

• 継承

  • 作ったpydanticモデルを継承し拡張可能

カスタムデータ検証

• フィールド：Field()による簡易検証でなく独自の検証メソッドで検証可能(@ validator())
  
• オブジェクト：@ root_validatorで受け取った複数の値を使って検証実施可能
  

Pydanticオブジェクト操作

• インスタンス.dict()で辞書に変換可能
  • .dict(include={含めるフィールド名}) や
    .dict(exclude={除外するフィールド名}) なども可能
• 一部のフィールドのみ送信未送信フィールドは更新しない）ことも可能（詳細省略）

まとめ

• 本記事のもととなった書籍以外の参考書籍としては、Zennの「fastAPI入門」がいい感じにまとまっています
• この記事で書かれている項目で以外のfastAPIの機能としては「依存性注入(5章)」「テスト機能(TestClient)(9章)」などがあります。