MENU

Django Ninjaチュートリアル⑤(クエリパラメータ)

Django-Ninjaチュートリアル⑤(クエリパラメータ)

前回に引き続き、Django Ninjaのチュートリアルを進めていきます。

前回までの記事はこちらをご覧ください。

ベースとなっているチュートリアルはこちらです。

それでは始めていきましょう。

目次

クエリパラメータ

今回は、Django Ninjaでのクエリパラメータの取り扱いについてみていきます。

Django Ninjaでは、パスパラメータではない他の関数パラメータを宣言すると、それらは自動的にクエリパラメータとして認識されます。

以下のような例をみていきます。

from ninja import NinjaAPI, Path
from example.Schema.api_v2_schema import PathDate

app_v2 = NinjaAPI(
  title = "Django Ninja Sample App2",
  version = "1.0.1"
)

weapons = ["Ninjato", "Shuriken", "Katana", "Kama", "Kunai", "Naginata", "Yari"] # add

〜略〜

# add 3
@app_v2.get("/weapons")
def weapons_list(request, limit: int = 10, offset: int = 0):
  return weapons[offset: offset + limit]

この例を確認する場合は、http://127.0.0.1:8000/api_v2/weapons?offset=0&limit=10にアクセスする必要があります。
下記のとおり、最初に設定したweaponsが返されました。

["Ninjato", "Shuriken", "Katana", "Kama", "Kunai", "Naginata", "Yari"]

Django Ninjaでは、すべてのGETパラメータで、デフォルト設定がstr型となります。
そこで、関数の引数(ここではlimitとoffset)に型アノテーションの設定をすると、これらの引数は設定した型(ここではint型)に変換され、それに対してバリデーションが適用されます。

パスパラメータと同様に、クエリパラメータでも型に基づくバリデーション機能を適用することができます。

⚠️ 引数に注釈を付けない場合は、自動的に引数はstr型として扱われます。

デフォルト値の設定

クエリパラメータはパスの固定部分ではなく、オプションの設定であるため、デフォルト値を渡すことができます。

先ほどの例を見てみます。

# add 3
@app_v2.get("/weapons")
def weapons_list(request, limit: int = 10, offset: int = 0):
  return weapons[offset: offset + limit]

この場合、limitの=10、offsetの=0はデフォルト値の設定です。

そのため、http://127.0.0.1:8000/api_v2/weaponsへのアクセスは、http://127.0.0.1:8000/api_v2/weapons?offset=0&limit=10と同じ結果を返します。

また、http://127.0.0.1:8000/api_v2/weapons?offset=2とした場合、

  • limitは10(デフォルト値を採用)
  • offsetは2(クエリパラメータで渡された値を採用)

としてアクセスすることになります。

この場合、返されるJSONは先ほどと異なり、下記のようになります。
(offset=2により、先頭の2つのweaponが返されていません)

["Katana", "Kama", "Kunai", "Naginata", "Yari"]

以上のように、オプションであるがゆえに、デフォルト値を渡すことができ、逆にデフォルト値を設定していても任意の値が渡されれば、その引数は渡された値に更新されて実行されます。

必須またはオプションのパラメータ

Django Ninjaでは、Pythonで関数の引数を宣言する方法と同じ方法で、必須のパラメータまたはオプションパラメータを宣言することができます。

例えば、以下のような例をみていきます。

from ninja import NinjaAPI, Path
from example.Schema.api_v2_schema import PathDate

app_v2 = NinjaAPI(
  title = "Django Ninja Sample App2",
  version = "1.0.1"
)

weapons = ["Ninjato", "Shuriken", "Katana", "Kama", "Kunai", "Naginata", "Yari"]

〜略〜

# add 4
@app_v2.get("/weapons/search")
def search_weapons(request, q: str, offset: int = 0):
  results = [weapon for weapon in weapons if q in weapon.lower()]
  print(q, results)
  return results[offset: offset + 10]

この場合、
q必須関数(qに値が渡されないと関数が実行されないため)
offsetオプション関数(offsetに値が渡されない場合、デフォルト値で実行される)
ということになります。

実行結果は以下のとおりです。
q(OpenAPIでも「」がついています)にkatanaを指定しましたが、offsetは指定していません。
これで実行すると、offsetはオプションのため指定していない以上、デフォルト値で実行されています。

qとoffsetの実行結果

GETパラメータの型変換

まずは例として、以下のようにGETメソッドの中で、異なる型を定義した複数のパラメータを設定します。

from ninja import NinjaAPI, Path
from example.Schema.api_v2_schema import PathDate
from datetime import date # add

app_v2 = NinjaAPI(
  title = "Django Ninja Sample App2",
  version = "1.0.1"
)

〜略〜

# add 5
@app_v2.get("/example")
def example(request, s: str = None, b: bool = None, d: date = None, i: int = None):
  return[s, b, d, i]

定義しパラメータは以下のとおりです。

  • sstr型を定義。
  • bbool型を定義。
  • ddate型を定義(上部でimportしている)。
  • iint型を定義。

なお、すべての値においてデフォルト値をNoneで設定しています。

この状態で、str型、int型はそのとおり実行されます。型のバリデーションが入ります。

bool型については、

http://127.0.0.1:8000/api_v2/example?b=1
http://127.0.0.1:8000/api_v2/example?b=True
http://127.0.0.1:8000/api_v2/example?b=true
http://127.0.0.1:8000/api_v2/example?b=on
http://127.0.0.1:8000/api_v2/example?b=yes

のような引数の渡し方や大文字小文字の区別をした引数の渡し方をすることができます。

そしてこの場合、bool型のとおり、関数はbの値を検証し、TrueまたはFalseを返します。

また、date型は日付文字列での表示や整数(UNIXタイムスタンプ) の両方で値を渡すことができます。

date型の例は以下のようなケースです。

以下の2つは同じ値を違う表示で渡しています。
①http://127.0.0.1:8000/api_v2/example?d=1577836800(UNIXタイムスタンプの場合)
②http://127.0.0.1:8000/api_v2/example?d=2020-01-01(日付文字列の場合)

UNIXタイムスタンプとは?
1970年1月1日午前0時0分0秒からの経過秒数で表示した日時のこと
→1970/1/1 0:0:1は「1」となる。

Schemaを利用したカプセル化

クエリパラメータでもパスパラメータと同様にSchemaを利用したパラメータのカプセル化(またはグループ化)が可能です。

内容はこちらの記事で書いていますので、参考にしてみてください。

最後に

今回はDjnago-Ninjaにおけるクエリパラメータについてまとめてみました。

パスパラメータと似ている部分もあったのではないかと思います。

Python構文を用いた設定ができる点も便利です(著者はもっとPythonを勉強しなければならないかもしれません)。

また、次回以降もDjnago-Ninjaのチュートリアルをしていきたいと思います。

それでは、今回はここまでとします。

Django-Ninjaチュートリアル⑤(クエリパラメータ)

この記事が気に入ったら
フォローしてね!

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

はじめまして、ふじです。
Python、Django、FastAPI、React.js、Next.jsを学習している、ずっと文系のプログラミング独学者です。

目次