请求解析

警告

Flask-RESTful 的整体请求解析部分被提名去除并且将被文档中如何与其他更好的模块集成所代替。 (比如 marshmallow). 这就意味着它将被支持到2.0,这被认为是过时的。 不用担心,如果你的代码使用了它,并且你希望继续使用下去,它不会很快的消失(会支持很长一段时间)。

Flask-RESTful 的请求解析接口, reqparse, 是仿照的
argparse 接口. 它被设计在 Flask flask.request 对象中去提供简单统一的任何变量的访问。

基本参数

这里有一个请求解析的简单例子。 它看起来有两个参数在

flask.Request.values 字典: 一个 integer 和一个 string

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument('rate', type=int, help='Rate cannot be converted')
parser.add_argument('name')
args = parser.parse_args()
如果你指定了 help 参数, 当它发现类型错误的时候,将会呈现出一个错误信息。
如果你不指定帮助信息, 默认的行为是返回类型错误自带的错误信息。

默认情况下, 参数是 被要求的。 此外, 提供的参数请求 不在 RequestParser 的部分将被忽略。

还要注意: Arguments declared in your request parser 但是如果没有设置请求本身将会被默认设置为 None

必须的参数

如果必须要求一个值去传递参数, 只需要添加 required=True

add_argument().

parser.add_argument('name', required=True,
help="Name cannot be blank!")

多重参数 & 列表

如果你想接受一个列表的key的多个值, 你可以通过这样设置: action='append'

parser.add_argument('name', action='append')

这将让你做出这样的查询

curl http://api.example.com -d "name=bob" -d "name=sue" -d "name=joe"

而你的args将是这样的

args = parser.parse_args()
args['name']    # ['bob', 'sue', 'joe']

Other Destinations

如果由于某种原因,你希望用不同的名字存储你的 argument 一旦它被解析, 你可以用 dest 关键字参数。

parser.add_argument('name', dest='public_name')

args = parser.parse_args()
args['public_name']

参数位置

默认情况下, 这个 RequestParser 会试图从 flask.Request.values, 和 flask.Request.json 解析值。

location 参数 to add_argument() 去指定备用位置读取参数。 flask.Request 上的任何变量都可以被使用。比如:

# Look only in the POST body
parser.add_argument('name', type=int, location='form')

# Look only in the querystring
parser.add_argument('PageSize', type=int, location='args')

# From the request headers
parser.add_argument('User-Agent', location='headers')

# From http cookies
parser.add_argument('session_id', location='cookies')

# From file uploads
parser.add_argument('picture', type=werkzeug.datastructures.FileStorage, location='files')

多个位置

多个位置参数可以通过一个 location 列表指定:

parser.add_argument('text', location=['headers', 'values'])

最后的 location 列表优先在结果中.

解析器继承

通常你会为你写的每一个资源不同的解释器. 问题是,如果解释器有共同的参数而不是需要重写参数, 你可以写一个包含所有公共参数的父解析器,然后通过 copy() 扩展这个解析器。 你也可以使用 replace_argument() 重写这个解释器里的任何参数, 或者用 remove_argument() 彻底的移除某个参数. 比如:

from flask_restful import reqparse

parser = reqparse.RequestParser()
parser.add_argument('foo', type=int)

parser_copy = parser.copy()
parser_copy.add_argument('bar', type=int)

# parser_copy has both 'foo' and 'bar'

parser_copy.replace_argument('foo', required=True, location='json')
# 'foo' is now a required str located in json, not an int as defined
#  by original parser

parser_copy.remove_argument('foo')
# parser_copy no longer has 'foo' argument

异常处理

RequestParser 处理错误的默认方法是第一个错误发生时退出. 这可能是有益的当你需要花费一些时间来处理的时候。 然而, 往往比较好的情况是将错误绑定到一起,并一次全部返回给客户端。 这种行为可以是明确规定的也可以是 Flask 应用级别的或者 RequestParser 案例的规范. 通过 bundle_errors 带着绑定错误的选项去调用一个 RequestParser,

比如

from flask_restful import reqparse

parser = reqparse.RequestParser(bundle_errors=True)
parser.add_argument('foo', type=int, required=True)
parser.add_argument('bar', type=int, required=True)

# If a request comes in not containing both 'foo' and 'bar', the error that
# will come back will look something like this.

{
    "message":  {
        "foo": "foo error message",
        "bar": "bar error message"
    }
}

# The default behavior would only return the first error

parser = RequestParser()
parser.add_argument('foo', type=int, required=True)
parser.add_argument('bar', type=int, required=True)

{
    "message":  {
        "foo": "foo error message"
    }
}

应用配置文件配置 “BUNDLE_ERRORS”. 例如

from flask import Flask

app = Flask(__name__)
app.config['BUNDLE_ERRORS'] = True

警告

BUNDLE_ERRORS 是一个全局设置,在一个 RequestParser 实例中, 比 bundle_errors 选项优先级更高。