DreamFactory 第7章 限制和记录API请求
在本章中,您将学习如何使用DreamFactory的API限制和日志记录功能来分配和监视对受限API的访问。
记录
无论您是调试API工作流还是遵守法规要求,日志记录都将在此过程中发挥关键作用。在本节中,我们将介绍与配置和管理DreamFactory平台日志以及通过DreamFactory的Elastic Stack集成管理的日志有关的各种最佳实践。
介绍DreamFactory平台日志
DreamFactory开发人员和管理员通常将需要使用信息和错误消息来调试平台行为。可以在.env
文件中或服务器环境变量中配置此日志记录行为。如果打开.env
文件,则会在文件顶部找到以下与日志记录相关的配置参数:
APP_DEBUG
:设置true
为时,如果引发异常,将返回调试跟踪。虽然在开发阶段很有用,但您无疑要false
在生产中将其设置为。APP_LOG
:默认情况下,DreamFactory将日志条目写入名为dreamfactory.log
中的文件storage/logs
。这称为单文件模式。您可以将DreamFactory配置为将日志条目分解为日常文件,例如dreamfactory-2019-02-14.log
通过设置APP_LOG
为daily
。但是请记住,默认情况下,仅保留5天的日志文件。您可以通过将所需的天数指定为来更改此默认设置APP_LOG_MAX_FILES
。或者,您可以通过将设置APP_LOG
为syslog
或发送给操作系统错误日志,将日志条目发送到操作系统syslogerrorlog
。APP_LOG_LEVEL
:该参数确定日志灵敏度的水平,并可以被设置为DEBUG
,INFO
,NOTICE
,WARNING
,ERROR
,CRITICAL
,ALERT
,和EMERGENCY
。当此参数设置为DEBUG
,INFO
或时NOTICE
,DreamFactory可能非常健谈,因此请警惕在生产环境中使用这些设置。另外,要记住这些设置是分层次的,如果你设置意味着APP_LOG_LEVEL
要WARNING
为实例,那么所有的WARNING
,ERROR
,CRITICAL
,ALERT
,和EMERGENCY
消息将被记录。
这是发送到日志的典型输出的示例:
[2019-02-14 22:35:45] local.DEBUG: API event handled: mysql._table.{table_name}.get.pre_process
[2019-02-14 22:35:45] local.DEBUG: API event handled: mysql._table.employees.get.pre_process
[2019-02-14 22:35:45] local.DEBUG: API event handled: mysql._table.{table_name}.get.post_process
[2019-02-14 22:35:45] local.DEBUG: API event handled: mysql._table.employees.get.post_process
[2019-02-14 22:35:45] local.DEBUG: Service event handled: mysql._table.{table_name}.get
[2019-02-14 22:35:45] local.DEBUG: Logged message on [mysql._table.{table_name}.get] event.
[2019-02-14 22:35:45] local.DEBUG: Service event handled: mysql._table.{table_name}.get
[2019-02-14 22:35:45] local.DEBUG: Service event handled: mysql._table.employees.get
[2019-02-14 22:35:45] local.INFO: [RESPONSE] {"Status Code":200,"Content-Type":null}
[2019-02-14 22:35:45] local.INFO: [RESPONSE] {"Status Code":200,"Content-Type":"application/json"}
#Logstash
DreamFactory的黄金版通过Logstash连接器提供了Elastic Stack(Elasticsearch,Logstash,Kibana)支持。该连接器可以轻松地与Elastic.io的其余ELK堆栈(Elasticsearch,Logstash,Kibana)进行接口,或连接到其他分析和监视源,例如开源Grafana。
如果您不熟悉Logstash,并且正在寻找一种简单而又便宜的入门方法,我们建议您阅读并跟随名为“ 如何在Ubuntu 18.04上安装Elasticsearch,Logstash和Kibana ”的出色Digital Ocean教程 。
要启用Logstash连接器,您将像配置其他任何服务时一样开始。导航至Services
,然后Create
在Service Type
选择框中选择Log > Logstash
。然后,像配置其他服务时一样添加名称,标签和描述:
接下来,导航到服务创建页面顶部的“配置”选项卡。在接下来的两个屏幕截图中,您可以看到需要选择的字段和选项。在第一个屏幕截图中,您将添加主机。在这种情况下,我将在我的DreamFactory实例上本地托管Logstash连接器。其他选项是Port
和Protocol/Format
。该端口与您的Logstash守护程序在其中运行的端口相对应。该Protocol/Format
字段应设置为与Logstash服务配置为接受输入的协议/格式相匹配:
- GELF(UDP):创建GELF(GrayLog扩展格式)作为syslog格式的优化替代方案。在此处了解更多信息。
- HTTP:如果您的Logstash服务配置为侦听HTTP协议,请选择此选项。DreamFactory将以JSON格式将数据发送到Logstash。
- TCP:如果您的Logstash服务配置为侦听TCP协议,请选择此选项。DreamFactory将以JSON格式将数据发送到Logstash。
- UDP:如果您的Logstash服务配置为侦听UDP协议,请选择此选项。DreamFactory将以JSON格式将数据发送到Logstash。
在第二个屏幕截图中,您可以通过Logstash连接器看到一些可用的日志记录选项。我还添加了一些我想登录的服务。您可以选择要记录的各个级别的信息。有关更多详细信息,请参阅本文。有效选项包括:
- 致命
- 错误
- 警告
- 信息
- 调试
- 跟踪
- 信息
从Elastic Stack过滤敏感数据
诸如社会安全号码,出生日期和遗传数据之类的敏感信息必须经常以特殊方式处理,并且通常完全从日志文件中排除。幸运的是,Logstash提供了一套强大的功能,用于在将数据插入Elasticsearch之前删除和变异数据。例如,如果您想防止将API密钥记录到Elasticsearch中,则可以定义以下过滤器:
filter {
json {
source => "message"
remove_field => ["[_platform][session][api_key]", "[_event][request][headers][x-dreamfactory-api-key]"]
}
}
对Logstash环境进行故障排除
如果您没有在Kibana上看到结果,则应该做的第一件事就是确定Logstash是否正在与Elasticsearch对话。您可以在Logstash日志中找到有用的诊断信息,这些信息可以在中找到,LS_HOME/logs
也可以在中找到/var/log/logstash
。如果您的Logstash环境无法与Elasticsearch对话,您将在日志中找到以下错误消息:
[2019-02-14T16:20:24,403][WARN ][logstash.outputs.elasticsearch] Attempted to resurrect connection to dead ES instance, but got an error
如果Logstash无法与Elasticsearch对话,并且服务位于两个单独的服务器上,则问题很可能是由于防火墙限制。
其他Logstash资源
DreamFactory API速率限制
可以为特定的用户,角色,服务或端点设置DreamFactory限制。此外,您可以为每个用户设置限制,每个用户将获得一个单独的计数器。可以创建限制以仅与特定的HTTP动词进行交互,例如,GET
也可以为POST
特定服务创建另一个限制。端点限制还提供了另一种强大的方式来限制DreamFactory实例内的粒度。
限制层次结构
可以创建限制以覆盖整个实例,或提供覆盖特定端点的覆盖范围。合并限制后,会创建一种限制层次结构,其中较宽的限制有时可以覆盖更细粒度的限制。例如,为整个实例创建的限制为每分钟500次点击。如果为每分钟1,000次命中的特定服务创建了限制,则实例限制将429 HTTP
在一分钟内达到500次命中时发出(超出限制)错误,因此服务限制永远不会达到1,000。在创建多个限制和计划限制策略时,请务必牢记全局。将更广泛的限制类型设置为更细粒度的限制。
限制类型
每个API限制均基于限制过期和重置时的特定时间段。此处的选项是可配置的,包括分钟,小时,天,7天(周)和30天(月)。各种限制类型与限制期限相结合,可以对您的实例进行广泛的控制。下表概述了可用的不同限制类型。
限制类型 | 描述 |
---|---|
实例 | 控制整个实例的速率限制,以包括所有服务,角色和用户。无论用户,服务等如何,此处的限制计数器都是累积的 |
用户 | 为指定用户提供速率限制控制。如果同时设置了用户限制和“每个用户”限制,则特定于用户的限制将在费率方面优先于“每个用户”。但是,两个计数器仍将递增。 |
每个用户 | 设置每个用户的速率限制。此实例与整个实例之间的主要区别在于,每个用户都有一个单独的计数器。 |
角色 | 通过指定角色启用速率限制。 |
服务 | 启用指定服务的速率限制。 |
用户服务 | 为特定服务上的特定用户启用速率限制。 |
每个用户的服务 | 为特定服务上的每个用户启用速率限制。 |
终点 | 启用指定端点的速率限制。 |
用户端点 | 在特定端点上为特定用户启用速率限制。 |
每个用户的端点 | 在特定端点上为每个用户启用速率限制。 |
限期 | 限制时间包括分钟,小时,天,7天(周)和30天(月)。限制期限确定了该限制有效的时间,直到该期限到期后自动重置为止。 |
通过API的限制
与DreamFactory中的所有其他服务一样,只要用户对系统/资源具有适当的权限,就可以仅通过API来管理限制。可以从以下端点管理限制:
api/v2/system/limit
-端点管理CRUD操作的限制。api/v2/system/limit_cache
-端点以检查电流限制量水平并手动重置限制计数器。
创建极限
限制通过发送创建POST
到/api/v2/system/limit
。要创建一个简单的实例限制,POST
需要向端点提供以下资源:
限制类型 | API“类型”参数 | 其他必需参数* |
---|---|---|
实例 | 实例 | 不适用 |
用户 | instance.user | 用户身份 |
每个用户 | instance.each_user | 不适用 |
服务 | 实例服务 | service_id |
用户服务 | instance.user.service | user_id,service_id |
每个用户的服务 | instance.each_user.service | service_id |
终点 | instance.service.endpoint | service_id,端点 |
用户端点 | instance.user.service.endpoint | user_id,service_id,端点 |
每个用户的端点 | instance.each_user.service.endpoint | service_id,端点 |
角色 | instance.role | 角色编号 |
所需的标准参数包括:类型,费率,期限和名称。下表描述了创建限制时可以传递的所有可用参数。
参数 | 类型 | 需要 | 描述 |
---|---|---|---|
类型 | {串} | 是 | 您正在创建的实例的类型。有关详细说明,请参见上表 |
key_text | {串} | 不适用 | 仅供参考。该密钥是系统自动构建的,是限制的唯一标识符。 |
率 | {整数} | 是 | 限制期内允许的点击数。 |
期 | {枚举} | 是 | 限制自动重置的时间段。有效值为:“分钟”,“小时”,“天”,“ 7天”,“ 30天” |
用户身份 | {整数} | (见上表) | 用户ID用于用户类型限制。 |
角色编号 | {整数} | (见上表) | 角色类型限制的角色ID。 |
service_id | {整数} | (见上表) | 服务和端点类型限制的服务ID。 |
名称 | {串} | 是 | 限制的任意名称(必填)。 |
描述 | {串} | 没有 | 限制说明(可选) |
活跃 | {boolean} | 没有 | 默认为true。此外,您可以创建处于“非活动”状态的限制,此限制可以在以后激活(可选)。 |
create_date | {timestamp} | 不适用 | 仅供参考。 |
last_modified_date | {timestamp} | 不适用 | 仅供参考。 |
终点 | {串} | (见上表) | 端点字符串(必要时请参见上表)。此外,请参考“端点限制”部分以获取更多信息。 |
动词 | {枚举} | 没有 | 默认为所有动词。传递单个动词只会设置这些请求的限制。可以使用任何限制类型指定。有效值是: GET ,POST ,PUT ,PATCH ,DELETE |
用户数与每个用户数限制
您可以为整个实例,特定服务或特定端点的特定用户分配限制。这种限制类型只会影响单个用户,而不会影响整个实例,服务或端点。也可以为此创建每个用户类型限制,主要区别在于,在“每个用户”限制中,每个用户将获得一个单独的计数器。例如,如果您对特定服务设置了限制,并将速率设置为每天1,000次点击,则单个用户可以达到该限制,并且无论该用户是谁,都会影响到该服务的任何后续请求。在“每个用户服务”类型限制中,每个用户将获得一个单独的计数器,以达到每天1,000个的计数。其他限制类型也一样。
警告
注意:无法使用“每个用户”类型限制来清除单个用户的计数器,只能使用“用户”限制来清除。清除“每个用户”限制类型的计数器将重置所有用户。
服务限制
创建服务限制时,您将基于特定服务进行限制。要创建这种类型的限制,请传入您要创建的服务的ID。
角色限制
角色限制与服务限制大致相同,但是结合了角色中的安全设置,您可以创建一些非常强大的基于角色的限制组合。
端点限制
端点限制使API管理员可以非常清楚地了解可以选择哪种类型的请求以进行限制。基本上,管理应用程序的“ API文档”标签中可用的任何内容都可以用作端点限制。端点限制可以并且在某些情况下应与特定动词组合。由于DreamFactory中的所有端点都绑定到服务中,因此在创建端点限制时需要service_id。因此,如果要定位db/_table/contact
,则需要按id选择db服务,并以字符串形式提供其余的端点。例:
如上例所示,创建限制类型只会在请求的特定资源与存储的限制完全匹配时才会生效。因此,只会_table/contact
增加极限计数器,不会增加_table/contact/5
或增加端点参数的变化。
通配符端点
因为在某些情况下您想限制一个端点以及端点上的所有变体,所以我们内置了将通配符添加到端点限制的功能。因此,通过向*
端点添加通配符,您将创建一个端点限制,该限制将与特定端点以及所有其他参数一起出现。每个端点限制都与服务关联。因此,端点限制只是服务类型限制的扩展。服务限制将为服务下的每个端点提供限制覆盖范围,而端点限制则更具针对性。结合通配符和特定动词,端点限制变得非常强大。
限制缓存
默认情况下,Limits使用基于文件的缓存存储系统。垃圾收集是自动的,并且基于限制期限。您可以通过API轮询限制缓存系统,以获取每个限制的当前点击计数。GET
对system / limit_cache 的调用将提供限制的ID,唯一键,最大尝试次数和当前尝试次数以及限制期内的剩余尝试次数。
清除限制缓存
清除限制高速缓存涉及将计数器重置为特定限制。此外,通过将allow_delete=true
参数传递给system / limit_cache端点,可以立即重置所有限制计数器。Id
将特定限制的传递给system/limit_cache endpoint
,例如system/limit_cache/11
只会清除该特定限制的限制计数器。
限制缓存存储选项
默认情况下,限制缓存使用基于文件的缓存。该文件缓存与DreamFactory(主)缓存分开,因此在DreamFactory中清除缓存时,限制计数不会受到影响。Redis也可以与限制缓存一起使用。请参阅.env-dist
文件以了解限制缓存选项。