解析器

機(jī)器互動(dòng)的Web服務(wù)往往使用更多結(jié)構(gòu)化的格式發(fā)送數(shù)據(jù)而不是使用表單編碼，因?yàn)樗鼈儼l(fā)送的是比簡單形式更復(fù)雜的數(shù)據(jù)。— Malcom Tredinnick, Django developers group

REST 框架包括一些內(nèi)置的Parser類，允許你接受各種媒體類型的請(qǐng)求。還支持定義自己的自定義解析器，這使你可以靈活地設(shè)計(jì)API接受的媒體類型。

解析器如何確定

一組視圖的有效解析器總是被定義為一個(gè)類的列表。當(dāng)訪問request.data時(shí)，REST框架將檢查傳入請(qǐng)求中的Content-Type頭，并確定用于解析請(qǐng)求內(nèi)容的解析器。

注意: 開發(fā)客戶端應(yīng)用程序時(shí)應(yīng)該始終記住在HTTP請(qǐng)求中發(fā)送數(shù)據(jù)時(shí)確保設(shè)置Content-Type頭。

如果你不設(shè)置內(nèi)容類型，大多數(shù)客戶端將默認(rèn)使用'application/x-www-form-urlencoded'，而這可能并不是你想要的。

舉個(gè)例子，如果你使用jQuery的.ajax() 方法發(fā)送json編碼數(shù)據(jù)，你應(yīng)該確保包含contentType：'application / json'設(shè)置。

設(shè)置解析器

可以使用DEFAULT_PARSER_CLASSES設(shè)置全局默認(rèn)的解析器集。例如，以下設(shè)置將僅允許具有JSON內(nèi)容的請(qǐng)求，而不是JSON或表單數(shù)據(jù)的默認(rèn)值。

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework.parsers.JSONParser',
    )
}

你還可以設(shè)置用于單個(gè)視圖或視圖集的解析器， 使用APIView類視圖。

from rest_framework.parsers import JSONParser
from rest_framework.response import Response
from rest_framework.views import APIView

class ExampleView(APIView):
    """
    可以接收J(rèn)SON內(nèi)容POST請(qǐng)求的視圖。
    """
    parser_classes = (JSONParser,)

    def post(self, request, format=None):
        return Response({'received data': request.data})

或者，如果你使用基于方法的視圖的@api_view裝飾器。

from rest_framework.decorators import api_view
from rest_framework.decorators import parser_classes

@api_view(['POST'])
@parser_classes((JSONParser,))
def example_view(request, format=None):
    """
    可以接收J(rèn)SON內(nèi)容POST請(qǐng)求的視圖
    """
    return Response({'received data': request.data})

API參考

JSONParser

解析 JSON 請(qǐng)求內(nèi)容。

.media_type: application/json

FormParser

解析 HTML 表單內(nèi)容。request.data將被填充一個(gè)QueryDict的數(shù)據(jù)。

通常，你需要使用FormParser和MultiPartParser兩者，以便完全支持HTML表單數(shù)據(jù)。

.media_type: application/x-www-form-urlencoded

MultiPartParser

解析多部分HTML表單內(nèi)容，支持文件上傳。request.data 都將被一個(gè) QueryDict填充。

你通常會(huì)同時(shí)使用FormParser和MultiPartParser兩者，以便完全支持HTML表單數(shù)據(jù)。

.media_type: multipart/form-data

FileUploadParser

解析原始文件上傳內(nèi)容。 request.data 屬性將是有單個(gè)key 'file'的包含上傳文件的字典。

如果與FileUploadParser一起使用的視圖使用filename URL關(guān)鍵字參數(shù)調(diào)用，則該參數(shù)將用作文件名。

如果沒有filename URL關(guān)鍵字參數(shù)調(diào)用，那么客戶端必須在Content-Disposition HTTP頭中設(shè)置文件名。例如 Content-Disposition: attachment; filename=upload.jpg.

.media_type: */*

說明:

• FileUploadParser 用于與原始數(shù)據(jù)請(qǐng)求一起上傳文件的本機(jī)客戶端。對(duì)于基于Web的上傳，或者對(duì)于具有多部分上傳支持的本機(jī)客戶端，您應(yīng)該使用MultiPartParser解析器。
• 由于該解析器的media_type與任何內(nèi)容類型匹配，所以FileUploadParser通常應(yīng)該是API視圖中唯一的解析器。
• FileUploadParser 遵循 Django 的標(biāo)準(zhǔn) FILE_UPLOAD_HANDLERS 設(shè)置，和 request.upload_handlers 屬性。參見 Django 文檔 獲取更多細(xì)節(jié)。

基本用法示例：

# views.py
class FileUploadView(views.APIView):
    parser_classes = (FileUploadParser,)

    def put(self, request, filename, format=None):
        file_obj = request.data['file']
        # ...
        # do some stuff with uploaded file
        # ...
        return Response(status=204)

# urls.py
urlpatterns = [
    # ...
    url(r'^upload/(?P<filename>[^/]+)$', FileUploadView.as_view())
]

自定義解析器

要實(shí)現(xiàn)一個(gè)自定義解析器，你應(yīng)該重寫B(tài)aseParser，設(shè)置.media_type屬性，并實(shí)現(xiàn).parse(self，stream，media_type，parser_context)方法。

該方法應(yīng)該返回用于填充request.data 屬性的數(shù)據(jù)。

傳遞給 .parse() 的參數(shù)是:

stream

表示請(qǐng)求體的數(shù)據(jù)流。

media_type

可選的。如果提供，這是傳入請(qǐng)求內(nèi)容的媒體類型。

基于請(qǐng)求的Content-Type:頭，這可能比渲染器的media_type屬性更具體，可能包括媒體類型參數(shù)。例如 "text/plain; charset=utf-8"。

parser_context

可選的。如果提供，該參數(shù)將是一個(gè)包含解析請(qǐng)求內(nèi)容可能需要的任何附加上下文的字典。

默認(rèn)情況下將包含以下keys: view, request, args, kwargs。

例子

以下是一個(gè)Plain text的示例，它將使用表示請(qǐng)求正文的字符串填充request.data屬性。

class PlainTextParser(BaseParser):
    """
    Plain text 解析器。
    """
    media_type = 'text/plain'

    def parse(self, stream, media_type=None, parser_context=None):
        """
        只需返回一個(gè)表示請(qǐng)求正文的字符串。
        """
        return stream.read()

第三方包

以下是可用的第三方包。

YAML

REST framework YAML 提供了 YAML 解析和呈現(xiàn)的支持。之前它是直接包含在REST框架包中的，現(xiàn)在被替代為第三方包支持。

安裝和配置

使用pip進(jìn)行安裝。

$ pip install djangorestframework-yaml

修改你的 REST framework settings。

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework_yaml.parsers.YAMLParser',
    ),
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework_yaml.renderers.YAMLRenderer',
    ),
}

XML

REST Framework XML 提供了一種簡單的非正式XML格式。它以前是直接包含在REST框架包中，現(xiàn)在被替代為第三方包支持。

安裝和配置

使用pip進(jìn)行安裝。

$ pip install djangorestframework-xml

修改你的 REST framework settings.

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework_xml.parsers.XMLParser',
    ),
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework_xml.renderers.XMLRenderer',
    ),
}

MessagePack

MessagePack 是一種快速，高效的二進(jìn)制序列化格式。 Juan Riaza 維護(hù)了 djangorestframework-msgpack 包，它為REST框架提供MessagePack渲染器和解析器支持。

CamelCase JSON

djangorestframework-camel-case 為REST framework提供了駝峰類型JSON 生成和解析。這個(gè)庫允許序列化程序使用Python風(fēng)格的下劃線字段名稱，并且將其轉(zhuǎn)變?yōu)镴avascript風(fēng)格的駝峰字段名稱在API中公開。這個(gè)庫由 Vitaly Babiy維護(hù)。