datacite/sashimi

DataCite Usage Reports API

Sashimi是一个仅提供API的应用程序，用于处理SUSHI格式的使用报告。它接收SUSHI格式的报告进行存储，并返回SUSHI报告集合供使用。该应用严格遵循RESEARCH_DATA_SUSHI规范。

服务文档

DataCite提供使用报告API服务。有关API参考和使用指南的描述，请访问：

• API参考
• 使用报告API指南

本文档其余部分涉及本仓库中软件的技术描述和使用方法。

安装

使用Docker安装：

docker run -p 8075:80 datacite/sashimi

现在可以将浏览器指向http://localhost:8075来使用该应用。

开发

我们使用Rspec进行单元测试和验收测试：

bundle exec rspec

技术描述

资源组件

数据使用API支持的主要资源组件包括：

• reports（报告）
• hearthbeat（心跳）

这些资源可单独使用，如下表所示：

资源组件与标识符

资源组件可与标识符结合使用，以检索特定报告的元数据：

提交报告

要添加报告，需要发送JSON内容，POST请求应在头中包含Content-Type: application/json和Accept: application/json。此外，还需要包含用于认证的JSON Web Token（JWT）。例如：

shell
curl --header "Content-Type: application/json; Accept: application/json" -H "X-Authorization: Bearer {YOUR_JWT}" -X POST https://api.datacite.org/reports

JSON示例：

json
{
  "report-header": {
    "report-name": "dataset report",
    "report-id": "dsr",
    "release": "rd1",
    "created": "2016-09-08t22:47:31z",
    "created-by": "dataone",
		"reporting-period": 
    {
        "begin-date": "2018-05-01",
        "end-date": "2018-05-30"
    },
    "report-filters": [
      {
        "name": "begin-date",
        "value": "2015-01"
      }
    ],
    "report-attributes": [
      {
        "name": "exclude-monthly-details",
        "value": "true"
      }
    ],
    "exceptions": [
      {
        "code": 3040,
        "severity": "warning",
        "message": "partial data returned.",
        "help-url": "string",
        "data": "usage data has not been processed for all requested months."
      }
    ]
  },
  "report-datasets": [
    {
      "dataset-title": "lake erie fish community data",
      "dataset-id": [
        {
          "type": "doi",
          "value": "0931-865"
        }
      ],
      "dataset-contributors": [
        {
          "type": "name",
          "value": "john smith"
        }
      ],
      "dataset-dates": [
        {
          "type": "pub-date",
          "value": "2002-01-15"
        }
      ],
      "dataset-attributes": [
        {
          "type": "dataset-version",
          "value": "vor"
        }
      ],
      "platform": "dataone",
      "publisher": "dataone",
      "publisher-id": [
        {
          "type": "orcid",
          "value": "1234-1234-1234-1234"
        }
      ],
      "data-type": "dataset",
      "yop": "2010",
      "access-method": "regular",
      "performance": [
        {
          "period": {
            "begin-date": "2015-01-01",
            "end-date": "2015-01-31"
          },
          "instance": [
            {
              "metric-type": "total-dataset-requests",
              "count": 21
            }
          ]
        }
      ]
    }
  ]
}

此外，可以使用PUT请求提交新报告并提供自己的'report_id'。只要报告符合Sushi模式且'report_id'是UUID，就会创建报告。

键和值

格式规范中定义了参数URL安全命名的允许和推荐字符。为了标准化参数名称，建议遵循以下（更严格的）规则：

• 参数名称应以“a-z”（U+0061至U+007A）字符开头和结尾
• 参数名称应仅包含“a-z”（U+0061至U+007A）、“0-9”（U+0030至U+0039）以及连字符（U+002D连字符，“-”）作为多个单词之间的分隔符。

报告存储

报告使用ActiveStore存储在S3桶中。我们选择存储在S3而非MYSQL中，因为如COUNTER文档所述，报告可能会变得相当大。

注册大型使用报告

使用报告可能会非常大，我们有两种方法处理大型报告的提交：压缩和分块。大型报告需要分割和压缩。我们设置了每个报告最多50,000个数据集的限制。

在这两种情况下，都需要在报告头中添加以下异常：

json
"exceptions": [{
  "code": 69,
  "severity": "warning",
  "message": "Report is compressed using gzip",
  "help-url": "https://github.com/datacite/sashimi",
  "data": "usage data needs to be uncompressed"
}]

发送压缩报告

建议压缩任何大于10MB的报告。以下是报告压缩的Ruby示例：

ruby
def compress file
  report = File.read(file)
  gzip = Zlib::GzipWriter.new(StringIO.new)
  string = JSON.parse(report).to_json
  gzip << string
  body = gzip.close.string
  body
end

发送压缩报告时，需要使用application/gzip作为Content-Type，并使用gzip作为Content-Encoding。例如：

ruby
URI = 'https://api.datacite.org/reports'

def post_file file
  
  headers = {
    content_type: "application/gzip",
    content_encoding: 'gzip',
    accept: 'gzip'
  }
  
  body = compress(file)

  request = Maremma.post(URI, data: body,
    bearer: ENV['TOKEN'],
    headers: headers,
    timeout: 100)
end

等效的Curl命令：

shell
$ curl --header "Content-Type: application/gzip; Content-Encoding: gzip" -H "X-Authorization: Bearer {YOUR-JSON-WEB-TOKEN}" -X POST https://api.datacite.org/reports/ -d @usage-report-compressed

分块发送使用报告

要创建包含超过50,000条记录的报告，只需使用相同的报告头进行多次POST请求。这将创建报告的分块。例如：

shell
POST /reports
POST /reports
POST /reports

要更新现有的压缩报告，先进行PUT请求，然后使用相同的报告头进行所需次数的POST请求。例如：

shell
PUT /reports/{report-id}
POST /reports
POST /reports

元数据验证

报告中元数据的验证分为两步。控制器负责检查字段是否存在。而模式验证在ActiveRecord保存之前执行。我们使用json-schema验证来实现这一点。

查询

支持非常基本的查询，且仅针对报告头中的字段。对于更复杂的查询，建议使用DataCite事件数据服务。在实际实例中，中心API会将每个新创建的报告推送到AWS SQS队列，由事件数据代理处理。

分页

分页遵循JSOANPI规范。

通过https://github.com/datacite/sashimi/issues%E5%85%B3%E6%B3%A8%E9%A1%B9%E7%9B%AE%E5%8A%A8%E6%80%81%E3%80%82

关于补丁/拉取请求的说明

• Fork项目
• 为新功能编写测试或复现错误的测试
• 实现功能或修复错误
• 不要修改Rakefile、版本或历史记录
• 提交、推送并创建拉取请求。使用主题分支可获得额外加分。

许可证

Sashimi 根据https://github.com/datacite/sashimi/blob/master/LICENSE%E5%8F%91%E5%B8%83%E3%80%82