# クエリパラメータ { #query-parameters }


パスパラメータではない関数パラメータを宣言すると、それらは自動的に「クエリ」パラメータとして解釈されます。

{* ../../docs_src/query_params/tutorial001_py310.py hl[9] *}

クエリはURL内で `?` の後に続くキーとバリューの組で、 `&` で区切られています。

例えば、以下の様なURL内で:

```
http://127.0.0.1:8000/items/?skip=0&limit=10
```

...クエリパラメータは:

* `skip`: 値は `0`
* `limit`: 値は `10`

これらはURLの一部なので、「自然に」文字列になります。

しかしPythonの型を宣言すると (上記の例では `int` として)、その型に変換されバリデーションが行われます。

パスパラメータに適用される処理と完全に同様な処理がクエリパラメータにも施されます:

* エディターサポート (明らかに)
* データ <dfn title="HTTP リクエストから来る文字列を Python のデータに変換すること">「解析」</dfn>
* データバリデーション
* 自動ドキュメント生成

## デフォルト { #defaults }

クエリパラメータはパスの固定部分ではないので、オプショナルとしたり、デフォルト値をもつことができます。

上述の例では、`skip=0` と `limit=10` というデフォルト値を持っています。

したがって、以下のURLにアクセスすることは:

```
http://127.0.0.1:8000/items/
```

以下のURLにアクセスすることと同等になります:

```
http://127.0.0.1:8000/items/?skip=0&limit=10
```

しかし、例えば、以下にアクセスすると:

```
http://127.0.0.1:8000/items/?skip=20
```

関数内のパラメータの値は以下の様になります:

* `skip=20`: URL内にセットしたため
* `limit=10`: デフォルト値だったため

## オプショナルなパラメータ { #optional-parameters }

同様に、デフォルト値を `None` とすることで、オプショナルなクエリパラメータを宣言できます:

{* ../../docs_src/query_params/tutorial002_py310.py hl[7] *}

この場合、関数パラメータ `q` はオプショナルとなり、デフォルトでは `None` になります。

/// tip | 豆知識

パスパラメータ `item_id` はパスパラメータであり、`q` はそれとは違ってクエリパラメータであると判別できるほど**FastAPI** が賢いということにも注意してください。

///

## クエリパラメータの型変換 { #query-parameter-type-conversion }

`bool` 型も宣言でき、変換されます:

{* ../../docs_src/query_params/tutorial003_py310.py hl[7] *}

この場合、以下にアクセスすると:

```
http://127.0.0.1:8000/items/foo?short=1
```

もしくは、

```
http://127.0.0.1:8000/items/foo?short=True
```

もしくは、

```
http://127.0.0.1:8000/items/foo?short=true
```

もしくは、

```
http://127.0.0.1:8000/items/foo?short=on
```

もしくは、

```
http://127.0.0.1:8000/items/foo?short=yes
```

もしくは、他の大文字小文字のバリエーション (アッパーケース、最初の文字だけアッパーケース、など)で、関数は `short` パラメータを `True` な `bool` 値として扱います。それ以外は `False` になります。


## 複数のパスパラメータとクエリパラメータ { #multiple-path-and-query-parameters }

複数のパスパラメータとクエリパラメータを同時に宣言できます。**FastAPI**はどれがどれかを把握しています。

そして特定の順序で宣言しなくてもよいです。

名前で判別されます:

{* ../../docs_src/query_params/tutorial004_py310.py hl[6,8] *}

## 必須のクエリパラメータ { #required-query-parameters }

パスパラメータ以外のパラメータ (今のところ、クエリパラメータのみ見てきました) のデフォルト値を宣言した場合、そのパラメータは必須ではなくなります。

特定の値を与えずにただオプショナルにしたい場合はデフォルト値を `None` にして下さい。

しかしクエリパラメータを必須にしたい場合は、ただデフォルト値を宣言しなければよいです:

{* ../../docs_src/query_params/tutorial005_py310.py hl[6:7] *}

ここで、クエリパラメータ `needy` は `str` 型の必須のクエリパラメータです。

以下のURLをブラウザで開くと:

```
http://127.0.0.1:8000/items/foo-item
```

...必須のパラメータ `needy` を加えなかったので、以下の様なエラーが表示されます:

```JSON
{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "query",
        "needy"
      ],
      "msg": "Field required",
      "input": null
    }
  ]
}
```

`needy` は必須のパラメータなので、URLにセットする必要があります:

```
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy
```

...これはうまくいくでしょう:

```JSON
{
    "item_id": "foo-item",
    "needy": "sooooneedy"
}
```

そして当然、あるパラメータを必須に、あるパラメータにデフォルト値を設定し、またあるパラメータを完全にオプショナルにできます:

{* ../../docs_src/query_params/tutorial006_py310.py hl[8] *}

この場合、3つのクエリパラメータがあります。:

* `needy`、必須の `str` 。
* `skip`、デフォルト値を `0` とする `int` 。
* `limit`、オプショナルな `int` 。

/// tip | 豆知識

[パスパラメータ](path-params.md#predefined-values)と同様に `Enum` を使用できます。

///