README

开放数据模式映射

本模块提供了一种灵活的方式来通过遵循特定开放数据模式（ODS）的API公开您的Drupal内容。目前，提供了CKAN、项目开放数据和DCAT-AP模式，但可以通过您自己的模块轻松添加新模式。用户界面可用于创建端点，并使用标记将所选模式中的字段映射到Drupal内容。

本模块是DKAN项目的一部分，但可以在Drupal 7站点上运行。存在一个单独的模块，用于DKAN特定的实现。

请注意，如果您不遵循ODSM文件缓存部分中的建议，可能会导致严重性能问题。

基本概念

模式

模式是一系列字段定义的列表，通常代表一个社区规范，用于展示可读性强的数据。Open Data Schema Map模块的核心不包含任何模式；它们由附加模块提供。一个模式模块包括

一个标准的Drupal .module文件，实现了hook_open_data_schema()以将模式暴露给核心Open Data Schema Map模块，以及任何需要修改UI表单或数据输出的_alter函数。
模式本身，以.json文件的形式表达。例如，查看项目开放数据模式文件，了解这些模式如何在JSON中定义。

API

本模块中的API是一个配置集，在特定URL（称为API的端点）上公开一组特定可读数据。本模块允许您创建多个API，并将它们保存为数据库记录，或通过Features导出。一个API记录将包含

端点URL
模式（从上述附加模块提供的可用模式中选择）
将模式中定义的字段映射到Drupal标记（通常引用节点中的字段）
可选地，通过URL传递一个或多个参数以过滤结果集

用法

安装

像往常一样启用主要模块Open Data Schema Map，并额外启用您将用于创建API的任何模式模块。

创建API

导航到admin/config/services/odsm，然后点击“添加API”。

为API提供一个标题、机器名称，选择实体类型（通常是node）和捆绑包（在DKAN中，这通常是Dataset）。

在添加参数和映射之前，您需要创建API记录。

参数

API调用结果可以通过URL中的参数按特定字段进行筛选。要添加一个参数，首先选择模式字段，然后，如果您正在通过自定义字段API字段（即机器名以"field_"开头的字段）进行筛选，则识别将包含实际参数值的数据库列。省略字段名称前缀；例如，如果您正在通过DKAN标签（术语引用字段）进行筛选，则正确列是field_tags_tid，因此您会输入"tid"。要使用的Drupal字段将通过映射到该模式字段的令牌来推断。

字段映射

API表单为您提供了每个模式字段的一个字段。使用Drupal的令牌系统进行字段映射。注意：在单个字段中使用多个令牌可能会产生意外结果，因此不建议这样做。

多值字段

对于Drupal多值实体引用字段，模式可以使用数组来指示API迭代每个值并将引用数据映射到多个模式字段。例如，在CKAN模式中，标签在schema_ckan.json中描述如下：

      "tags": {
      "title":"Tags",
      "description":"",
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "title": "UUID",
                "type": "string"
              },
              "vocabulary_id": {
                "title": "Vocaulary ID",
                "type": "string"
              },
              "name": {
                "title": "Name",
                "type": "string"
              },
              "revision_timestamp": {
                "title": "Revision Timestamp",
                "type": "string"
              },
              "state": {
                "title": "state",
                "description": "",
                "type": "string",
                "enum": ["uncomplete", "complete", "active"]
              }
            }
          }
        }
      ]
    },

您可以选择将所选包上的哪些多值字段映射到"tags"数组，以公开所有引用的"tag"实体（本例中的术语分类），以便在数组内的模式字段上进行令牌映射。首先，只需选择多值字段，留空单个字段映射，并保存表单。

保存表单后返回表单的标签部分，您现在将看到一个特殊的令牌导航器，您可以使用它来查找与此迭代方法（使用"第N个"代替标准delta值）兼容的令牌。

数据联邦筛选

要排除API中的特定组，请导航到/admin/config/services/odsm/settings并选择您希望包含的组。

然后，您必须编辑您的API并勾选应用数据联邦筛选器复选框，以便筛选器应用于您的端点。

定制

添加新模式

您不受此模块包含的模式限制；任何开放数据模式都可以在自定义模块中定义。使用open_data_schema_ckan模块作为起点。

日期格式

日期格式可以通过更改"Medium"日期时间格式在"admin/config/regional/date-time"中手动更改，或在代码中使用其中一个alter钩子更改。

关于XML输出的说明

开放数据模式映射提供XML输出格式。这是出于历史原因在modules/文件夹中的单独子模块中提供的，但应该在未来的版本中重构到主要的ODSM模块中。

XML端点仍然需要一个在JSON中定义的模式。定义自己的XML端点可能不那么直观，但请查看DCAT模式模块作为模型。

ODSM文件缓存

列出大量实体的开放数据模式映射端点（项目开放数据（code>data.json），CKAN包列表（/api/3/action/package_list）和DCAT-AP目录（code>catalog.xml））为每个记录执行完整实体加载，以便执行令牌替换。这可能会在每次访问这些URL时对拥有超过几十个数据集的网站造成重大性能影响，在拥有数千个数据集的网站上，响应时间可能为两分钟或更长时间。

开放数据模式映射包含一个文件缓存功能，可以将任何端点的快照保存为静态文件，以快速提供，对数据库的访问非常少。

文件缓存可以通过Drush命令或管理界面生成。在生产网站上，建议使用cron作业或Jenkins等任务运行程序每天（使用Drush命令）在网站流量最少时重新生成性能密集型端点的文件缓存。当然，这种权衡是，您网站上的任何新增或更改都不会反映在这些端点上，直到它们被重新生成。

Drush使用

由Open Data Schema Map提供的Drush命令是odsm-filecache（也可以简单地作为别名odsmfc）。该命令的参数是ODSM端点的机器名。例如

drush odsm-filecache data_json_1_1

这将渲染完整的data_json_1_1端点（这是DKAN附带的数据.json实现），并将其保存到文件系统中

public://odsm_cache_data_json_1_1

现在对/data.json的访问将路由到这个文件，在大多数情况下，这个文件实际上位于/sites/default/files/odsm_cache_data_json_1_1。

界面使用

还包括一个管理界面，可以手动重新生成文件缓存。此界面在手动创建缓存文件足够的情况下很有用。

要使用，请导航到admin/config/services/odsm，在那里有一个名为“缓存”的列，包含指向特定端点缓存的单独管理页面的链接。如果没有缓存，则链接标记为“无”，否则链接标记为缓存的年龄（小时）。从缓存管理页面，您可以创建、删除或重新生成缓存。

模式验证

Project Open Data和DCAT-AP模式都附带验证工具，您可以从Drupal管理菜单访问这些工具。有关此功能的更多文档即将推出...

社区

我们只接受在DKAN问题队列中的Open Data Schema Map问题。请在提交问题后将其标记为"组件：ODSM"，以便我们更快地识别问题和功能请求。

如果您向此项目提交拉取请求，请尝试将您的PR与DKAN问题线程中的对应问题联系起来。

getdkan / open_data_schema_map

维护者

详细信息