# 查询参数模型 { #query-parameter-models }

如果你有一组具有相关性的**查询参数**，你可以创建一个 **Pydantic 模型**来声明它们。

这将允许你在**多个地方**去**复用模型**，并且一次性为所有参数声明验证和元数据。😎

/// note | 注意

FastAPI 从 `0.115.0` 版本开始支持这个特性。🤓

///

## 使用 Pydantic 模型的查询参数 { #query-parameters-with-a-pydantic-model }

在一个 **Pydantic 模型**中声明你需要的**查询参数**，然后将参数声明为 `Query`：

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

# 查詢參數模型 { #query-parameter-models }

如果你有一組具有相關性的**查詢參數**，你可以建立一個 **Pydantic 模型**來聲明它們。

這將允許你在**多個地方**去**重複使用模型**，並且一次性為所有參數聲明驗證和元資料 (metadata)。😎

/// note

FastAPI 從 `0.115.0` 版本開始支援這個特性。🤓

///

## 使用 Pydantic 模型的查詢參數 { #query-parameters-with-a-pydantic-model }

在一個 **Pydantic 模型**中聲明你需要的**查詢參數**，然後將參數聲明為 `Query`：

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

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

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

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

名前で判別されます:

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

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

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

```Python
q: str | None = Query(default=None, max_length=50)
```

Це забезпечить валідацію даних, виведе зрозумілу помилку у разі недійсних даних і задокументує параметр у схемі OpenAPI операції шляху.

### `Query` як значення за замовчуванням або всередині `Annotated` { #query-as-the-default-value-or-in-annotated }

Важливо пам’ятати, якщо використовувати `Query` всередині `Annotated`, не можна задавати параметр `default` у `Query`.

但用 `Query` 的版本會明確宣告它是查詢參數。

接著，我們可以傳更多參數給 `Query`。此例中是用於字串的 `max_length` 參數：

```Python
q: str | None = Query(default=None, max_length=50)
```

這一樣會驗證資料、在資料不合法時顯示清楚錯誤，並在 OpenAPI 的路徑操作中文件化該參數。

### 將 `Query` 作為預設值或放在 `Annotated` 中 { #query-as-the-default-value-or-in-annotated }

注意，把 `Query` 放在 `Annotated` 內時，不能使用 `Query` 的 `default` 參數。

請改用函式參數的實際預設值。否則會不一致。

例如，這是不允許的：

```Python

///

## Pydantic Model ile Query Parameters { #query-parameters-with-a-pydantic-model }

İhtiyacınız olan **query parameter**’ları bir **Pydantic model** içinde tanımlayın, ardından parametreyi `Query` olarak belirtin:

{* ../../docs_src/query_param_models/tutorial001_an_py310.py hl[9:13,17] *}

**FastAPI**, request’teki **query parameter**’lardan **her field** için veriyi **extract** eder ve tanımladığınız Pydantic model’i size verir.

<div class="screenshot">
<img src="/img/tutorial/query-param-models/image01.png">
</div>

## Запретить Дополнительные Query-Параметры { #forbid-extra-query-parameters }

В некоторых случаях (не особо часто встречающихся) вам может понадобиться **ограничить** query-параметры, которые вы хотите получить.

        List<RelatedQuery> testData = new ArrayList<>();
        testData.add(createRelatedQuery("term1", new String[] { "query1" }, "host1"));
        testData.add(createRelatedQuery("term1", new String[] { "query2" }, "host2"));
        testData.add(createRelatedQuery("term2", new String[] { "query3" }, ""));
        mockBhv.setTestData(testData);

        int count = relatedQueryHelper.load();

q: str | None = Query(default=None, max_length=50)
```

This will validate the data, show a clear error when the data is not valid, and document the parameter in the OpenAPI schema *path operation*.

### `Query` as the default value or in `Annotated` { #query-as-the-default-value-or-in-annotated }

Keep in mind that when using `Query` inside of `Annotated` you cannot use the `default` parameter for `Query`.

# 쿼리 매개변수 모델 { #query-parameter-models }

연관된 **쿼리 매개변수** 그룹이 있다면 이를 선언하기 위해 **Pydantic 모델**을 생성할 수 있습니다.

이렇게 하면 **여러 곳**에서 **모델을 재사용**할 수 있을 뿐만 아니라, 매개변수에 대한 검증 및 메타데이터도 한 번에 선언할 수 있습니다. 😎

/// note | 참고

이 기능은 FastAPI 버전 `0.115.0`부터 지원됩니다. 🤓

///

## Pydantic 모델과 쿼리 매개변수 { #query-parameters-with-a-pydantic-model }

필요한 **쿼리 매개변수**를 **Pydantic 모델** 안에 선언한 다음, 매개변수를 `Query`로 선언합니다: