配置

通常,EVE配置最好使用配置文件。配置文件本身就是实际的python文件。但是,EVE将优先于基于字典的设置,然后它将尝试查找传入的文件 EVE_SETTINGS 环境变量(如果设置)并最终尝试定位 settings.py 或文件名传递给 settings 构造函数中的标志。

配置文件

启动时,如果 settings 构造函数中省略了标志,eve将尝试查找名为 settings.py ,首先在应用程序文件夹中,然后在应用程序的一个子文件夹中。您可以选择另一个文件名/路径,只需在实例化应用程序时将其作为参数传递即可。如果文件路径是相对的,EVE将尝试在 sys.path 因此,必须确保将应用程序根目录附加到它之后。例如,在测试环境中,当设置文件不一定位于应用程序的根目录中时,这很有用。

from eve import Eve

app = Eve(settings='my_settings.py')
app.run()

使用字典配置

或者,您可以选择提供设置字典。与使用设置文件配置EVE不同,基于字典的方法将只使用您自己的值更新EVE的默认设置,而不是覆盖所有设置。

from eve import Eve

my_settings = {
    'MONGO_HOST': 'localhost',
    'MONGO_PORT': 27017,
    'MONGO_DBNAME': 'the_db_name',
    'DOMAIN': {'contacts': {}}
}

app = Eve(settings=my_settings)
app.run()

开发/生产

大多数应用程序需要多个配置。生产服务器和开发过程中使用的服务器至少应该有单独的配置。处理此问题的最简单方法是使用始终加载的默认配置和版本控制的一部分,以及根据需要覆盖值的单独配置。

这是您可以用文件的内容覆盖或扩展设置的主要原因 EVE_SETTINGS 环境变量指向。开发/本地设置可以存储在 settings.py 然后,在生产中,您可以导出eve_settings=/path/to/production_setting.py,然后就完成了。

有许多可供选择的方法来处理数据开发/生产如何eve eve r。使用Python模块进行配置非常方便,因为它们允许使用各种技巧,比如能够在本地和生产系统上无缝启动相同的API,并根据需要连接到适当的数据库实例。请考虑以下示例:

# We want to run seamlessly our API both locally and on Heroku, so:
if os.environ.get('PORT'):
    # We're hosted on Heroku! Use the MongoHQ sandbox as our backend.
    MONGO_HOST = 'alex.mongohq.com'
    MONGO_PORT = 10047
    MONGO_USERNAME = '<user>'
    MONGO_PASSWORD = '<pw>'
    MONGO_DBNAME = '<dbname>'
else:
    # Running on local machine. Let's just use the local mongod instance.

    # Please note that MONGO_HOST and MONGO_PORT could very well be left
    # out as they already default to a bare bones local 'mongod' instance.
    MONGO_HOST = 'localhost'
    MONGO_PORT = 27017
    MONGO_USERNAME = 'user'
    MONGO_PASSWORD = 'user'
    MONGO_DBNAME = 'apitest'

全局配置

除了定义一般的API行为之外,大多数全局配置设置还用于定义标准端点规则集,并且可以稍后在配置单个端点时进行微调。全局配置设置始终为大写。

URL_PREFIX

所有API端点的URL前缀。将与 API_VERSION 构建API端点(例如, api 将呈现给 /api/<endpoint> )。默认为 '' .

API_VERSION

API版本。将与 URL_PREFIX 构建API端点(例如, v1 将呈现给 /v1/<endpoint> )默认为 '' .

ALLOWED_FILTERS

允许筛选的字段列表。此列表中的条目以分层方式工作。这意味着,例如,过滤 'dict.sub_dict.foo' 允许的条件是 ALLOWED_FILTERS 包含任何 'dict.sub_dict.foo'dict.sub_dict''dict' .而是过滤 'dict' 允许的条件是 ALLOWED_FILTERS 包含 'dict' .可以设置为 [] (不允许使用过滤器)或 ['*'] (每个字段都允许使用筛选器)。除非您的API仅由一个端点组成,否则此全局设置应用作开/关开关,在本地级别委托显式白名单(请参见 allowed_filters 以下)。默认为 ['*'] .

请注意: 如果担心API抓取或DB-DOS攻击,那么全局禁用过滤器并在本地级别将有效的过滤器白名单显示出来是可行的方法。

VALIDATE_FILTERS

是否根据资源架构验证筛选器。无效的筛选器将引发异常。默认为 False .

注意:对包含自定义规则或类型的字段的筛选表达式进行验证可能会对性能产生相当大的影响。例如,这种情况下, data_relation -规则字段。考虑从过滤器中排除重载字段(请参见 ALLOWED_FILTERS

SORTING

True 如果支持排序 GET 请求,否则 False .可以被资源设置覆盖。默认为 True .

PAGINATION

True 如果为启用分页 GET 请求,否则 False .可以被资源设置覆盖。默认为 True .

PAGINATION_LIMIT

允许的最大值 QUERY_MAX_RESULTS 查询参数。超过该限制的值将以静默方式替换为此值。您希望在性能和传输大小之间实现合理的折衷。默认为50。

PAGINATION_DEFAULT

的默认值 QUERY_MAX_RESULTS 。默认为25。

OPTIMIZE_PAGINATION_FOR_SPEED

设置为 True 以提高分页性能。当优化处于活动状态时,不会对数据库执行计数操作,这在大型集合上可能比较慢。这确实会带来一些后果。首先,不返回文档计数。其次, HATEOAS 不太准确:没有可用的最后一页链接,并且下一页链接始终包括在内,即使是在最后一页。在大型收藏中,打开此功能可以大大提高性能。默认为 False (性能较慢;包括文档计数;准确 HATEOAS

QUERY_WHERE

筛选器查询参数的键。默认为 where .

QUERY_SORT

排序查询参数的键。默认为 sort .

QUERY_PROJECTION

投影查询参数的键。默认为 projection .

QUERY_PAGE

页查询参数的键。默认为 page .

QUERY_MAX_RESULTS

最大结果查询参数的键。默认为 max_results .

QUERY_EMBEDDED

嵌入查询参数的键。默认为 embedded .

QUERY_AGGREGATION

聚合查询参数的键。默认为 aggregate .

DATE_FORMAT

用于分析和呈现日期时间值的python日期格式。当服务请求时,匹配的JSON字符串将被解析并存储为 datetime 价值观。作为回应, datetime 值将使用此格式呈现为JSON字符串。默认为RFC1123(例如RFC822)标准 a, %d %b %Y %H:%M:%S GMT (2013年4月2日星期二10:29:13格林尼治标准时间)。

RESOURCE_METHODS

资源终结点支持的HTTP方法列表。允许值: GETPOSTDELETE . POST 用于插入。 DELETE 将删除 all 资源内容(请小心启用)。可以被资源设置覆盖。默认为 ['GET'] .

PUBLIC_METHODS

资源端点支持的HTTP方法列表,即使在 认证和授权 已启用。可以被资源设置覆盖。默认为 [] .

ITEM_METHODS

在项终结点支持的HTTP方法列表。允许值: GETPATCHPUTDELETE . PATCH 或者,对于不支持补丁的客户机, POSTX-HTTP-Method-Override 标题标签,用于项目更新; DELETE 用于项目删除。可以被资源设置覆盖。默认为 ['GET'] .

PUBLIC_ITEM_METHODS

项终结点支持的HTTP方法列表,当 认证和授权 已启用。可以被资源设置覆盖。默认为 [] .

ALLOWED_ROLES

允许的列表 roles 用于资源终结点。可以被资源设置覆盖。参见 认证和授权 更多信息。默认为 [] .

ALLOWED_READ_ROLES

允许的列表 roles 用于具有get和options方法的资源终结点。可以被资源设置覆盖。参见 认证和授权 更多信息。默认为 [] .

ALLOWED_WRITE_ROLES

允许的列表 roles 对于具有POST、PUT和DELETE方法的资源终结点。可以被资源设置覆盖。参见 认证和授权 更多信息。默认为 [] .

ALLOWED_ITEM_ROLES

允许的列表 roles 用于项终结点。参见 认证和授权 更多信息。可以被资源设置覆盖。默认为 [] .

ALLOWED_ITEM_READ_ROLES

允许的列表 roles 用于具有get和options方法的项终结点。参见 认证和授权 更多信息。可以被资源设置覆盖。默认为 [] .

ALLOWED_ITEM_WRITE_ROLES

允许的列表 roles 对于具有Put、Patch和Delete方法的项端点。参见 认证和授权 更多信息。可以被资源设置覆盖。默认为 [] .

ALLOW_OVERRIDE_HTTP_METHOD

启用/禁用全局用头重写发送的方法的可能性 X-HTTP-METHOD-OVERRIDE .

CACHE_CONTROL

的值 Cache-Control 服务时使用的标题字段 GET 请求(例如, max-age=20,must-revalidate )。如果不想在API响应中包含缓存指令,请保留为空。可以被资源设置覆盖。默认为 '' .

CACHE_EXPIRES

的值(秒) Expires 服务时使用的标题字段 GET 请求。如果设置为非零值,则无论 CACHE_CONTROL .可以被资源设置覆盖。默认为0。

X_DOMAINS

CORS(跨源资源共享)支持。允许API维护人员指定允许哪些域执行CORS请求。允许值为: None ,域列表,或 '*' 对于广泛开放的API。默认为 None .

X_DOMAINS_RE

设置与 X_DOMAINS ,但允许使用正则表达式列表。这对于具有动态子域范围的网站很有用。确保正确锚定并脱离正则表达式。无效的正则表达式(例如 '*' )被忽略。默认为 None .

X_HEADERS

CORS(跨源资源共享)支持。允许API维护人员指定哪些头可以与CORS请求一起发送。允许值为: None 或标题名称列表。默认为 None .

X_EXPOSE_HEADERS

CORS(跨源资源共享)支持。允许API维护人员指定哪些头在CORS响应中公开。允许值为: None 或标题名称列表。默认为 None .

X_ALLOW_CREDENTIALS

CORS(跨源资源共享)支持。允许API维护人员指定客户端是否可以发送cookie。唯一允许的值是: True ,任何其他将被忽略。默认为 None .

X_MAX_AGE

CORS(跨源资源共享)支持。允许设置访问控制允许头的最大期限。默认为21600。

LAST_UPDATED

用于记录文档上次更新日期的字段的名称。此字段由EVE自动处理。默认为 _updated .

DATE_CREATED

用于记录文档创建日期的字段的名称。此字段由EVE自动处理。默认为 _created .

ID_FIELD

用于唯一标识数据库中资源项的字段的名称。您希望此字段在数据库中被正确索引。可以被资源设置覆盖。默认为 _id .

ITEM_LOOKUP

True 如果项目端点在整个API中普遍可用, False 否则。可以被资源设置覆盖。默认为 True .

ITEM_LOOKUP_FIELD

查找资源项时使用的文档域。可以被资源设置覆盖。默认为 ID_FIELD .

ITEM_URL

用于构造默认项终结点URL的URL规则。可以被资源设置覆盖。默认 regex("[a-f0-9]{{24}}") 哪个是MongoDB标准 Object_Id 格式。

ITEM_TITLE

在XML和JSON响应中构建项引用时使用的标题。默认为资源名称,如果存在,则去掉复数“s”。在配置单个资源终结点时,很可能会被覆盖。

AUTH_FIELD

使能够 用户限制的资源访问 .启用该功能后,用户只能读取/更新/删除自己创建的资源项。关键字包含用于存储创建资源项的用户ID的字段的实际名称。可以被资源设置覆盖。默认为 None ,这将禁用该功能。

ALLOW_UNKNOWN

什么时候? True ,此选项将允许向任何API端点插入任意的未知字段。小心使用。参见 允许未知 更多信息。默认为 False .

PROJECTION

什么时候? True ,此选项启用 预测 功能。可以被资源设置覆盖。默认为 True .

EMBEDDING

什么时候? True ,此选项启用 嵌入式资源序列化 功能。默认为 True .

BANDWIDTH_SAVER

什么时候? True 、Post、Put和Patch响应只返回自动处理的字段和 EXTRA_RESPONSE_FIELDS . 什么时候? False ,将发送整个文档。默认为 True .

EXTRA_RESPONSE_FIELDS

允许配置附加文档字段列表,这些字段应随每个post响应一起提供。通常只自动处理字段 (ID_FIELDLAST_UPDATEDDATE_CREATEDETAG )包括在响应有效载荷中。可以被资源设置覆盖。默认为 [] ,有效禁用功能。

RATE_LIMIT_GET

表示GET请求的速率限制的元组。元组的第一个元素是允许的请求数,第二个元素是以秒为单位的时间窗口。例如, (300, 60 * 15) 将设置每15分钟300个请求的限制。默认为 None .

RATE_LIMIT_POST

表示POST请求的速率限制的元组。元组的第一个元素是允许的请求数,第二个元素是以秒为单位的时间窗口。例如 (300, 60 * 15) 将设置每15分钟300个请求的限制。默认为 None .

RATE_LIMIT_PATCH

表示修补程序请求的速率限制的元组。元组的第一个元素是允许的请求数,第二个元素是以秒为单位的时间窗口。例如 (300, 60 * 15) 将设置每15分钟300个请求的限制。默认为 None .

RATE_LIMIT_DELETE

表示删除请求的速率限制的元组。元组的第一个元素是允许的请求数,第二个元素是以秒为单位的时间窗口。例如 (300, 60 * 15) 将设置每15分钟300个请求的限制。默认为 None .

DEBUG

True 要启用调试模式, False 否则。

ERROR

允许自定义错误代码字段。默认为 _error .

HATEOAS

什么时候? False ,此选项禁用 HATEOAS .默认为 True .

ISSUES

允许自定义问题字段。默认为 _issues .

STATUS

允许自定义状态字段。默认为 _status .

STATUS_OK

数据验证成功时返回状态消息。默认为 OK .

STATUS_ERR

数据验证失败时返回状态消息。默认为 ERR .

ITEMS

允许自定义项目字段。默认为 _items .

META

允许自定义元字段。默认为 _meta

INFO

字符串值,用于在EVE主页上包含具有给定信息名称的信息部分(建议值 _info )。信息部分将包括EVE服务器版本和API版本(如果设置了API U版本)。 None 否则,如果不想公开任何服务器信息。默认为 None .

LINKS

允许自定义链接字段。默认为 _links .

ETAG

允许自定义etag字段。默认为 _etag .

IF_MATCH

True 要启用并发控制, False 否则。默认为 True . 见 数据完整性和并发控制 .

ENFORCE_IF_MATCH

True 要始终在启用并发控制时强制执行并发控制, False 否则。默认为 True . 见 数据完整性和并发控制 .

RENDERERS

允许更改启用的渲染器。默认为 ['eve.render.JSONRenderer', 'eve.render.XMLRenderer'] .

JSON_SORT_KEYS

True 要启用JSON键排序, False 否则。默认为 False .

JSON_REQUEST_CONTENT_TYPES

支持的JSON内容类型。当您需要支持特定于供应商的JSON类型时很有用。请注意:回复仍然符合标准。 application/json 类型。默认为 ['application/json'] .

VALIDATION_ERROR_STATUS

用于验证错误的HTTP状态代码。默认为 422 .

VERSIONING

启用文档版本控制的时间 True .可以被资源设置覆盖。默认为 False .

VERSIONS

添加到主集合名称的后缀,以创建用于存储文档版本的卷影集合名称。默认为 _versions . 什么时候? VERSIONING 已启用,集合如 myresource_versions 将为数据源为的资源创建 myresource .

VERSION_PARAM

用于访问文档特定版本的URL查询参数。默认为 version .省略此参数以获取文档的最新版本或使用 ?version=all `获取文档的所有版本的列表。仅对单个项终结点有效。

VERSION

用于存储文档版本号的字段。默认为 _version .

LATEST_VERSION

用于存储文档最新版本号的字段。默认为 _latest_version .

VERSION_ID_SUFFIX

在卷影集合中用于存储文档ID。默认为 _document .如果 ID_FIELD 设置为 _id ,文档ID将存储在字段中 _id_document .

MONGO_URI

A MongoDB URI 它优先于其他配置变量使用。

MONGO_HOST

MongoDB服务器地址。默认为 localhost .

MONGO_PORT

MongoDB端口。默认为 27017 .

MONGO_USERNAME

MongoDB用户名。

MONGO_PASSWORD

MongoDB密码。

MONGO_DBNAME

MongoDB数据库名称。

MONGO_OPTIONS

要传递给MongoClient类的MongoDB关键字参数 __init__ 。默认为 {'connect': True, 'tz_aware': True, 'appname': 'flask_app_name', 'uuidRepresentation': 'standard'} 。看见 PyMongo mongo_client 以供参考。

MONGO_AUTH_SOURCE

MongoDB授权数据库。默认为 None .

MONGO_AUTH_MECHANISM

MongoDB认证机制。参见 PyMongo Authentication Mechanisms .默认为 None .

MONGO_AUTH_MECHANISM_PROPERTIES

如果需要,请指定MongoDB额外身份验证机制属性。默认为 None .

MONGO_QUERY_BLACKLIST

资源筛选器中不允许使用的Mongo查询运算符列表 (?where= )默认为 ['$where', '$regex'] .

默认情况下,mongo javascript操作符被禁用,因为它们可能被用作注入攻击的向量。JavaScript查询速度也很慢,通常可以很容易地用(非常丰富的)Mongo查询方言替换。

MONGO_QUERY_WHITELIST

除了允许的运算符的正式列表外,允许的额外Mongo查询运算符的列表。默认为 [] .

可以在端点(Mongo集合)级别重写。参见 mongo_query_whitelist 下面。

MONGO_WRITE_CONCERN

定义MongoDB写关注设置的字典。支持所有标准写入问题设置(w、wtimeout、j、fsync)。默认为 {{'w': 1}} 这意味着“执行常规确认写入”(这也是Mongo的默认值)。

请注意,将“w”设置为2或更大的值要求复制处于活动状态,否则您将收到500个错误(写入仍将发生;Mongo将无法检查它是否正在写入多个服务器)。

可以在端点(Mongo集合)级别重写。参见 mongo_write_concern 下面。

DOMAIN

保存API域定义的dict。参见 Domain Configuration .

EXTENDED_MEDIA_INFO

要从文件上载驱动程序转发的属性列表。

RETURN_MEDIA_AS_BASE64_STRING

控制在终结点响应中嵌入媒体类型。当您有其他方法来获取二进制文件(如自定义flask端点)但仍希望客户机能够发布/修补它时,这很有用。默认为 True .

RETURN_MEDIA_AS_URL

设置为 True 在专用媒体终结点上启用媒体文件服务。默认为 False .

MEDIA_BASE_URL

在以下情况下使用的基URL RETURN_MEDIA_AS_URL 处于活动状态。结合 MEDIA_ENDPOINTMEDIA_URL 指示为媒体文件返回的URL。如果 None 作为默认值,将使用api基地址。

MEDIA_ENDPOINT

要在以下情况下使用的媒体终结点: RETURN_MEDIA_AS_URL 已启用。默认为 media .

MEDIA_URL

在专用媒体终结点提供的文件URL的格式。默认为 regex("[a-f0-9]{{24}}") .

MULTIPART_FORM_FIELDS_AS_JSON

如果您将资源提交为 multipart/form-data 所有表单数据域都将作为字符串提交,这违反了您在资源域上可能拥有的任何验证规则。如果要将所有提交的表单数据视为JSON字符串,则必须激活此设置。在这种情况下,字段验证将继续正常工作。阅读有关字段格式设置的详细信息 媒体文件注释为 multipart/form-data .默认为 False .

AUTO_COLLAPSE_MULTI_KEYS

如果设置为 True ,使用同一密钥发送多个值,使用 application/x-www-form-urlencodedmultipart/form-data 内容类型,将自动转换为值列表。

与一起使用时 AUTO_CREATE_LISTS 可以使用媒体字段列表。

默认为 False

AUTO_CREATE_LISTS

提交非 list 类型为的字段的类型值 list ,在运行验证程序之前自动创建一个元素列表。

默认为 False

OPLOG

设置为 True 启用 作战日志 .默认为 False .

OPLOG_NAME

这是数据库集合的名称,其中 作战日志 已存储。默认为 oplog .

OPLOG_METHODS

应在其中登录操作的HTTP方法列表 作战日志 .默认为 ['DELETE', 'POST', 'PATCH', 'PUT'] .

OPLOG_CHANGE_METHODS

操作将包括更改的HTTP方法列表 作战日志 进入。默认为 ['DELETE','PATCH', 'PUT'] .

OPLOG_ENDPOINT

名称 作战日志 终结点。如果启用了端点,则可以像配置任何其他API端点一样对其进行配置。设置为 None 禁用端点。默认为 None .

OPLOG_AUDIT

设置为 True 启用审核功能。启用审核后,客户端IP和文档更改也会记录到 作战日志 .默认为 True .

OPLOG_RETURN_EXTRA_FIELD

启用时,可选 extra 字段将包含在 OPLOG_ENDPOINT .默认为 False .

SCHEMA_ENDPOINT

名称 架构终结点 .默认为 None .

HEADER_TOTAL_COUNT

包含集合响应有效负载中项目总数的自定义头 GET 请求。这个很方便 HEAD 当客户端希望知道项目计数而不检索响应正文时请求。一个示例用例是使用 where 查询而不加载日志本身。默认为 X-Total-Count .

JSONP_ARGUMENT

如果在请求中设置了参数,则此选项将导致响应包装在javascript函数调用中。例如,如果设置 JSON_ARGUMENT = 'callback' ,然后所有响应 ?callback=funcname 请求将包装在 funcname 呼叫。默认为 None .

BULK_ENABLED

设置为时启用大容量插入 True . 见 大容量插入 更多信息。默认为 True .

SOFT_DELETE

设置为时启用软删除 True . 见 软删除 更多信息。默认为 False .

DELETED

用于指示文档是否已被删除的字段名 SOFT_DELETE 已启用。默认为 _deleted .

SHOW_DELETED_PARAM

用于在资源级别get responses中包含软删除项的url查询参数。默认为“显示已删除”。

STANDARD_ERRORS

这是将为其提供标准API响应的HTTP错误代码列表。规范错误响应包括一个带有实际错误代码和描述的JSON主体。如果要完全禁用规范响应,请将其设置为空列表。默认为 [400, 401, 403, 404, 405, 406, 409, 410, 412, 422, 428]

VALIDATION_ERROR_AS_LIST

如果 True 即使是单个字段错误也会在列表中返回。默认情况下,单个字段错误作为字符串返回,而多个字段错误捆绑在一个列表中。如果要标准化字段错误输出,请将此设置设置为 True 你总是会得到一份现场问题清单。默认为 False .

UPSERT_ON_PUT

PUT 尝试创建不存在的文档。URL端点将用作 ID_FIELD 值(如果 ID_FIELD 包含在有效载荷中,将被忽略)。正常验证规则适用。回答将是 201 Created 成功创建。响应负载将与执行到资源端点的单个文档发布所获得的负载相同。设置为 False 禁用此功能,以及 404 将被返回。默认为 True .

MERGE_NESTED_DOCUMENTS

如果 True ,对嵌套字段的更新将与上的当前数据合并。 PATCH .如果 False ,更新将覆盖当前数据。默认为 True .

NORMALIZE_DOTTED_FIELDS

如果 True ,点域作为子文档域进行分析和处理。如果 False ,点式字段保持未处理状态,有效负载按原样传递给底层数据层。请注意,对于默认的mongo层,将其设置为 False 将导致错误。默认为 True .

NORMALIZE_ON_PATCH

如果 True ,补丁文件将根据模式进行规范化。这意味着,如果一个字段不包含在补丁主体中,它将被重置为其模式中的默认值。如果 False ,未包含在补丁主体中的字段将保持不变。默认为 True .

域配置

在EVE术语中,a domain 是API结构的定义,是设计API、微调资源端点和定义验证规则的区域。

DOMAIN 是一个 global configuration setting :一个python字典,其中键是api资源,并为其定义赋值。

# Here we define two API endpoints, 'people' and 'works', leaving their
# definitions empty.
DOMAIN = {
    'people': {},
    'works': {},
    }

在以下两个部分中,我们将自定义 people 资源。

资源/项目终结点

端点自定义主要通过重写 global settings ,但也可以使用其他独特的设置。资源设置总是小写。

url

终结点URL。如果省略了 DOMAIN dict将用于构建URL。举个例子, contacts 会使 people 资源可用位置 /contacts 而不是 /people )。URL可以根据需要复杂,并且可以相对于另一个API端点嵌套(您可以 /contacts 终结点,然后是 /contacts/overseas 终结点。两者相互独立,可自由配置)。

您还可以使用regex来设置类似于子资源的端点。参见 子资源 .

allowed_filters

允许筛选的字段列表。此列表中的条目以分层方式工作。这意味着,例如,过滤 'dict.sub_dict.foo' 允许的条件是 allowed_filters 包含任何 'dict.sub_dict.foo'dict.sub_dict''dict' .而是过滤 'dict' 允许的条件是 allowed_filters 包含 'dict' .可以设置为 [] (不允许使用过滤器),或 ['*'] (每个字段都允许字段)。默认为 ['*'] .

请注意: 如果担心API抓取或DB-DOS攻击,则全局禁用过滤器(请参见 ALLOWED_FILTERS 上面)然后在本地级别将有效的列为白名单就可以了。

sorting

True 如果启用排序, False 否则。本地覆盖 SORTING .

pagination

True 如果启用分页, False 否则。本地覆盖 PAGINATION .

pagination_limit

允许的最大值 QUERY_MAX_RESULTS 查询参数。超过该限制的值将以静默方式替换为此值。您希望在性能和传输大小之间实现合理的折衷。默认为50。

resource_methods

资源终结点支持的HTTP方法列表。允许值: GETPOSTDELETE .本地覆盖 RESOURCE_METHODS .

请注意: 如果您运行的是0.0.5或更低版本,请使用现在不支持的 methods 关键字。

public_methods

资源端点支持的HTTP方法列表,即使在 认证和授权 已启用。本地覆盖 PUBLIC_METHODS .

item_methods

在项终结点支持的HTTP方法列表。允许值: GETPATCHPUTDELETE . PATCH 或者,对于不支持补丁的客户机, POSTX-HTTP-Method-Override 标题标签。本地覆盖 ITEM_METHODS .

public_item_methods

项终结点支持的HTTP方法列表,当 认证和授权 已启用。本地覆盖 PUBLIC_ITEM_METHODS .

allowed_roles

允许的列表 roles 用于资源终结点。参见 认证和授权 更多信息。本地覆盖 ALLOWED_ROLES .

allowed_read_roles

允许的列表 roles 用于具有get和options方法的资源终结点。参见 认证和授权 更多信息。本地覆盖 ALLOWED_READ_ROLES .

allowed_write_roles

允许的列表 roles 对于具有post的资源端点,Put和Delete。参见 认证和授权 更多信息。本地覆盖 ALLOWED_WRITE_ROLES .

allowed_item_read_roles

允许的列表 roles 用于带有get和options方法的项端点。参见 认证和授权 更多信息。本地覆盖 ALLOWED_ITEM_READ_ROLES .

allowed_item_write_roles

允许的列表 roles 对于具有Put、Path和Delete方法的项端点。参见 认证和授权 更多信息。本地覆盖 ALLOWED_ITEM_WRITE_ROLES .

allowed_item_roles

允许的列表 roles 用于项终结点。参见 认证和授权 更多信息。本地覆盖 ALLOWED_ITEM_ROLES .

cache_control

的值 Cache-Control 服务时使用的标题字段 GET 请求。如果不想在API响应中包含缓存指令,请保留为空。本地覆盖 CACHE_CONTROL .

cache_expires

的值(秒) Expires 服务时使用的标题字段 GET 请求。如果设置为非零值,则无论 CACHE_CONTROL .本地覆盖 CACHE_EXPIRES .

id_field

用于唯一标识数据库中资源项的字段。本地覆盖 ID_FIELD .

item_lookup

True 如果项终结点应可用, False 否则。本地覆盖 ITEM_LOOKUP .

item_lookup_field

查找资源项时使用的域。本地覆盖 ITEM_LOOKUP_FIELD .

item_url

用于构造项终结点URL的规则。本地覆盖 ITEM_URL .

resource_title

建立资源链接时使用的标题(hateoas)。默认为资源的 url .

item_title

在XML和JSON响应中构建项引用时使用的标题。覆盖 ITEM_TITLE .

additional_lookup

除了默认为 /<resource>/<ID_FIELD_value> ,您可以选择定义辅助的、只读的、类似端点的 /<resource>/<person_name> .你可以通过定义一个由两个项目组成的字典来实现。 fieldurl .前者是用于查找的字段的名称。如果字段类型(在资源中定义 schema) 是字符串,然后将URL规则放入 url .如果它是一个整数,那么只需省略 url ,因为它是自动处理的。有关此功能的用法示例,请参见下面的代码段。

datasource

将API资源显式链接到数据库集合。参见 Advanced Datasource Patterns .

auth_field

使能够 用户限制的资源访问 .启用该功能后,用户只能读取/更新/删除自己创建的资源项。关键字包含用于存储创建资源项的用户ID的字段的实际名称。本地覆盖 AUTH_FIELD .

allow_unknown

什么时候? True ,此选项将允许向端点插入任意的未知字段。小心使用。本地覆盖 ALLOW_UNKNOWN . 见 允许未知 更多信息。默认为 False .

projection

什么时候? True ,此选项启用 预测 功能。本地覆盖 PROJECTION .默认为 True .

embedding

什么时候? True 此选项启用 嵌入式资源序列化 功能。默认为 True .

extra_response_fields

允许配置附加文档字段列表,这些字段应随每个post响应一起提供。通常只自动处理字段 (ID_FIELDLAST_UPDATEDDATE_CREATEDETAG )包括在响应有效载荷中。覆盖 EXTRA_RESPONSE_FIELDS .

hateoas

什么时候? False ,此选项禁用 HATEOAS 为了资源。默认为 True .

mongo_query_whitelist

除了允许的运算符的正式列表之外,允许此端点使用的额外Mongo查询运算符的列表。默认为 [] .

mongo_write_concern

定义端点数据源MongoDB写关注设置的字典。支持所有标准写入问题设置(w、wtimeout、j、fsync)。默认为 {{'w': 1}} 这意味着“执行常规确认写入”(这也是Mongo的默认值)。

请注意,将“w”设置为2或更大的值要求复制处于活动状态,否则您将收到500个错误(写入仍将发生;Mongo将无法检查它是否正在写入多个服务器)。

mongo_prefix

允许覆盖默认值 MONGO 前缀,用于从配置中检索MongoDB设置。

例如,如果 mongo_prefix 设置为 MONGO2 然后,在为端点的请求提供服务时, MONGO2 前缀设置将用于访问数据库。

这允许最终在每个端点为来自不同数据库/服务器的数据提供服务。

参见: 身份验证驱动的数据库访问 .

mongo_indexes

允许在启动应用程序之前指定要为此资源创建的一组索引。

索引表示为一个dict,其中键是索引名,值是(字段、方向)对的元组列表,或者是具有字段/方向对列表的元组。 and 以dict表示的索引选项,例如 {{'index name': [('field', 1)], 'index with args': ([('field', 1)], {{"sparse": True}})}} .

多对用于创建复合索引。direction采用pymongo支持的所有类型的值,例如 ASCENDING =1和 DESCENDING =-1.所有索引选项,如 sparseminmax 等被支持(参见 PyMongo 文件。)

请注意: 请记住,索引的设计、创建和维护是一项非常重要的任务,应该精心计划和执行。通常,这也是一个非常资源密集型的行动。因此,您可能希望手动处理API的实例化。还请记住,在默认情况下,任何已经存在的、定义已被更改的索引都将被删除并重新创建。

authentication

具有端点授权逻辑的类。如果没有提供,将使用最终的通用身份验证类(作为应用程序构造函数参数传递)。有关身份验证和授权的详细信息,请参阅 认证和授权 . 默认为 None

embedded_fields

字段列表,其中 嵌入式资源序列化 默认情况下启用。要使此功能正常工作,列表中的字段必须 embeddableembedding 必须对资源有效。

query_objectid_as_string

启用后,mongo解析器将避免自动将可选择的字符串强制转换为objectid。这在数据库中的字符串字段很少出现的情况下很有用,这些字段的值实际上可以转换为objectid值,但不应该转换为objectid值。它会影响查询。 (?where= )分析有效载荷。默认为 False .

internal_resource

什么时候? True ,此选项使资源成为内部资源。无法在端点上执行HTTP操作,该端点仍然可以从EVE数据层访问。参见 内部资源 更多信息。默认为 False .

etag_ignore_fields

不应用于计算etag值的字段列表。默认为 None 这意味着默认情况下,所有字段都包含在计算中。看起来像 ['field1', 'field2', 'field3.nested_field', ...] .

schema

定义由资源处理的实际数据结构的dict。启用数据验证。参见 Schema Definition .

bulk_enabled

什么时候? True 此选项启用 大容量插入 此资源的功能。本地覆盖 BULK_ENABLED .

soft_delete

什么时候? True 此选项启用 软删除 此资源的功能。本地覆盖 SOFT_DELETE .

merge_nested_documents

如果 True ,对嵌套字段的更新将与上的当前数据合并。 PATCH .如果 False ,更新将覆盖当前数据。本地覆盖 MERGE_NESTED_DOCUMENTS .

normalize_dotted_fields

如果 True ,点域作为子文档域进行分析和处理。如果 False ,点式字段保持未处理状态,有效负载按原样传递给底层数据层。请注意,对于默认的mongo层,将其设置为 False 将导致错误。默认为 True .

normalize_on_patch

如果 True ,补丁文件将根据模式进行规范化。这意味着,如果一个字段不包含在补丁主体中,它将被重置为其模式中的默认值。如果 False ,未包含在补丁主体中的字段将保持不变。默认为 True .

下面是一个资源定制的例子,主要通过覆盖全局API设置来完成:

people = {
    # 'title' tag used in item links. Defaults to the resource title minus
    # the final, plural 's' (works fine in most cases but not for 'people')
    'item_title': 'person',

    # by default, the standard item entry point is defined as
    # '/people/<ObjectId>/'. We leave it untouched, and we also enable an
    # additional read-only entry point. This way consumers can also perform
    # GET requests at '/people/<lastname>'.
    'additional_lookup': {
        'url': 'regex("[\w]+")',
        'field': 'lastname'
    },

    # We choose to override global cache-control directives for this resource.
    'cache_control': 'max-age=10,must-revalidate',
    'cache_expires': 10,

    # we only allow GET and POST at this resource endpoint.
    'resource_methods': ['GET', 'POST'],
}

架构定义

除非您的API是只读的,否则您可能需要定义资源 schemas .模式很重要,因为它们能够对传入流进行适当的验证。

# 'people' schema definition
schema = {
    'firstname': {
        'type': 'string',
        'minlength': 1,
        'maxlength': 10,
    },
    'lastname': {
        'type': 'string',
        'minlength': 1,
        'maxlength': 15,
        'required': True,
        'unique': True,
    },
    # 'role' is a list, and can only contain values from 'allowed'.
    'role': {
        'type': 'list',
        'allowed': ["author", "contributor", "copy"],
    },
    # An embedded 'strongly-typed' dictionary.
    'location': {
        'type': 'dict',
        'schema': {
            'address': {'type': 'string'},
            'city': {'type': 'string'}
        },
    },
    'born': {
        'type': 'datetime',
    },
}

如您所见,模式键是实际的字段名,而值是定义字段验证规则的dict。允许的验证规则为:

type

字段数据类型。可以是以下之一:

  • string

  • boolean

  • integer

  • float

  • number (允许使用整数值和浮点值)

  • datetime

  • dict

  • list

  • media

如果使用MongoDB数据层,则 objectiddbref 地理数据结构也允许:

  • objectid

  • dbref

  • point

  • multipoint

  • linestring

  • multilinestring

  • polygon

  • multipolygon

  • geometrycollection

  • decimal

GeoJSON 有关地理字段的详细信息。

required

如果 True ,插入时该字段是必需的。

readonly

如果 True ,该字段为只读。

minlength, maxlength

允许的最小和最大长度 stringlist 类型。

min, max

允许的最小值和最大值 integerfloatnumber 类型。

allowed

允许值列表 stringlist 类型。

empty

仅适用于字符串字段。如果 False ,如果值为空,验证将失败。默认为 True .

items

定义允许在 list 固定长度,见 docs .

schema

的验证架构 dict 类型和任意长度 list 类型。有关详细信息和用法示例,请参见 Cerberus documentation .

unique

字段的值在集合中必须是唯一的。

请注意:验证约束是根据数据库检查的,而不是在有效负载文档之间检查的。这导致了一个有趣的情况:如果多个文档的有效负载中有两个或多个文档对设置了“unique”约束的字段具有相同的值,那么有效负载将成功验证,因为数据库中没有重复项(尚未)。

如果这是一个问题,客户机总是可以一次发送一个文档进行插入,或者在将有效负载提交给API之前在本地进行验证。

unique_to_user

字段值对用户是唯一的。当 用户限制的资源访问 在终结点上启用。将根据验证规则 仅限用户数据 .因此,在这种情况下,只要由不同的用户存储,就允许重复。相反,单个用户不能存储重复的值。

如果URRA在端点上不活动,则此规则的行为如下 unique

unique_within_resource

域的值在资源中必须是唯一的。

这与 unique 规则是在搜索字段具有相同值的文档时将使用数据源筛选器。如果资源与其他资源共享数据库集合,但在评估字段的唯一性时不应考虑它们的文档,请使用此选项。在没有数据源筛选器的资源中使用时,此规则的行为如下 unique .

data_relation

允许指定值必须满足的引用完整性规则才能进行验证。这是一个有四个键的口述:

  • resource :被引用资源的名称;

  • field :外部资源中的字段名;

  • embeddable :设置为 True 如果客户端可以请求将引用的文档嵌入到序列化中。参见 嵌入式资源序列化 .默认为 False .

  • version :设置为 True 要求 _version 与数据关系。参见 文档版本控制 .默认为 False .

nullable

如果 True ,字段值可以设置为 None .

default

字段的默认值。当提供POST和PUT请求时,丢失的字段将被分配配置的默认值。

它也适用于类型 dictlist .后者是受限制的,仅适用于具有模式的列表(具有随机数量的元素的列表,并且每个元素都是 dict

schema = {
  # Simple default
  'title': {
    'type': 'string',
    'default': 'M.'
  },
  # Default in a dict
  'others': {
    'type': 'dict',
    'schema': {
      'code': {
        'type': 'integer',
        'default': 100
      }
    }
  },
  # Default in a list of dicts
  'mylist': {
    'type': 'list',
    'schema': {
      'type': 'dict',
      'schema': {
        'name': {'type': 'string'},
        'customer': {
          'type': 'boolean',
          'default': False
        }
      }
    }
  }
}

versioning

启用文档版本控制的时间 True .默认为 False .

versioned

如果 True ,此字段将包含在每个文档的版本历史记录中,当 versioning 已启用。默认为 True .

valueschema

的所有值的验证架构 dict .dict可以具有任意键,所有键的值都必须使用给定的模式进行验证。参见 valueschema 在赛伯勒斯医生。

keyschema

这是对应的 valueschema 验证dict.validation架构的所有值的键 dict . 见 keyschema 在赛伯勒斯医生。

regex

如果字段值与提供的regex规则不匹配,验证将失败。仅适用于字符串字段。参见 regex 在赛伯勒斯医生。

dependencies

此规则允许为允许目标字段而必须存在的字段列表。参见 dependencies 在赛伯勒斯医生。

anyof

此规则允许您列出要验证的多组规则。如果该字段针对列表中的一个集进行验证,则该字段将被视为有效。参见 *of-rules 在赛伯勒斯医生。

allof

等同于 anyof ,但列表中的所有规则集合都必须验证。

noneof

等同于 anyof ,但它不需要在列表中验证任何规则集合。

oneof

等同于 anyof ,但列表中只有一个规则集合可以验证。

coerce

类型强制允许您在任何其他验证程序运行之前对值应用可调用。可调用文件的返回值将替换文档中的新值。这可用于在验证前转换值或清理数据。参见 value coercion 在赛伯勒斯医生。

架构语法基于 Cerberus 是的,它可以扩展。实际上,eve本身通过添加 uniquedata_relation 关键字,以及 objectid 数据类型。有关自定义验证和使用示例的详细信息,请参阅 数据验证 .

资源/项目终结点 你定制了 people endpoint. Then, in this section, you defined people validation rules. Now you are ready to update the domain which was originally set up in Domain Configuration

# add the schema to the 'people' resource definition
people['schema'] = schema
# update the domain
DOMAIN['people'] = people

高级数据源模式

这个 datasource 关键字允许将API资源显式链接到数据库集合。如果省略,则假定域资源键也是数据库集合的名称。它是一个字典,有四个允许的键:

source

资源使用的数据库集合的名称。如果省略,则假定资源名称也是有效的集合名称。参见 多个API端点,一个数据源 .

filter

用于检索和验证数据的数据库查询。如果省略,则默认情况下会检索整个集合。参见 预定义的数据库筛选器 .

projection

终结点公开的字段集。如果省略,默认情况下,所有字段都将返回给客户机。参见 限制API端点公开的字段集 .

default_sort

在端点检索到的文档的默认排序。如果省略,文档将以默认的数据库顺序返回。一个有效的声明是:

'datasource': {'default_sort': [('name', 1)]}

有关排序和筛选的详细信息,请参阅 过滤 .

aggregation

聚合管道和选项。当使用所有其他 datasource 设置被忽略,除非 source .终结点将是只读的,并且没有可用的项查找。默认为 None .

这是一本具有以下一个或多个键的字典:

  • pipeline .聚合管道。语法必须与pymongo支持的语法匹配。有关详细信息,请参阅 PyMongo Aggregation Examples 还有官员 MongoDB Aggregation Framework 文档。

  • options .聚合选项。必须是具有以下一个或多个键的字典:

    • allowDiskUse (布尔)

    • maxTimeMS (国际)

    • batchSize (国际)

    • useCursor (布尔)

你只需要设置 options 如果你想改变 PyMongo aggregation defaults .

预定义的数据库筛选器

API端点的数据库筛选器是用 filter 关键字。

people = {
    'datasource': {
        'filter': {'username': {'$exists': True}}
        }
    }

在上面的示例中, people 资源将仅使用现有的 username 字段。

在用户查询上运行的预定义筛选器(使用 where 条款)和标准条件请求 (If-Modified-Since 等)

请注意,数据源过滤器应用于get、patch和delete请求。如果您的资源允许发布请求(文档插入),那么您可能需要相应地设置验证规则(在我们的示例中,“用户名”可能是必需字段)。

静态与动态过滤器

预定义的过滤器是静态的。你也可以利用 事件钩子 系统(具体来说, on_pre_<METHOD> hooks)来设置动态过滤器。

多个API端点,一个数据源

多个API终结点可以针对同一数据库集合。例如,您可以同时设置 /admins/users 读和写 people 数据库上的集合。

people = {
    'datasource': {
        'source': 'people',
        'filter': {'userlevel': 1}
        }
    }

上面的设置将只检索、编辑和删除 people 集合 userlevel 第页,共1页。

限制API端点公开的字段集

默认情况下,对GET请求的API响应将包括由相应资源定义的所有字段 schema. 这个 projection 设置 datasource resource关键字允许您重新定义字段集。

当你想隐藏一些 秘密领域 从客户端,您应该使用包含投影设置,并且包含所有字段都应该公开。当您希望将默认响应限制到某些字段,但仍允许通过客户端投影访问这些字段时,应使用独占投影设置,并且应忽略排除字段。

以下是包含投影设置的示例:

people = {
    'datasource': {
        'projection': {'username': 1}
        }
    }

上述设置将只显示 username 获取请求的字段,无论 schema 为资源定义。以及其他领域 不会 即使通过客户端投影也会暴露出来。以下API调用将不会返回 lastnameborn .

$ curl -i http://myapi/people?projection={"lastname": 1, "born": 1}
HTTP/1.1 200 OK

还可以从API响应中排除字段。但这次,排除的字段 暴露于客户端投影。以下是独占投影设置的示例:

people = {
    'datasource': {
        'projection': {'username': 0}
        }
    }

上面将包括所有文档字段,但是 username .但是,以下API调用将返回 username 这次。因此,您可以利用这种行为服务于媒体领域或其他昂贵的领域。

在大多数情况下,首选无投影或包含投影设置。通过包含投影,机密字段从服务器端得到处理,返回的默认字段可以由客户端的快捷函数定义。

$ curl -i http://myapi/people?projection={"username": 1}
HTTP/1.1 200 OK

请注意,post和patch方法仍然允许操作整个模式。例如,当您希望保护 认证和授权 方案,同时保持对公众开放的读取访问权限。