Serializer fields

각각의 폼 클래스의 필드는 데이터의 유효성을 검사하는 것뿐만 아니라 데이터를 "클린징"하여 일관된 형식으로 정규화하는 역할을 합니다.

— Django 문서

직렬화기 필드는 원시 값과 내부 데이터 유형 간의 변환을 처리합니다. 또한 입력 값의 유효성을 검증하고, 부모 객체에서 값을 검색하거나 설정하는 데 사용됩니다.

참고: 직렬화기 필드는 fields.py에서 선언되지만 관례적으로 from rest_framework import serializers를 사용하여 가져오고 필드를 serializers.<FieldName> 형식으로 참조하는 것이 좋습니다.

핵심 인수

각 직렬화기 필드 클래스 생성자는 적어도 다음 인수를 가져야 합니다. 일부 필드 클래스는 추가로 필드별 인수를 가져올 수 있지만 다음은 항상 허용되어야 합니다.

read_only

읽기 전용 필드는 API 출력에 포함되지만 생성 또는 업데이트 작업 중에는 입력에 포함되지 않아야 합니다. 직렬화기 입력에 잘못 포함된 read_only 필드는 무시됩니다.

이 값을 True로 설정하여 표현을 직렬화하는 동안 필드가 사용되지만 역직렬화 중에는 인스턴스 생성 또는 업데이트 중에 사용되지 않도록 합니다.

기본값은 False입니다.

write_only

이 값을 True로 설정하여 인스턴스를 업데이트하거나 생성할 때 필드를 사용할 수 있지만 직렬화된 표현을 생성하는 동안에는 포함되지 않도록 합니다.

기본값은 False입니다.

required

일반적으로 필드가 역직렬화 중에 제공되지 않으면 오류가 발생합니다. 이 필드가 역직렬화 중에 필요하지 않은 경우 false로 설정합니다.

이 값을 False로 설정하면 객체 속성 또는 사전 키를 직렬화된 인스턴스에서 생략할 수 있게 됩니다. 키가 없으면 출력 표현에 포함되지 않습니다.

기본값은 True입니다. Model Serializer를 사용하는 경우 필드에서 blank=True 또는 default 또는 null=True를 지정한 경우 기본값은 False가 됩니다.

default

설정하면 입력 값이 제공되지 않을 경우 필드에 사용할 기본값을 지정합니다. 기본값이 설정되지 않은 경우 기본 동작은 속성을 전혀 채우지 않는 것입니다.

default는 부분 업데이트 작업 중에 적용되지 않습니다. 부분 업데이트 경우 들어오는 데이터에서 제공된 필드만 검증된 값이 반환됩니다.

함수 또는 다른 호출 가능한 것으로 설정할 수 있으며 사용될 때마다 해당 값을 평가합니다. 호출 시 인수를 받지 않습니다. 호출 가능한 개체에 requires_context = True 속성이 있는 경우 직렬화기 필드가 인수로 전달됩니다.

예를 들어:

class CurrentUserDefault:
    """
    직렬화기 필드의 `default=...` 값으로 적용할 수 있습니다.
    현재 사용자를 반환합니다.
    """
    requires_context = True

    def __call__(self, serializer_field):
        return serializer_field.context['request'].user

인스턴스를 직렬화할 때 객체 속성 또는 사전 키가 인스턴스에 없는 경우 기본값이 사용됩니다.

default 값을 설정하면 필드가 필수가 아님을 의미합니다. default 및 required 키워드 인수를 모두 포함하는 것은 잘못된 동작이며 오류가 발생합니다.

allow_null

일반적으로 직렬화기 필드에 None이 전달되면 오류가 발생합니다. None을 유효한 값으로 간주해야 하는 경우 이 키워드 인수를 True로 설정합니다.

allow_null=True로 설정하는 것은 직렬화 출력에 대한 기본값이 null인 것을 의미하지만 입력 역직렬화에 대한 기본값은 의미하지 않습니다.

기본값은 False입니다.

source

필드를 채우는 데 사용될 속성의 이름입니다. URLField(source='get_absolute_url')처럼 self 인수만 가져야 하는 메서드이거나 EmailField(source='user.email')처럼 점 표기법을 사용하여 속성을 탐색할 수 있습니다.

점 표기법으로 필드를 직렬화하는 경우 속성 탐색 중에 어떤 객체가 없거나 비어 있는 경우 default 값을 제공해야 할 수 있습니다. 관계형 orm 모델에 액세

스하는 경우 소스 속성을 사용할 때 가능한 n+1 문제에 주의하십시오. 예를 들어:

class CommentSerializer(serializers.Serializer):
    email = serializers.EmailField(source="user.email")

위의 예시는 사용자 객체가 프리페치되지 않은 경우 데이터베이스에서 사용자 객체를 가져와야 합니다. 그렇지 않은 경우, 적절한 prefetch_related 및 select_related 메서드를 사용하도록 주의하십시오. 이에 대한 자세한 내용은 Django 문서를 참조하십시오.

값 source='*'는 특별한 의미를 가지며 전체 객체를 필드로 전달해야 함을 나타냅니다. 이것은 중첩된 표현을 생성하거나 출력 표현을 결정하기 위해 완전한 객체에 액세스해야 하는 필드에 유용할 수 있습니다.

기본값은 필드의 이름입니다.

validators

수신 필드 입력에 적용할 유효성 검사기 함수의 목록입니다. 이 함수는 일반적으로 serializers.ValidationError을 발생시키지만 Django의 내장 ValidationError은 Django 코드베이스나 타사 Django 패키지에서 정의된 유효성 검사기와의 호환성을 위해 지원됩니다.

error_messages

오류 코드와 오류 메시지의 사전입니다.

label

HTML 폼 필드 또는 기타 기술 요소에서 필드의 이름으로 사용될 수 있는 짧은 텍스트 문자열입니다.

help_text

HTML 폼 필드 또는 기타 설명 요소에서 필드에 대한 설명으로 사용될 수 있는 텍스트 문자열입니다.

initial

HTML 폼 필드의 값을 사전 채우기하는 데 사용할 값입니다. 호출 가능한 것처럼 일반 Django Field와 마찬가지로 호출 가능한 값을 전달할 수 있습니다.

import datetime
from rest_framework import serializers

class ExampleSerializer(serializers.Serializer):
    day = serializers.DateField(initial=datetime.date.today)

style

렌더러가 필드를 어떻게 렌더링해야 하는지를 제어하는 데 사용할 수 있는 키-값 쌍 사전입니다.

여기에는 'input_type' 및 'base_template'의 두 가지 예가 있습니다:

# 입력에 <input type="password">를 사용합니다.
password = serializers.CharField(
    style={'input_type': 'password'}
)

# select 입력 대신 라디오 입력을 사용합니다.
color_channel = serializers.ChoiceField(
    choices=['red', 'green', 'blue'],
    style={'base_template': 'radio.html'}
)

자세한 내용은 HTML 및 폼 문서를 참조하십시오.

부울 필드

BooleanField

부울 표현입니다.

HTML 인코딩된 폼 입력을 사용할 때 빈 값을 생략하면 항상 필드를 False로 설정한 것으로 간주됩니다. 심지어 default=True 옵션이 지정된 경우에도 마찬가지입니다. 이는 HTML 체크박스 입력이 값을 생략하여 체크되지 않은 상태를 나타내기 때문입니다. 따라서 REST 프레임워크는 생략을 빈 체크박스 입력으로 처리합니다.

Django 2.1에서 models.BooleanField에서 blank 인수가 제거되었습니다. Django 2.1 이전에는 models.BooleanField 필드가 항상 blank=True였습니다. 따라서 Django 2.1 이후에는 serializers.BooleanField 인스턴스가 required 인수 없이 생성될 것이며 (required=True와 동등함) 이전 버전의 Django에서는 BooleanField 인스턴스가 required=False 옵션을 가진 상태로 생성될 것입니다. 이 동작을 수동으로 제어하려면 직렬화기 클래스에서 명시적으로 BooleanField를 선언하거나 extra_kwargs 옵션을 사용하여 required 플래그를 설정하십시오.

django.db.models.fields.BooleanField에 해당합니다.

시그니처: BooleanField()

문자열 필드

CharField

텍스트 표현입니다. 텍스트가 max_length보다 짧거나 min_length보다 길도록 옵션으로 유효성을 검사합니다.

django.db.models.fields.CharField 또는 django.db.models.fields.TextField에 해당합니다.

시그니처: CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)

• max_length: 입력에 포함될 수 있는 최대 문자 수를 검증합니다.

• min_length: 입력에 포함될 수 있는 최소 문자 수를 검증합니다.

• allow_blank: True로 설정하면 빈 문자열을 유효한 값으로 간주합니다. False로 설정하면 빈 문자열이 유효하지 않으며 유효성 검사 오류가 발생합니다.

  기본값은 False입니다.

• trim_whitespace: True로 설정하면 앞뒤의 공백이 제거됩니다. 기본값은 True입니다.

문자열 필드에는 allow_null 옵션이 문자열에도 사용 가능하지만 allow_blank를 선호합니다. allow_blank=True 및 allow_null=True 모두 설정하는 것은 문자열 표현에 대해 두 가지 다른 유형의 빈 값이 허용된다는 것을 의미합니다. 이로 인해 데이터 일관성 및 애플리케이션 버그의 가능성이 증가할 수 있으므로 사용을 권장하지 않습니다.

EmailField

텍스트 표현으로, 텍스트가 유효한 이메일 주소인지 검증합니다.

django.db.models.fields.EmailField에 해당합니다.

시그니처: EmailField(max_length=None, min_length=None, allow_blank=False)

RegexField

주어진 값을 특정 정규식과 일치하도록 검증하는 텍스트 표현입니다.

django.forms.fields.RegexField에 해당합니다.

시그니처: RegexField(regex, max_length=None, min_length=None, allow_blank=False)

필수인 regex 인수는 문자열이나 컴파일된 파이썬 정규식 객체일 수 있습니다.

유효성 검사에는 Django의 django.core.validators.RegexValidator를 사용합니다.

SlugField

입력을 [a-zA-Z0-9_-]+ 패턴과 일치하도록 검증하는 RegexField입니다.

django.db.models.fields.SlugField에 해당합니다.

시그니처: SlugField(max_length=50, min_length=None, allow_blank=False)

URLField

URL 일치 패턴에 입력을 검증하는 RegexField입니다. 형식이 http://<host>/<path>인 완전한 URL을 기대합니다.

django.db.models.fields.URLField에 해당합니다. 검증에는 Django의 django.core.validators.URLValidator를 사용합니다.

시그니처: URLField(max_length=200, min_length=None, allow_blank=False)

UUIDField

입력이 유효한 UUID 문자열인지 확인하는 필드입니다. to_internal_value 메서드는 uuid.UUID 인스턴스를 반환합니다. 출력 시에는 교차선 문자 포함된 규범적 형식의 문자열을 반환합니다. 예를 들어:

"de305d54-75b4-431b-adb2-eb6b9e546013"

시그니처: UUIDField(format='hex_verbose')

• format: uuid 값의 표현 형식을 결정합니다.

  • 'hex_verbose': 하이픈을 포함한 규범적 16진수 표현, 예: "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
  • 'hex': 하이픈이 없는 간결한 16진수 표현, 예: "5ce0e9a55ffa654bcee01238041fb31a"
  • 'int': 128비트 정수 표현, 예: "123456789012312313134124512351145145114"
  • 'urn': RFC 4122 URN 표현, 예: "urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" format 매개변수 변경은 표현값에만 영향을 미칩니다. 모든 형식은 to_internal_value에서 허용됩니다.

FilePathField

특정 디렉토리의 파일 이름으로 제한된 선택지를 가지는 필드입니다.

django.forms.fields.FilePathField에 해당합니다.

시그니처: FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)

• path - 이 FilePathField가 선택지를 가져올 디렉토리의 절대 파일 시스템 경로입니다.
• match - 파일 이름을 필터링하는 데 사용되는 정규식 문자열입니다.
• recursive - 경로의 모든 하위 디렉토리를 포함해야 하는지 여부를 지정합니다. 기본값은 False입니다.
• allow_files - 지정된 위치의 파일을 포함해야 하는지 여부를 지정합니다. 기본값은 True입니다. 이 값 또는 allow_folders 중 하나는 반드시 True여야 합니다.
• allow_folders - 지정된 위치의 폴더를 포함해야 하는지 여부를 지정합니다. 기본값은 False입니다. 이 값 또는 allow_files 중 하나는 반드시 True여야 합니다.

IPAddressField

유효한 IPv4 또는 IPv6 문자열인지 확인하는 필드입니다.

django.forms.fields.IPAddressField와 django.forms.fields.GenericIPAddressField에 해당합니다.

시그니처: IPAddressField(protocol='both', unpack_ipv4=False, **options)

• protocol - 유효한 입력을 지정한 프로토콜로 제한합니다. 허용되는 값은 'both' (기본값), 'IPv4', 'IPv6'입니다. 대/소문자를 구분하지 않습니다.
• unpack_ipv4 - ::ffff:192.0.2.1과 같은 IPv4 매핑 주소를 풀어서 반환해야 하는지 여부를 지정합니다. 이 옵션이 활성화된 경우 해당 주소는 192.0.2.1로 풀리게 됩니다. 기본값은 비활성화되어 있습니다. 프로토콜이 'both'로 설정된 경우에만 사용할 수 있습니다.

숫자 필드

IntegerField

정수 표현입니다.

django.db.models.fields.IntegerField, django.db.models.fields.SmallIntegerField, django.db.models.fields.PositiveIntegerField, django.db.models.fields.PositiveSmallIntegerField에 해당합니다.

시그니처: IntegerField(max_value=None, min_value=None)

• max_value - 제공된 숫자가 이 값을 초과하지 않도록 유효성을 검사합니다.
• min_value - 제공된 숫자가 이 값 미만이 되지 않도록 유효성을 검사합니다.

FloatField

부동 소수점 표현입니다.

django.db.models.fields.FloatField에 해당합니다.

시그니처: FloatField(max_value=None, min_value=None)

• max_value - 제공된 숫자가 이 값을 초과하지 않도록 유효성을 검사합니다.
• min_value - 제공된 숫자가 이 값 미만이 되지 않도록 유효성을 검사합니다.

DecimalField

Decimal 인스턴스로 표현되는 십진수 표현입니다.

django.db.models.fields.DecimalField에 해당합니다.

시그니처: DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)

• max_digits - 숫자에서 허용되는 최대 자릿수입니다. None이거나 decimal_places보다 크거나 같은 정수여야 합니다.
• decimal_places - 숫자와 함께 저장될 소수 자릿수입니다.
• coerce_to_string - 표현값에 대해 문자열 값을 반환해야 하는 경우 True로 설정하거나, Decimal 객체를 반환해야 하는 경우 False로 설정합니다. 기본값은 COERCE_DECIMAL_TO_STRING 설정 키와 동일한 값을 가지며, 해당 설정 키가 오버라이드되지 않은 경우에는 True입니다. 직렬화기에서 Decimal 객체가 반환되면 최종 출력 형식은 렌더러에 의해 결정됩니다. localize 설정이 True로 설정된 경우 값이 강제로 True가 됩니다.
• max_value - 제공된 숫자가 이 값을 초과하지 않도록 유효성을 검사합니다.
• min_value - 제공된 숫자가 이 값 미만이 되지 않도록 유효성을 검사합니다.
• localize - 현재 로케일을 기반으로 입력 및 출력을 지역화하려면 True로 설정합니다. 이 경우 출력 형식은 렌더러에 의해 결정되며 localize가 설정되면 coerce_to_string이 자동으로 True로 설정됩니다. 기본값은 False입니다. 데이터 포맷팅은 설정 파일에서 USE_L10N=True로 설정한 경우에 활성화됩니다.
• rounding - 구성된 정밀도에 대한 양자화 시 사용되는 반올림 모드를 설정합니다. 유효한 값은 decimal 모듈의 반올림 모드입니다. 기본값은 None입니다.

예를 들어, 최대 2자리 소수점을 갖는 숫자를 최대 999

까지 유효성을 검사하려면 다음과 같이 사용합니다:

serializers.DecimalField(max_digits=5, decimal_places=2)

그리고 최대 10자리 소수점을 갖는 숫자를 10진수로 유효성을 검사하려면:

serializers.DecimalField(max_digits=19, decimal_places=10)

날짜 및 시간 필드

DateTimeField

날짜와 시간 표현입니다.

django.db.models.fields.DateTimeField에 해당합니다.

시그니처: DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None, default_timezone=None)

• format - 출력 형식을 나타내는 문자열입니다. 지정되지 않은 경우, 이 값은 DATETIME_FORMAT 설정 키와 동일한 값을 가지며 설정되지 않은 경우 'iso-8601'로 설정됩니다. 문자열 형식을 설정하면 to_representation 반환 값이 문자열 출력으로 강제 변환됩니다. 형식 문자열에 대한 설명은 아래에서 확인할 수 있습니다. 이 값을 None으로 설정하면 to_representation에서 Python datetime 객체가 반환되며 렌더러가 결정하는대로 datetime 인코딩이 수행됩니다.
• input_formats - 날짜를 구문 분석하는 데 사용될 수 있는 입력 형식을 나타내는 문자열 목록입니다. 지정되지 않은 경우, DATE_INPUT_FORMATS 설정이 사용되며 기본값은 ['iso-8601']입니다.
• default_timezone - 시간대를 나타내는 tzinfo 서브클래스 (zoneinfo 또는 pytz)입니다. 지정되지 않았고 USE_TZ 설정이 활성화된 경우, 기본값은 현재 시간대로 설정됩니다. USE_TZ가 비활성화된 경우, datetime 객체가 무작위로 됩니다.

DateTimeField 형식 문자열.

형식 문자열은 Python strftime 형식 또는 특별한 문자열 'iso-8601'일 수 있습니다. 이는 ISO 8601 스타일의 datetime을 나타냅니다. (예: '2013-01-29T12:34:56.000000Z')

값이 None으로 설정된 경우, datetime 객체가 to_representation에 의해 반환되며 최종 출력 표현은 렌더러 클래스에 의해 결정됩니다.

auto_now 및 auto_now_add 모델 필드.

ModelSerializer 또는 HyperlinkedModelSerializer를 사용할 때, auto_now=True 또는 auto_now_add=True 속성이 있는 모델 필드는 기본적으로 read_only=True인 직렬화 필드를 사용합니다.

이 동작을 재정의하려면 직렬화기에서 명시적으로 DateTimeField를 선언해야 합니다. 예를 들어:

class CommentSerializer(serializers.ModelSerializer):
    created = serializers.DateTimeField()

    class Meta:
        model = Comment

DateField

날짜 표현입니다.

django.db.models.fields.DateField에 해당합니다.

시그니처: DateField(format=api_settings.DATE_FORMAT, input_formats=None)

• format - 출력 형식을 나타내는 문자열입니다. 지정되지 않은 경우, 이 값은 DATE_FORMAT 설정 키와 동일한 값을 가지며 설정되지 않은 경우 'iso-8601'로 설정됩니다. 문자열 형식을 설정하면 to_representation 반환 값이 문자열 출력으로 강제 변환됩니다. 형식 문자열에 대한 설명은 아래에서 확인할 수 있습니다. 이 값을 None으로 설정하면 to_representation에서 Python date 객체가 반환되며 렌더러가 결정하는대로 날짜 인코딩이 수행됩니다.
• input_formats - 날짜를 구문 분석하는 데 사용될 수 있는 입력 형식을 나타내는 문자열 목록입니다. 지정되지 않은 경우, DATE_INPUT_FORMATS 설정이 사용되며 기본값은 ['iso-8601']입니다.

DateField 형식 문자열

형식 문자열은 Python strftime 형식 또는 특별한 문자열 'iso-8601'일 수 있습니다. 이는 ISO 8601 스타일의 날짜를 나타냅니다. (예: '2013-01-29')

TimeField

시간 표현입니다.

django.db.models.fields.TimeField에 해당합니다.

시그니처: TimeField(format=api_settings.TIME_FORMAT, input_formats=None)

• format - 출력 형식을 나타내는 문자열입니다. 지정되지 않은 경우, 이 값은 TIME_FORMAT 설정 키와 동일한 값을 가지며 설정되지 않은 경우 'iso-8601'로 설정됩니다. 문자열 형식을 설정하면 `to

_representation반환 값이 문자열 출력으로 강제 변환됩니다. 형식 문자열에 대한 설명은 아래에서 확인할 수 있습니다. 이 값을None으로 설정하면 to_representation에서 Python time` 객체가 반환되며 렌더러가 결정하는대로 시간 인코딩이 수행됩니다.

• input_formats - 날짜를 구문 분석하는 데 사용될 수 있는 입력 형식을 나타내는 문자열 목록입니다. 지정되지 않은 경우, TIME_INPUT_FORMATS 설정이 사용되며 기본값은 ['iso-8601']입니다.

TimeField 형식 문자열

형식 문자열은 Python strftime 형식 또는 특별한 문자열 'iso-8601'일 수 있습니다. 이는 ISO 8601 스타일의 시간을 나타냅니다. (예: '12:34:56.000000')

DurationField

기간 표현입니다. django.db.models.fields.DurationField에 해당합니다.

이러한 필드의 validated_data에는 datetime.timedelta 인스턴스가 포함됩니다. 표현은 이 형식을 따르는 문자열입니다: '[DD] [HH:[MM:]]ss[.uuuuuu]'.

시그니처: DurationField(max_value=None, min_value=None)

• max_value - 제공된 기간이 이 값을 초과하지 않도록 유효성을 검사합니다.
• min_value - 제공된 기간이 이 값 미만이 되지 않도록 유효성을 검사합니다.

선택 필드

ChoiceField

일정한 선택지 집합 중에서 값을 받아들일 수 있는 필드입니다.

ModelSerializer에서 해당 모델 필드에 choices=… 인자가 포함된 경우, 필드를 자동으로 생성하는 데 사용됩니다.

시그니처: ChoiceField(choices)

• choices - 유효한 값의 목록 또는 (key, display_name) 튜플의 목록입니다.
• allow_blank - True로 설정하면 빈 문자열을 유효한 값으로 간주합니다. False로 설정하면 빈 문자열이 유효하지 않으며 유효성 검사 오류를 발생시킵니다. 기본값은 False입니다.
• html_cutoff - 설정된 경우, HTML 선택 목록에서 표시되는 최대 선택 수입니다. 아주 큰 선택 옵션을 가진 자동 생성된 ChoiceField가 템플릿의 렌더링을 방해하지 않도록 하려면 사용할 수 있습니다. 기본값은 None입니다.
• html_cutoff_text - 설정된 경우, HTML 선택 목록에서 최대 항목 수가 자르게 되면 텍스트 표시기를 표시합니다. 기본값은 "More than {count} items…"입니다.

allow_blank과 allow_null 옵션은 모두 ChoiceField에서 유효한 옵션입니다. 그러나 텍스트 선택의 경우 allow_blank를, 숫자나 기타 비텍스트 선택의 경우 allow_null을 사용하는 것이 좋습니다.

MultipleChoiceField

일정한 선택지 집합 중에서 선택한 값의 집합을 받아들일 수 있는 필드입니다. 단일 필수 인자를 받습니다. to_internal_value는 선택된 값을 포함하는 set을 반환합니다.

시그니처: MultipleChoiceField(choices)

• choices - 유효한 값의 목록 또는 (key, display_name) 튜플의 목록입니다.
• allow_blank - True로 설정하면 빈 문자열을 유효한 값으로 간주합니다. False로 설정하면 빈 문자열이 유효성 검사 오류를 발생시킵니다. 기본값은 False입니다.
• html_cutoff - 설정된 경우, HTML 선택 목록에서 표시되는 최대 선택 수입니다. 아주 큰 선택 옵션을 가진 자동 생성된 ChoiceField가 템플릿의 렌더링을 방해하지 않도록 하려면 사용할 수 있습니다. 기본값은 None입니다.
• html_cutoff_text - 설정된 경우, HTML 선택 목록에서 최대 항목 수가 자르게 되면 텍스트 표시기를 표시합니다. 기본값은 "More than {count} items…"입니다.

ChoiceField와 마찬가지로 allow_blank와 allow_null 옵션이 모두 유효하지만, 텍스트 선택에는 allow_blank, 숫자나 기타 비텍스트 선택에는 allow_null을 사용하는 것이 좋습니다.

파일 업로드 필드

파서 및 파일 업로드.

FileField 및 ImageField 클래스는 오직 MultiPartParser 또는 FileUploadParser와 함께 사용하기에 적합합니다. 대부분의 파서, 예를 들어 JSON과 같은 파서는 파일 업로드를 지원하지 않습니다. Django의 일반적인 FILE_UPLOAD_HANDLERS가 업로드된 파일을 처리하는 데 사용됩니다.

FileField

파일 표현입니다. Django의 표준 FileField 유효성 검사를 수행합니다.

django.forms.fields.FileField와 대응합니다.

시그니처: FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

• max_length - 파일 이름의 최대 길이를 지정합니다.
• allow_empty_file - 빈 파일이 허용되는지 여부를 지정합니다.
• use_url - True로 설정되면 URL 문자열 값이 출력 표현에 사용됩니다. False로 설정되면 파일 이름 문자열 값이 출력 표현에 사용됩니다. 기본값은 UPLOADED_FILES_USE_URL 설정 키의 값이며, 설정되지 않은 경우 True입니다.

ImageField

이미지 표현입니다. 업로드된 파일 내용을 이미지 형식과 일치하도록 유효성 검사합니다.

django.forms.fields.ImageField와 대응합니다.

시그니처: ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

• max_length - 파일 이름의 최대 길이를 지정합니다.
• allow_empty_file - 빈 파일이 허용되는지 여부를 지정합니다.
• use_url - True로 설정되면 URL 문자열 값이 출력 표현에 사용됩니다. False로 설정되면 파일 이름 문자열 값이 출력 표현에 사용됩니다. 기본값은 UPLOADED_FILES_USE_URL 설정 키의 값이며, 설정되지 않은 경우 True입니다.

Pillow 패키지 또는 PIL 패키지가 필요합니다. Pillow 패키지를 권장하며, PIL은 더 이상 활발히 유지되지 않습니다.

복합 필드

ListField

객체 목록을 유효성 검사하는 필드 클래스입니다.

시그니처: ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None, max_length=None)

• child - 목록의 객체를 유효성 검사하는 데 사용될 필드 인스턴스입니다. 이 인수가 제공되지 않으면 목록의 객체가 유효성 검사되지 않습니다.
• allow_empty - 빈 목록이 허용되는지 여부를 지정합니다.
• min_length - 목록이 이 수 이상의 요소를 포함하도록 유효성 검사합니다.
• max_length - 목록이 이 수 이하의 요소를 포함하도록 유효성 검사합니다.

예를 들어 정수 목록을 유효성 검사하려면 다음과 같이 할 수 있습니다:

scores = serializers.ListField(
   child=serializers.IntegerField(min_value=0, max_value=100)
)

ListField 클래스는 재사용 가능한 목록 필드 클래스를 작성하는 데 사용할 수 있는 선언적 스타일도 지원합니다.

class StringListField(serializers.ListField):
    child = serializers.CharField()

이제 사용자 지정 StringListField 클래스를 애플리케이션 전체에서 재사용할 수 있으며 해당 필드에 대해 별도의 child 인수를 제공할 필요가 없습니다.

DictField

객체의 딕셔너리를 유효성 검사하는 필드 클래스입니다. DictField의 키는 항상 문자열 값으로 가정됩니다.

시그니처: DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)

• child - 딕셔너리의 값을 유효성 검사하는 데 사용될 필드 인스턴스입니다. 이 인수가 제공되지 않으면 딕셔너리의 값이 유효성 검사되지 않습니다.
• allow_empty - 빈 딕셔너리가 허용되는지 여부를 지정합니다.

예를 들어 문자열에서 문자열로의 매핑을 유효성 검사하는 필드를 만들려면 다음과 같이 할 수 있습니다:

document = DictField(child=CharField())

ListField와 마찬가지로 선언적 스타일도 지원됩니다. 예를 들어:

class DocumentField(DictField):
    child = CharField()

HStoreField

Django의 postgres HStoreField와 호환되는 미리 구성된 DictField입니다.

시그니처: HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)

• child - 딕셔너리의 값을 유효성 검사하는 데 사용될 필드 인스턴스

입니다. 기본적으로 기본 자식 필드는 빈 문자열과 null 값을 모두 허용합니다.

• allow_empty - 빈 딕셔너리가 허용되는지 여부를 지정합니다.

참고로, 자식 필드는 hstore 확장이 값을 문자열로 저장하기 때문에 반드시 CharField의 인스턴스여야 합니다.

JSONField

들어오는 데이터 구조가 유효한 JSON 기본 자료형으로 구성되어 있는지 유효성 검사하는 필드 클래스입니다. 대안 이진 모드에서는 JSON으로 인코딩된 바이너리 문자열을 나타내고 유효성 검사합니다.

시그니처: JSONField(binary, encoder)

• binary - True로 설정되면 필드는 기본 자료 구조 대신 JSON 인코딩된 문자열을 출력 및 유효성 검사합니다. 기본값은 False입니다.
• encoder - 이 JSON 인코더를 입력 개체를 직렬화하는 데 사용합니다. 기본값은 None입니다.

기타 필드

ReadOnlyField

값을 수정하지 않고 필드의 값을 반환하는 필드 클래스입니다.

이 필드는 ModelSerializer에서 속성이 아닌 모델 필드와 관련된 필드 이름을 포함할 때 기본적으로 사용됩니다.

시그니처: ReadOnlyField()

예를 들어, has_expired가 Account 모델의 속성인 경우 다음과 같은 직렬화기는 자동으로 ReadOnlyField로 생성됩니다:

class AccountSerializer(serializers.ModelSerializer):
    class Meta:
        model = Account
        fields = ['id', 'account_name', 'has_expired']

HiddenField

사용자 입력을 기반으로 값을 가져오지 않고, 대신 기본 값 또는 호출 가능한 값에서 값을 가져오는 필드 클래스입니다.

시그니처: HiddenField()

예를 들어, 현재 시간을 항상 직렬화된 데이터의 일부로 제공하는 필드를 포함하려면 다음과 같이 사용할 수 있습니다:

modified = serializers.HiddenField(default=timezone.now)

HiddenField 클래스는 보통 일부 제공된 필드 값에 기반한 유효성 검사가 실행되어야 하지만 모든 필드를 최종 사용자에게 노출하고 싶지 않을 때 필요합니다.

HiddenField에 대한 추가 예제는 validators 문서를 참조하세요.

ModelField

임의의 모델 필드와 연결될 수 있는 일반적인 필드입니다. ModelField 클래스는 직렬화/역직렬화 작업을 관련된 모델 필드로 위임합니다. 이 필드를 사용하면 새로운 사용자 정의 직렬화기 필드를 생성하지 않고도 사용자 정의 모델 필드에 대한 직렬화기 필드를 만들 수 있습니다.

이 필드는 사용자 정의 모델 필드 클래스와 대응하기 위해 ModelSerializer에서 사용됩니다.

시그니처: ModelField(model_field=<Django ModelField instance>)

ModelField 클래스는 일반적으로 내부적으로 사용되도록 의도되었지만 필요한 경우 API에서 사용할 수 있습니다. ModelField를 올바르게 인스턴스화하려면 실제 모델에 연결된 필드를 전달해야 합니다. 예를 들어: ModelField(model_field=MyModel()._meta.get_field('custom_field'))

SerializerMethodField

읽기 전용 필드입니다. 연결된 직렬화기 클래스에서 메서드를 호출하여 값을 가져옵니다. 이를 사용하여 개체의 직렬화된 표현에 모든 유형의 데이터를 추가할 수 있습니다.

시그니처: SerializerMethodField(method_name=None)

• method_name - 호출할 직렬화기의 메서드 이름입니다. 이를 포함하지 않으면 기본값은 get_<field_name>입니다.

method_name 인수로 참조된 직렬화기 메서드는 하나의 인수(또한 self를 제외한)를 받아야 합니다. 이 인수는 직렬화 중인 개체입니다. 이 메서드는 객체의 직렬화된 표현에 포함할 내용을 반환해야 합니다. 예를 들어:

from django.contrib.auth.models import User
from django.utils.timezone import now
from rest_framework import serializers

class UserSerializer(serializers.ModelSerializer):
    days_since_joined = serializers.SerializerMethodField()

    class Meta:
        model = User
        fields = '__all__'

    def get_days_since_joined(self, obj):
        return (now() - obj.date_joined).days

사용자 정의 필드

사용자 정의 필드를 생성하려면 Field를 서브클래싱하고 .to_representation() 및/또는 .to_internal_value() 메서드 중 하나 또는 둘 모두를 오버라이드해야 합니다. 이 두 메서드는 초기 데이터 유형과 원시, 직렬화 가능한 데이터 유형 간의 변환에 사용됩니다. 원시 데이터 유형은 일반적으로 숫자, 문자열, 불리언

, date/time/datetime 또는 None일 수 있습니다. 또한 다른 원시 객체만을 포함하는 목록 또는 사전과 같은 객체일 수도 있습니다. 사용 중인 렌더러에 따라 다른 유형도 지원될 수 있습니다.

.to_representation() 메서드는 초기 데이터 유형을 원시, 직렬화 가능한 데이터 유형으로 변환하는 데 호출됩니다.

.to_internal_value() 메서드는 원시 데이터 유형을 내부 파이썬 표현으로 복원하는 데 호출됩니다. 이 메서드는 데이터가 잘못된 경우 serializers.ValidationError를 발생시켜야 합니다.

예제

기본 사용자 정의 필드

RGB 색상 값을 나타내는 클래스를 직렬화하는 예제를 살펴보겠습니다:

class Color:
    """
    RGB 색상 공간에서 표현된 색상입니다.
    """
    def __init__(self, red, green, blue):
        assert(red >= 0 and green >= 0 and blue >= 0)
        assert(red < 256 and green < 256 and blue < 256)
        self.red, self.green, self.blue = red, green, blue

class ColorField(serializers.Field):
    """
    Color 객체는 'rgb(#, #, #)' 표기법으로 직렬화됩니다.
    """
    def to_representation(self, value):
        return "rgb(%d, %d, %d)" % (value.red, value.green, value.blue)

    def to_internal_value(self, data):
        data = data.strip('rgb(').rstrip(')')
        red, green, blue = [int(col) for col in data.split(',')]
        return Color(red, green, blue)

기본적으로 필드 값은 객체의 속성에 매핑됩니다. 필드 값에 액세스하고 설정하는 방법을 사용자 정의하려면 .get_attribute()와/또는 .get_value()를 오버라이드해야 합니다.

예를 들어, 직렬화되는 개체의 클래스 이름을 나타내는 필드를 만들기 위해 다음과 같이 필드를 생성할 수 있습니다:

class ClassNameField(serializers.Field):
    def get_attribute(self, instance):
        # 필드 속성뿐만 아니라 객체 인스턴스를 `to_representation`에 전달합니다.
        return instance

    def to_representation(self, value):
        """
        값을 클래스 이름으로 직렬화합니다.
        """
        return value.__class__.__name__

검증 오류 발생

위의 ColorField 클래스는 현재 데이터 유효성 검사를 수행하지 않습니다. 잘못된 데이터를 나타내려면 다음과 같이 serializers.ValidationError을 발생시켜야 합니다.

def to_internal_value(self, data):
    if not isinstance(data, str):
        msg = '올바르지 않은 유형입니다. 문자열이 예상되었지만 %s을(를) 받았습니다.'
        raise ValidationError(msg % type(data).__name__)

    if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
        raise ValidationError('잘못된 형식입니다. `rgb(#,#,#)`가 예상되었습니다.')

    data = data.strip('rgb(').rstrip(')')
    red, green, blue = [int(col) for col in data.split(',')]

    if any([col > 255 or col < 0 for col in (red, green, blue)]):
        raise ValidationError('범위를 벗어난 값입니다. 0과 255 사이여야 합니다.')

    return Color(red, green, blue)

.fail() 메서드는 ValidationError을 발생시키는 바로가기로서, error_messages 사전에서 메시지 문자열을 가져옵니다. 예를 들어:

default_error_messages = {
    'incorrect_type': '올바르지 않은 유형입니다. 문자열이 예상되었지만 {input_type}을(를) 받았습니다.',
    'incorrect_format': '잘못된 형식입니다. `rgb(#,#,#)`가 예상되었습니다.',
    'out_of_range': '범위를 벗어난 값입니다. 0과 255 사이여야 합니다.'
}

def to_internal_value(self, data):
    if not isinstance(data, str):
        self.fail('incorrect_type', input_type=type(data).__name__)

    if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
        self.fail('incorrect_format')

    data = data.strip('rgb(').rstrip(')')
    red, green, blue = [int(col) for col in data.split(',')]

    if any([col > 255 or col < 0 for col in (red, green, blue)]):
        self.fail('out_of_range')

    return Color(red, green, blue)

이 스타일은 오류 메시지를 더 깨끗하게 유지하고 코드에서 분리하며, 선호되어야 합니다.

source='*' 사용

여기에서는 x_coordinate 및 y_coordinate 속성을 가진 플랫 DataPoint 모델의 예제를 살펴보겠습니다.

class DataPoint(models.Model):
    label = models.CharField(max_length=50)
    x_coordinate = models.SmallIntegerField()
    y_coordinate = models.SmallIntegerField()

사용자 정의 필드와 source='*'를 사용하여 좌표 쌍의 중첩 표현을 제공할 수 있습니다.

class CoordinateField(serializers.Field):

    def to_representation(self, value):
        ret = {
            "x": value.x_coordinate,
            "y": value.y_coordinate
        }
        return ret

    def to_internal_value(self, data):
        ret = {
            "x_coordinate": data["x"],
            "y_coordinate": data["y"],
        }
        return ret


class DataPointSerializer(serializers.ModelSerializer):
    coordinates = CoordinateField(source='*')

    class Meta:
        model = DataPoint
        fields = ['label', 'coordinates']

이 예제는 유효성 검사를 다루지 않습니다. 일부 이유 때문에 실제 프로젝트에서는 좌표 중첩을 더 나은 방식으로 처리하는 것이 좋을 수 있으며, 이는 두 개의 IntegerField 인스턴스를 사용하여 source가 해당 필드를 가리키는 중첩 직렬화기를 사용하여 처리할 수 있습니다.

그러나 이 예제의 주요 포인트는 다음과 같습니다.

• to_representation은 전체 DataPoint 객체를 전달받으며 원하는 출력으로 매핑해야 합니다.

  >>> instance = DataPoint(label='예제', x_coordinate=1, y_coordinate=2)
  >>> out_serializer = DataPointSerializer(instance)
  >>> out_serializer.data
  ReturnDict([('label', '예제'), ('coordinates', {'x': 1, 'y': 2})])

• 필드가 읽기 전용이 아닌 경우 to_internal_value은 대상 개체를 업데이트하기에 적합한 딕셔너리로 매핑해야 합니다. source='*'로 설정한 경우 to_internal_value에서 반환한 값은 단일 키가 아닌 루트 검증된 데이터 딕셔너리를 업데이트합니다.

  >>> data =
  
  {
  ...     "label": "두 번째 예제",
  ...     "coordinates": {
  ...         "x": 3,
  ...         "y": 4,
  ...     }
  ... }
  >>> in_serializer = DataPointSerializer(data=data)
  >>> in_serializer.is_valid()
  True
  >>> in_serializer.validated_data
  OrderedDict([('label', '두 번째 예제'),
               ('y_coordinate', 4),
               ('x_coordinate', 3)])

완전성을 위해 위에서 제안한 중첩 직렬화기 접근 방식으로 동일한 작업을 수행하는 코드도 확인해 보겠습니다.

class NestedCoordinateSerializer(serializers.Serializer):
    x = serializers.IntegerField(source='x_coordinate')
    y = serializers.IntegerField(source='y_coordinate')


class DataPointSerializer(serializers.ModelSerializer):
    coordinates = NestedCoordinateSerializer(source='*')

    class Meta:
        model = DataPoint
        fields = ['label', 'coordinates']

여기에서 대상 및 소스 속성 쌍 (x와 x_coordinate, y와 y_coordinate) 사이의 매핑은 IntegerField 선언에서 처리됩니다. source='*'는 우리의 NestedCoordinateSerializer에서 사용하는 것입니다.

새로운 DataPointSerializer도 사용자 정의 필드 접근 방식과 동일한 동작을 보여줍니다.

직렬화:

>>> out_serializer = DataPointSerializer(instance)
>>> out_serializer.data
ReturnDict([('label', '테스트'),
            ('coordinates', OrderedDict([('x', 1), ('y', 2)]))])

역직렬화:

>>> in_serializer = DataPointSerializer(data=data)
>>> in_serializer.is_valid()
True
>>> in_serializer.validated_data
OrderedDict([('label', '테스트 중'),
             ('x_coordinate', 3),
             ('y_coordinate', 4)])

그러나 내장된 유효성 검사도 무료로 제공됩니다.

>>> invalid_data = {
...     "label": "테스트 중",
...     "coordinates": {
...         "x": 'a',
...         "y": 'b',
...     }
... }
>>> invalid_serializer = DataPointSerializer(data=invalid_data)
>>> invalid_serializer.is_valid()
False
>>> invalid_serializer.errors
ReturnDict([('coordinates',
             {'x': ['유효한 정수가 필요합니다.'],
              'y': ['유효한 정수가 필요합니다.']})])

이러한 이유로 중첩 직렬화기 접근 방식이 처음에 시도할 방법입니다. 중첩 직렬화기가 불가능하거나 지나치게 복잡한 경우에는 사용자 정의 필드 접근 방식을 사용합니다.

서드 파티 패키지

다음과 같은 서드 파티 패키지도 사용 가능합니다.

DRF Compound Fields

drf-compound-fields 패키지는 다른 필드 또는 many=True 옵션을 가진 직렬화기보다 기술된 필드로 설명할 수 있는 "복합" 직렬화기 필드를 제공합니다. 또한 형식별 사전 및 해당 유형의 항목 또는 해당 유형의 항목 목록을 포함할 수 있는 필드가 제공됩니다.

DRF Extra Fields

drf-extra-fields 패키지는 Base64ImageField 및 PointField 클래스를 포함하여 REST 프레임워크에 추가적인 직렬화기 필드를 제공합니다.

djangorestframework-recursive

djangorestframework-recursive 패키지는 재귀적 구조를 직렬화하고 역직렬화하기 위한 RecursiveField를 제공합니다.

django-rest-framework-gis

django-rest-framework-gis 패키지는 GeometryField 필드와 GeoJSON 직렬화기와 같은 지리적 추가 기능을 제공합니다.

django-rest-framework-hstore

django-rest-framework-hstore 패키지는 django-hstore DictionaryField 모델 필드를 지원하기 위한 HStoreField를 제공합니다.