编辑“Open Web Analytics/数据访问API”

{{Open Web Analytics top}}
数据访问接口（Data Access API），为你在OWA报告界面之外请求和使用数据提供了一种方法。接口提供了一种灵活的语法来描述具体的指标及维度参数，这些维度参数都是你想包含在结果集中的，以及过滤、排序、格式要求所需要的。

这些数据访问接口可以通过REST请求或者PHP方法getResultSet来访问。
==利用PHP获得结果集==
举例：
 $params = array('do'          => 'getResultSet',
                'metrics'     => 'visitDuration,bounces,repeatVisitors,newVisitors,visits,pageViews',
                'dimensions'  => 'date,browserType',
                'constraints' => 'browserType=Firefox 3.5',
                'startDate'   => '20100312',
                'endDate'     => '20100331',
                'sort'        => 'date-,browserType',
                'limit'       => 10,
                'siteId'      => 'yoursiteid'
               );
 $result_set = owa_coreAPI::executeApiCommand($params);


==利用REST获得结果集==
举例：
  http://yourdomain/owa/api.php
  ?owa_apiKey=b6b9c9b9016d2b8b3b9b52e67eba06a3
  &owa_do=getResultSet
  &owa_metrics=visitDuration,bounces,repeatVisitors,newVisitors,visits,pageViews
  &owa_dimensions=date,browserType
  &owa_constraints=browserType%3dFirefox%203.5
  &owa_startDate=20100312
  &owa_endDate=20100331
  &owa_limit=10
  &owa_siteId=your_site_id
  &owa_format=xml
可以在 [[Open Web Analytics/REST API|REST API]] 中阅读关于怎样构建请求。
==请求的属性值==
OWA提供了一些请求的属性值，让用户可以获得具体的结果集。

*'''Metrics:'''
指标(必须的）。
 
 '''REST:'''  owa_metrics=visitDuration,bounces,repeatVisitors,newVisitors,visits,pageViews 

 '''PHP:'''   'metrics' => 'visitDuration,bounces,repeatVisitors,newVisitors,visits,pageViews' 

指标表示一些网站或应用程序的用户活动的汇总统计，比如访问数、页面访问量、事件自定义操作等。你可以在一个请求中获得多个度量，只要他们是一个有效的组合。获得多个度量，只需要将度量的名字用英文逗号分开就行。

用户可以访问[[Open Web Analytics/Metrics and Dimensions|Metrics&Dimensions]]来查看OWA支持的所有度量。

*'''Dimensions:'''
维度参数（可选的）。

 '''REST:''' owa_dimensions=date,browserType 

 '''PHP:''' 'dimensions' => 'date,browserType' 

维度参数是用来描述站点上用户活动某些方面的数据元素，它们在结果集中非常有用，因为它们允许你进入更详细的分部或分项总指标。例如，不是请求您的网站的访问者的总数，而是加入像“国家”的一个参数，将允许您检索来自每一个城市的页面访问指标。

你可以在一个请求中添加多个维度参数，只需要用逗号将这些参数名称分开就行。

更多的维度参数，可以在[[Open Web Analytics/Metrics and Dimensions|Metrics&Dimensions]]中查看。

*'''startDate:'''
起始时间（必须的）。

 '''REST:''' owa_startDate=20100310 

 '''PHP: ''' 'startDate' => '20100310' 

所有的getResultSet请求必须使用period（时间间隔）、startDate、endDate 参数 或者startTime、endTime参数。

起始时间的格式是YYYYMMDD，分别四位的年份、两位的月份、两位的具体某一天。

起始时间可以是未来某个时间，但是可能造成你的请求返回的是空数据。

*'''endDate:''' 
截止时间（必须的）。

 '''REST:''' owa_endDate=20100320 

 '''PHP: ''' 'endDate' => '20100320' 

所有的getResultSet请求必须使用period（时间间隔）、startDate、endDate 参数 或者startTime、endTime参数。

截止时间的格式是YYYYMMDD，分别四位的年份、两位的月份、两位的具体某一天。

截止时间必须与起始时间一致或者比起始时间晚。

*'''Constraints:'''
约束条件（可选的）。

 '''REST:'''  owa_constraints=browserType%3dFirefox%203.5 

 '''PHP:'''  'constraints' => 'browserType=Firefox 3.5' 


为了获得满足某一特定条件的返回结果，我们可以在请求中添加约束条件。

约束条件有这些表单项：
'''name：'''  通过指标或者维度参数来约束返回结果，这里就是这些指标或者维度参数的名称；
'''operator：''' 操作符，用来定义约束的类型；
'''expression：''' 约束必须必须评估的一个值或多个值。

举例：

{| class="wikitable"
! Operator
! 描述
! URL的编码
! 举例
|-
| =
| 等号
| %3D
| 返回来自布鲁克林城市的结果:
constraints=city%3Dbrooklyn
|-
| !=
| 不等号
| !%3D
| constraints=city!%3Dbrooklyn
|-
| >	
| 大于号	
| %3E	
| tdb
|-
| <	
| 小于号
| %3C
| tbd
|-
| >=
| 大于等于号	
| %3E%3D	
| tbd
|-
|<=	
| 小于等于号	
| %3C%3D
| tbd
|-
| =~	
| 包含正则表达式匹配	
| %3D~	
| 返回来自以 "New"开头的城市的结果: <code>constraints=city%3D~%5ENew.</code>
'' (%5E 是字符 ^ 在url中的编码，表示一个字符串的开头格式.)'''
|-
| !~	
| 不匹配正则表达式	
| none	
| 返回不以"New"开头的城市的结果: <code>constraints=city!~%5ENew</code>
|-
| =@
| 包含子串	
| %3D@
| 返回名字中包含"York"子串的城市的结果: <code>constraints=city%3D@York</code>
|-
| !@	
| 不包含子串	
| none
| 返回名字中不包含"York"子串的城市的结果：<code>constraints=city!@York</code>
|}

*'''Sort :'''
排序（可选的）。

  '''REST: ''' owa_sort=date-,browserType 

PHP: 'sort' => 'date-,browserType ' 

具体设置你想用来进行排序的维度参数。排序是发生在具体的命令中的。在某个维度参数后附加一个"-"，则根据这个参数进行降序排列。

*'''Format'''
格式（可选的）。

 '''REST:''' owa_format=json 

用来具体设置返回结果集的显示格式，OWA中支持的格式有：

{| border="1" cellpadding="10" cellspacing="0"
! Format
! Notes
|-
| <code>json</code>
| 作为一个JSON对象的完整结果集，包括总的结果以及分项结果。
|-
| <code>XML</code>
| 以XML格式显示的完整结果集，包裹总结果以及分项结果。
|-
| <code>PHP</code>
| 作为一个序列化的 <code>paginatedResultSet</code> 对象返回的完整结果集，包括总结过以及分项结果。
|-
| <code>HTML</code>
| 分项结果都是以一个HTML表格显示。
|-
| <code>debug</code>
| 格式化PHP的VAR转储的结果集
|-
|}

*'''Segment (v1.5 or later) '''
段（可选的）。

 '''REST: '''owa_segment=id::1 

在返回结果前你申请的结果集段和指标都会被计算。段可以通过“id”来指代，或者使用动态关键字来动态汇编。

使用“id”的话，格式是''' id:: id的值''',这个id的值是在管构造器GUI中汇编和保存得到的。

动态段，应该带有前缀'''dynamic:: ''',当然可以包含一系列的对维度参数的约束条件。这些约束条件与普通的约束条件的格式都是一样的。动态段只能在维度参数中添加约束条件，不允许在指标上添加。


==结果集的属性值==
*'''Aggregates ：''' 
包含总指标的部分。
*'''Result Rows ：''' 
是显示通过添加维度参数返回的分项指标数据（一行对应一个分项指标），如果在请求中并没有添加维度参数，那么这部分什么都不显示，为空。 
*'''timePeriod ：''' 
这部分显示的是请求中设置的时间段的信息。 
*'''resultsPerPage：''' 
这一属性代表信息是每一页显示的返回结果数目。
*'''resultsTotal'''  
*''' resultsReturned''' 
*'''Labels ：''' 
这一部分包含的信息是请求的指标以及维度参数的标签信息 
*'''Errors '''
==paginatedResultSet对象==
如果你想通过PHP接口来发出结果集请求的话，你可能需要操作

[http://trac.openwebanalytics.com/browser/trunk/modules/base/classes/paginatedResultSet.php paginatedResultSet]对象。

==参考来源==
[http://wiki.openwebanalytics.com/index.php?title=Data_Access_API#Format 参考来源]


{{Open Web Analytics}}

[[category:Open Web Analytics]]