2021年7月22日木曜日

【和訳】Django Rest framework クイックスタート

【和訳】Django Rest Framework クイックスタート

【和訳】Django Rest Framework チュートリアル１：シリアル化

【和訳】Django Rest Framework チュートリアル２：リクエストとレスポンス

【和訳】Django Rest Framework チュートリアル３：クラスベースのビュー

【和訳】Django Rest Framework チュートリアル４：認証とアクセス許可

【和訳】Django Rest Framework チュートリアル５：リレーションとハイパーリンクされたAPI

【和訳】Django Rest Framework チュートリアル６：ビューセットとルーター


クイックスタート

DjangoのAdminユーザーがシステム内のUserとGroupを表示・編集できるように、単純なAPIを作成します。


プロジェクトの作成

tutorialという名前でDjangoプロジェクトを新規作成し、quickstartと言う名前で新規appを作成します。

# プロジェクトディレクトリを作成
mkdir tutorial
cd tutorial

# 仮想環境の構築（ローカルでパッケージの依存性を分離するため）
python3 -m venv env
source env/bin/activate  # Windows では、`env\Scripts\activate`をタイプする

# pipで仮想環境内にDjangoとDjango REST frameworkをインストールする
pip install django
pip install djangorestframework

# プロジェクトとアプリを作成する
django-admin startproject tutorial .  # 最後のドットを忘れずに
cd tutorial
django-admin startapp quickstart
cd ..

プロジェクトのファイル構成は次のようになります。

$ pwd
<some path>/tutorial
$ find .
.
./manage.py
./tutorial
./tutorial/__init__.py
./tutorial/quickstart
./tutorial/quickstart/__init__.py
./tutorial/quickstart/admin.py
./tutorial/quickstart/apps.py
./tutorial/quickstart/migrations
./tutorial/quickstart/migrations/__init__.py
./tutorial/quickstart/models.py
./tutorial/quickstart/tests.py
./tutorial/quickstart/views.py
./tutorial/settings.py
./tutorial/urls.py
./tutorial/wsgi.py

アプリケーションがプロジェクトディレクトリ内に作成されているのは不思議に感じるかもしれません。プロジェクトの名前空間を使用すれば、外部モジュールとの名前の衝突を回避できます（本チュートリアルでは説明しません）。

次に、データベースの初回同期を行います。

python manage.py migrate

名前がadmin、パスワードがpassword123スーパーユーザーを作成します。
本チュートリアルの後半では、このユーザーでログインします。

python manage.py createsuperuser --email admin@example.com --username admin

データベースを設定し、最初のユーザーが作成され、準備が整ったら、アプリのディレクトリを開き、コーディングを行っていきましょう。


シリアライザー

最初に、いくつかのシリアライザーを定義します。
tutorial/quickstart/serializers.pyという名前で新規モジュールを作成しましょう。
これは、データを表現するために使用します。

from django.contrib.auth.models import User, Group
from rest_framework import serializers


class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups']


class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

ここではHyperlinkedModelSerializerを用いて、ハイパーリンクのリレーションを使用しています。
主キーやその他のさまざまなリレーションを使用することもできます。
ですが、ハイパーリンクは優れたRESTful設計なので、本チュートリアルではハイパーリンクのリレーションを使用します。


ビュー

続いて、いくつかのビューを書きましょう。
tutorial/quickstart/views.pyを開いて、次の内容を入力します。

from django.contrib.auth.models import User, Group
from rest_framework import viewsets
from rest_framework import permissions
from tutorial.quickstart.serializers import UserSerializer, GroupSerializer


class UserViewSet(viewsets.ModelViewSet):
    """
    APIのエンドポイント：userの表示と編集を許可する
    """
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]


class GroupViewSet(viewsets.ModelViewSet):
    """
    APIのエンドポイント：groupの表示と編集を許可する
    """
    queryset = Group.objects.all()
    serializer_class = GroupSerializer
    permission_classes = [permissions.IsAuthenticated]

ここでは、複数のビューを作成するのではなく、すべての共通動作をViewSetsと呼ばれるクラスにひとまとめにします。

もちろん、必要に応じて、各動作を個別のビューに簡単に分割することもできます。
ですが、ビューセットを使用すると、ビューのロジックが適切に整理され、非常に簡潔になります。


URL

では、APIのURLを紐づけしましょう。
tutorial/urls.pyに以下を記述します。

from django.urls import include, path
from rest_framework import routers
from tutorial.quickstart import views

router = routers.DefaultRouter()
router.register(r'users', views.UserViewSet)
router.register(r'groups', views.GroupViewSet)

# 自動URLルーティングを用いて、APIを紐づけしましょう。
# そして、APIをブラウザから閲覧できるようにするため、ログインURLをincludeします。
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

ここでは、ビューの代わりにビューセットを使用しているので、ビューセットをルータークラスに登録するだけで、APIのURLconfが自動的に生成されます。

繰り返しになりますが、API URLを個別に制御したい場合は、通常のクラスベースのビューを使用し、URLconfを明示的に記述するだけです。

最後に、ここでは、ブラウザから閲覧可能なAPIで使用するために、デフォルトのログインビューとログアウトビューを含んでいます。これは必須項目ではありませんが、あなたがAPIでの認証を必要としており、ブラウザから閲覧可能なAPIを使用したい場合に役立ちます。


ページネーション

ページネーションを使用すると、ページごとに返されるオブジェクトの数を制御できます。
有効にするには、tutorial/settings.pyに以下の内容を追加します。

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}


設定

tutorial/settings.pyのINSTALLED_APPSに'rest_framework'を追加します。

INSTALLED_APPS = [
    ...
    'rest_framework',
]

以上で完成です。


APIのテスト

これで構築したAPIをテストする準備が整いました。
コマンドラインからサーバーを起動してみましょう。

python manage.py runserver

APIには、curlのようなコマンドラインツールを用いてアクセスできます。

bash: curl -H 'Accept: application/json; indent=4' -u admin:password123 http://127.0.0.1:8000/users/
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/1/",
            "username": "admin"
        },
        {
            "email": "tom@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

あるいは、httpieコマンドラインツールを使用しても構いません。

bash: http -a admin:password123 http://127.0.0.1:8000/users/

HTTP/1.1 200 OK
...
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "admin@example.com",
            "groups": [],
            "url": "http://localhost:8000/users/1/",
            "username": "paul"
        },
        {
            "email": "tom@example.com",
            "groups": [],
            "url": "http://127.0.0.1:8000/users/2/",
            "username": "tom"
        }
    ]
}

あるいは、ブラウザから直接、http://127.0.0.1:8000/users/にアクセスすることもできます。

クイックスタート画像

ブラウザからアクセスする場合は、右上隅のボタンを使用してログインしてください。

素晴らしい。簡単でしたね！

RESTフレームワークがどのように組み合わさっているか、もっと深く理解したいなら、チュートリアルに進むか、APIガイドを参照を開始してください。

時刻:
ラベル: , , , ,

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)

【和訳】Django Rest Framework 目次

目次 【和訳】Django Rest Framework クイックスタート 【和訳】Django Rest Framework チュートリアル１：シリアル化 【和訳】Django Rest Framework チュートリアル２：リクエストとレスポンス 【和訳】Django Res...