报告HTTP API

关于本指南

阅读本指南,如果

  • 你肯定想知道Matomo(以前的Piwik)的Reporting API是如何工作的,你的插件如何扩展它
  • 你肯定想知道Matomo的Reporting API在数据被服务之前对数据做了什么
  • 你肯定想知道什么输出格式可以用来查看从Reporting API返回的数据
  • 你肯定想知道关于报表API用来转换分析数据的查询参数

指南的假设

本指南假设您:

  • 会用PHP编程,
  • 了解报表如何存储在内存中(如果没有阅读报告指导),
  • 并对扩展Matomo有一个大致的了解(如果没有,请阅读我们的开始指南)。

报告API

Piwik是报告API允许第三方应用程序通过HTTP请求访问分析数据并操纵其他数据(除了报告或跟踪数据之外的任何数据)。

API请求

的每个HTTP API请求API.index控制器方法将由Reporting API处理。有效的请求必须查询参数名为方法引用API方法来调用,例如,UserSettings.getBrowser

API请求的处理方式如下:

  1. API::指数()方法创建Piwik \ \ API请求实例,并使用它来分派API请求。
  2. 请求实例使用方法参数来确定使用哪个插件和API方法。
  3. 请求实例使用查询参数作为参数调用插件的API方法。与方法参数同名的查询参数将被传递给方法。例如,idSite查询参数将作为idSite美元方法参数。
  4. 请求实例使用ResponseBuilder实例处理API方法的结果,并将其转换为所需的输出格式。
  5. 返回到API::指数()控制器方法,并作为HTTP响应发送。

API方法

Reporting API调用每个插件中的方法API类。但是,以下方法不能从HTTP API调用:

  • 私有和受保护的方法
  • 方法,其文档包含@ ignore标签

查询参数作为方法参数传递。因此API方法必须假设方法参数为字符串或数组值。对象不允许作为参数。

方法只允许返回以下值:

备注:返回时数据表DataTable \地图实例,过滤器将需要应用。确保对用于表示目的的筛选器进行排队,并直接应用其他筛选器。

如果方法抛出异常,其消息将出现在输出中。在调试过程中,通过更改可以显示堆栈跟踪ResponseBuilder: DISPLAY_BACKTRACE_DEBUG真正的

可以看到Matomo安装暴露的所有API方法的列表:单击API链接在顶部菜单。请参阅演示列表在这里

额外的报表处理

API方法返回的报告(例如:数据表DataTable \地图实例)加工过的在被输出之前。

一套DataTable \ BaseFilter将根据某些查询参数的值在报表上执行。

这是按应用顺序排列的过滤器列表:

  1. 压延机:合并整个数据表层次归一数据表,将子表行添加到它们的父行。
    • :设置为1应用过滤器
  2. 模式:删除a的行数据表不匹配正则表达式模式。
    • filter_pattern正则表达式(如果设置,则应用过滤器)
    • filter_column:列,将正则表达式模式应用到(标签默认为列)
  3. PatternRecursive:删除a的行数据表该行及其所有子表与正则表达式模式不匹配。
    • filter_pattern_recursive正则表达式(如果设置,则应用过滤器)
    • filter_column_recursive:列,将正则表达式模式应用到(标签默认为列)
  4. ExcludeLowPopulation:删除包含低于最小阈值的特定列的所有行。
    • filter_excludelowpop:要筛选的列(如果设置了,则应用筛选)
    • filter_excludelowpop_value:最小阈值,默认为0
  5. AddColumnsProcessedMetrics:向报告的每一行添加一些通用的已处理指标。
    • filter_add_columns_when_show_all_columns:设置为1应用过滤器
  6. AddColumnsProcessedMetricsGoal:为站点的每个目标的每一行添加已处理的指标。
    • filter_update_columns_when_show_all_goals:设置为1应用过滤器
    • idGoal:目标ID或以下特殊值之一:
      • AddColumnsProcessedMetricsGoal: GOALS_OVERVIEW(默认值):为总体目标而不是单个目标添加指标
      • AddColumnsProcessedMetricsGoal: GOALS_MINIMAL_REPORT:只增加一个指标:revenue_per_visit(没有每个目标的指标将被添加)
      • AddColumnsProcessedMetricsGoal: GOALS_FULL_TABLE:显示网站每个目标的指标,包括电子商务目标
  7. 排序:对行进行排序。
    • filter_sort_column:要排序的列(如果设置了则应用筛选器)
    • filter_sort_order“desc”“asc”
  8. 截断:删除指定行索引后的所有行。
    • filter_truncate:行号,之后的行应该被删除(如果设置了,则应用筛选器)
  9. 限制:删除不在特定行索引范围内的行。
    • filter_limit:范围的大小(如果设置了,则应用过滤器)
    • filter_offset:范围的起始行索引
    • keep_summary_row:如果设置为1,则汇总行保留在报表中
  10. SafeDecodeLabel: url解码,然后消毒标签列值。这个过滤器总是被应用。
  11. 排队过滤器:所有的数据表的队列筛选器在此时应用。
    • disable_queued_filters:如果设置为1,队列筛选器将不会被应用
  12. ColumnDelete:基于排除列表或包含列表删除列。
    • hideColumnsshowColumns:要隐藏或保留的以逗号分隔的列名列表(如果设置了一个,则应用筛选器)
  13. LabelFilter属性指定的一行或几行之外,此筛选器将删除所有行标签查询参数。只适用于标签完成查询参数的设置。
    • 标签:可以是单个值,也可以是子表中某一行的路径。要分解为子表,值应包含>比如性格,urldir > urlsubdir >索引.也可以是一个值的数组,例如,标签[]= arg1&label[] =最长

其他特殊查询参数

还有其他一些特殊的查询参数会影响报表的处理方式:

  • disable_generic_filters:如果设置为1,上述编号为2 - 9的过滤器将不适用。默认为0因此,如果该参数不存在,将应用过滤器。
  • 格式:决定输出格式返回值的。这将影响所有返回值,而不管它是报告还是标量值。

输出格式

Reporting API请求的输出是API方法返回值的序列化字符串。属性的值决定该字符串的格式格式查询参数。目前Matomo支持以下输出格式:

有一个特殊的输出格式值,原始,可以在Matomo使用中请求数据时使用Piwik \ \ API请求.这种格式将强制将结果作为未处理和未序列化的数据返回。它只能在PHP中调用Matomo中的API时使用。

注意:要求::processRequest ()方法自动使用原始格式,所以在大多数情况下,您不需要指定原始格式=

特殊API方法

API插件中的一些API方法有特殊的含义和用途:

报告元数据

API.getMetadataAPI.getReportMetadata而且API.getProcessedReportAPI方法可用于获取关于一个或所有报表的信息。信息包括报告中包含的指标、这些指标的文档和更多的

第三方应用程序可以使用这些方法,为Matomo存储的分析提供接口:

  • API.getReportMetadata为每个报告返回元数据,它可以用来获得一个网站的所有可用报告的列表
  • API.getMetadata可以用来获得关于单个报告的更多信息吗
  • API.getProcessedReport可用于获取单个报表的元数据以及报表的数据。

在Matomo中,报表元数据还可以用于对用户指定的报表进行操作的特性。例如,ImageGraph插件,它使用报表数据输出图形的图像,使用报表元数据值作为如何绘制输出图形的提示。的ScheduledReports插件也以类似的方式使用报表元数据。

行进化

Matomo的行演化特征可以通过UI获得的信息也可以通过Reporting API获得。第三方应用程序可以使用API.getRowEvolution方法来同时获取两者单行进化数据多行进化数据

大量API请求

比如跟踪API, Reporting API支持批量请求。批量请求允许应用程序用一个HTTP请求调用和检索多个API方法的结果。这可以用来节省应用程序查询Matomo HTTP API的时间。

要发送批量请求,请将HTTP请求发送到API.getBulkRequestAPI方法。唯一需要的查询参数被命名url.它应该是单个API请求url的数组。例如:

https://demo.www.hju8.com/?module=API&method=API.getBulkRequest&format=xml&urls[] =模块% 3 dapi % 26方法% 3 dvisitorinterest.getnumberofvisitspervisitduration % 26格式% 3 dxml % 26 idsite % 3 d62 % 26期% 3 dday % 26日% 3 d2013-11-24 % 26扩大% 3 d1&urls[] =模块% 3 dapi % 26方法% 3 dusersettings.getbrowser % 26格式% 3 dxml % 26 idsite % 3 d7 % 26期% 3 dday % 26日% 3 d2013-11-24 % 26扩大% 3 d1

本例使用以下API请求:

  • 模块= api方法= UserSettings.getBrowser&format = XML&idSite = 62期=日期与星期= 2013 - 11 - 24扩大= 1
  • 模块= api方法= VisitorInterest.getNumberOfVisitsPerVisitDuration&format = XML&idSite = 62期=日期与星期= 2013 - 11 - 24扩大= 1

注意:单独的API方法是同步执行的,因此对于长时间运行的API方法,使用批量请求可能不是一个好主意。

其他方法

  • API.get:调用得到API方法的所有加载的插件,支持它并合并结果。的得到方法都输出插件存档的度量,因此的结果API.get是您的Matomo安装支持的每个指标的值集(用于指定的网站和期间)。
  • API.getSegmentDimensionMetadata:返回每个支持的元数据部分尺寸.每个段维度返回以下信息:
    • 类型:段尺寸类型。
    • 类别:描述段维度类别的翻译字符串。
    • 的名字:描述段维度本身的翻译字符串或翻译标记。
    • :段维度的ID。这是在段表达式中使用的。
    • acceptedValues:描述段维度应该使用什么值的字符串。
    • sqlSegment:段维所操作的表列,例如:log_visit.idvisitor
    • sqlFilterValue:一个可选的PHP回调函数,它在SQL表达式中使用之前转换段表达式中提供的值。
    • 许可:当前用户是否可以使用该段维度。
  • API.getSuggestedValuesForSegment:返回可用于指定段维度的值列表。
  • API.getLogoUrl:返回一个指向Matomo标志的URL。
  • API.getHeaderLogoUrl:返回一个指向Matomo标志的缩小版的URL。

了解更多

  • 学习如何在内部使用API类阅读我们的Matomo api指南。
  • 学习关于如何计算报表阅读我们的报告指南。
Baidu