From ca26f2274c7f094fac4ce3e2198e9f81f61d8206 Mon Sep 17 00:00:00 2001 From: SwftAlpc Date: Sun, 10 Jan 2021 03:33:07 +0900 Subject: [PATCH] =?UTF-8?q?=F0=9F=8C=90=20Add=20Japanese=20translation=20f?= =?UTF-8?q?or=20Tutorial=20-=20Body=20-=20Updates=20(#1956)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: T. Tokusumi <41147016+tokusumi@users.noreply.github.com> Co-authored-by: ryusuke.miyaji Co-authored-by: ryuckel <36391432+ryuckel@users.noreply.github.com> Co-authored-by: tokusumi Co-authored-by: Sebastián Ramírez --- docs/ja/docs/tutorial/body-updates.md | 99 +++++++++++++++++++++++++++ docs/ja/mkdocs.yml | 1 + 2 files changed, 100 insertions(+) create mode 100644 docs/ja/docs/tutorial/body-updates.md diff --git a/docs/ja/docs/tutorial/body-updates.md b/docs/ja/docs/tutorial/body-updates.md new file mode 100644 index 000000000..7a56ef2b9 --- /dev/null +++ b/docs/ja/docs/tutorial/body-updates.md @@ -0,0 +1,99 @@ +# ボディ - 更新 + +## `PUT`による置換での更新 + +項目を更新するにはHTTPの`PUT`操作を使用することができます。 + +`jsonable_encoder`を用いて、入力データをJSON形式で保存できるデータに変換することができます（例：NoSQLデータベース）。例えば、`datetime`を`str`に変換します。 + +```Python hl_lines="30 31 32 33 34 35" +{!../../../docs_src/body_updates/tutorial001.py!} +``` + +既存のデータを置き換えるべきデータを受け取るために`PUT`は使用されます。 + +### 置換についての注意 + +つまり、`PUT`を使用して以下のボディで項目`bar`を更新したい場合は: + +```Python +{ + "name": "Barz", + "price": 3, + "description": None, +} +``` + +すでに格納されている属性`"tax": 20.2`を含まないため、入力モデルのデフォルト値は`"tax": 10.5`です。 + +そして、データはその「新しい」`10.5`の`tax`と共に保存されます。 + +## `PATCH`による部分的な更新 + +また、HTTPの`PATCH`操作でデータを*部分的に*更新することもできます。 + +つまり、更新したいデータだけを送信して、残りはそのままにしておくことができます。 + +!!! Note "備考" + `PATCH`は`PUT`よりもあまり使われておらず、知られていません。 + + また、多くのチームは部分的な更新であっても`PUT`だけを使用しています。 + + **FastAPI** はどんな制限も課けていないので、それらを使うのは **自由** です。 + + しかし、このガイドでは、それらがどのように使用されることを意図しているかを多かれ少なかれ、示しています。 + +### Pydanticの`exclude_unset`パラメータの使用 + +部分的な更新を受け取りたい場合は、Pydanticモデルの`.dict()`の`exclude_unset`パラメータを使用すると非常に便利です。 + +`item.dict(exclude_unset=True)`のように。 + +これにより、`item`モデルの作成時に設定されたデータのみを持つ`dict`が生成され、デフォルト値は除外されます。 + +これを使うことで、デフォルト値を省略して、設定された（リクエストで送られた）データのみを含む`dict`を生成することができます: + +```Python hl_lines="34" +{!../../../docs_src/body_updates/tutorial002.py!} +``` + +### Pydanticの`update`パラメータ + +ここで、`.copy()`を用いて既存のモデルのコピーを作成し、`update`パラメータに更新するデータを含む`dict`を渡すことができます。 + +`stored_item_model.copy(update=update_data)`のように: + +```Python hl_lines="35" +{!../../../docs_src/body_updates/tutorial002.py!} +``` + +### 部分的更新のまとめ + +まとめると、部分的な更新を適用するには、次のようにします: + +* (オプションで)`PUT`の代わりに`PATCH`を使用します。 +* 保存されているデータを取得します。 +* そのデータをPydanticモデルにいれます。 +* 入力モデルからデフォルト値を含まない`dict`を生成します（`exclude_unset`を使用します）。 + * この方法では、モデル内のデフォルト値ですでに保存されている値を上書きするのではなく、ユーザーが実際に設定した値のみを更新することができます。 +* 保存されているモデルのコピーを作成し、受け取った部分的な更新で属性を更新します（`update`パラメータを使用します）。 +* コピーしたモデルをDBに保存できるものに変換します（例えば、`jsonable_encoder`を使用します）。 + * これはモデルの`.dict()`メソッドを再度利用することに匹敵しますが、値をJSONに変換できるデータ型、例えば`datetime`を`str`に変換します。 +* データをDBに保存します。 +* 更新されたモデルを返します。 + +```Python hl_lines="30 31 32 33 34 35 36 37" +{!../../../docs_src/body_updates/tutorial002.py!} +``` + +!!! tip "豆知識" + 実際には、HTTPの`PUT`操作でも同じテクニックを使用することができます。 + + しかし、これらのユースケースのために作成されたので、ここでの例では`PATCH`を使用しています。 + +!!! note "備考" + 入力モデルがまだ検証されていることに注目してください。 + + そのため、すべての属性を省略できる部分的な変更を受け取りたい場合は、すべての属性をオプションとしてマークしたモデルを用意する必要があります（デフォルト値または`None`を使用して）。 + + **更新** のためのオプション値がすべて設定されているモデルと、**作成** のための必須値が設定されているモデルを区別するには、[追加モデル](extra-models.md){.internal-link target=_blank}で説明されている考え方を利用することができます。 diff --git a/docs/ja/mkdocs.yml b/docs/ja/mkdocs.yml index f8243528d..19b159492 100644 --- a/docs/ja/mkdocs.yml +++ b/docs/ja/mkdocs.yml @@ -61,6 +61,7 @@ nav: - tutorial/cookie-params.md - tutorial/header-params.md - tutorial/request-forms.md + - tutorial/body-updates.md - セキュリティ: - tutorial/security/first-steps.md - tutorial/cors.md