2015/4/22 於「開放資料技術研習營-CKAN 研習營」

1. CKAN 技術介紹 ( 開發篇 )
李承錱 (Sol)
中央研究院資訊科學研究所
本著作採用創用 CC 「姓名標示 - 相同方式分享」授權條款台灣 3.0 版

2. 2
大綱
● 客製化 CKAN 功能
● 常見客製化議題探討

3. 3
客製化 CKAN 功能
修改網頁介面選項
撰寫擴充套件
修改環境設定檔
較困難
較容易

4. 4
客製化 CKAN 功能
● 修改網頁介面選項
– 位置： SITE_URL/ckan-admin/config
– 需有系統管理員權限
– 設定網站配色、 LOGO 、簡介、 header CSS 、首頁佈局等
● 修改環境設定檔 (production.ini)
– 參見基礎篇：管理與維護
● 撰寫擴充套件
– 建議將客製部分置於擴充套件，避免修改核心造成不相容情形

5. 5
常見客製化議題探討
● 自訂詮釋資料 (Metadata)
● 自訂資料授權選項
● 資料驗證與格式轉換
● 資料視覺化
● 自訂資料集過濾器
● 資料採集 (Harvesting)
● 多語系支援

6. 6
自訂詮釋資料
● 擴充套件 ckanext-scheming1
– 使用 JSON 資料交換語言自訂詮釋資料欄位
– 提供多種常用顯示樣板 (Template)
樣板名稱 欄位型態
text.html 自由文字
large_text.html 較大文字 ( 用於標題等 )
date.html 日期 ( 西元年 / 月 / 日 )
markdown.html 文字方塊 ( 支援 Markdown)
select.html 下拉式選單
multiple_choice.html 多選鈕 ( 核取方塊 )
repeating.html2
多重值 ( 自由文字 )
1. https://github.com/open-data/ckanext-scheming，相容於 CKAN 2.3 以上版本
2. 由擴充套件 ckanext-repeating 提供

7. 7
自訂詮釋資料：範例
{
"field_name": "data_type",
"label": {"en": "Data Type", "zh_TW": " 資料類型 "},
"preset": "select",
"form_attrs": {"data-module": "autocomplete"},
"choices": [
{"value": "statistics", "label":{"en": "Statistics", "zh_TW": " 統計資料 "}},
...
]
}
{"preset_name": "select",
"values": {
"form_snippet": "select.html",
"display_snippet": "select.html",
"validators": "scheming_required scheming_choices"}}
結果
Source: http://goo.gl/QF9lJA

8. 8
自訂資料授權選項
● 使用 JSON 自訂資料授權選項
● 使用環境設定檔變數 licenses_group_url 指定 JSON 定義檔
所在網址
– 例： licenses_group_url =
http://licenses.opendefinition.org/licenses/groups/od.json
– 注意：使用 licenses_group_url 指定的定義檔案，會直
接覆寫內建授權清單

9. 9
自訂資料授權選項：範例
{
"status": "active",
"maintainer": "",
"family": "",
"title": " 政府資料開放平臺資料使用規範 ",
"domain_data": false,
"is_okd_compliant": false,
"is_generic": true,
"url": "http://data.gov.tw/principle",
"is_osi_compliant": false,
"domain_content": false,
"domain_software": false,
"id": "twogd"
}
資料集顯示
資料集新增 / 編輯
Source: http://goo.gl/IMmQHk

10. 10
資料驗證與轉換
● 資料驗證：確保資料品質
● 資料轉換：將格式一致化
● 適用於網頁表單及 API 上傳
● 核心內建部分驗證器 (Validators) 與
轉換器 (Converters)1,2
1. 參見
http://docs.ckan.org/en/ckan-2.3/extensions/validators.html
2. CKAN 中無論驗證器或轉換器均被命名為 validator

11. 11
資料驗證與轉換
● 驗證器 (Validator)
– 檢驗使用者輸入
– 部分內建驗證器
● natural_number_validtor( 自然數 )
● is_positive_integer( 正整數 )
● isodate(ISO8601 格式時間 )
● not_empty( 必填欄位 )
● ignore_missing( 允許空值 )

12. 12
資料驗證與轉換
● 驗證器 (Validator)
– 自訂例：驗證輸入是否為 JSON 格式
def json_validator(value, context):
(...)
try:
json.loads(value)
except ValueError:
raise Invalid('Invalid JSON')
return value

13. 13
資料驗證與轉換
● 轉換器 (Converter)
– 轉換資料格式以一致化
– 部分內建轉換器
● int_validator( 轉換文數字為整數 )
●
boolean_validator
( 轉換文字為布林值 )
●
remove_whitespace
( 去除前後空白 )

14. 14
資料驗證與轉換
● 轉換器 (Converter)
– 自訂例：去除多重值欄位之重複內容
– ['a', 'b', 'c', 'a'] ['a', 'b', 'c']→
def duplicate_validator(key, data, errors,
context):
(…)
value = json.loads(data[key])
unduplicated = list(set(value))
(...)

15. 15
資料視覺化
● 實作 CKAN 未提供之資料預覽 / 視覺化 (Viewers)1
● 例：擴充地理資料之預覽 3
– WMTS 圖磚服務
● 提供電子地圖圖資服務
● 如：國土測繪中心提供之通用版電子地圖 WMTS
– ESRI Shapefile (shp 、 dbf 與 prj 置於一 zip 壓縮檔中 )
● GIS 領域流行之空間資料格式
1. CKAN 提供試算表 (csv 、 xls) 、文字 (txt, xml) 、圖片 (png 、 jpg 、 gif) 、網頁
(html) 、 pdf 、 geojson2
、 wms2
等預覽
2. 由擴充套件 ckanext-spatial 提供
3. 由第 1 及第 2 點可知， ckanext-spatial 僅提供 geojson 與 wms 兩種空間格式預覽

16. 16
資料視覺化範例： Shapefile 預覽
CKAN Shapefile 預覽 使用 QGIS 桌面軟體檢
視
http://taijiang.tw/dataset/proj4-29

17. 17
撰寫 CKAN 擴充套件
● PyUtilib Component Architecture (PCA) 擴充架構
1. 繼承 ckan.plugins.SingletonPlugin
2. 視需求實作一或多個 ckan.plugins.* 抽象介面 (Interface)
● 如 IResourceView1
：針對指定資料格式實作資料預覽
3. 若該外掛涉及前端 (Front-end) 介面，則需額外撰寫
HTML 檔與 JavaScript
● 如： Shapefile 預覽需與 leaflet2
、 shp2geojson.js3
等
合併使用
1. http://docs.ckan.org/en/ckan-2.3/extensions/plugin-
interfaces.html#ckan.plugins.interfaces.IResourceView
2. http://leafletjs.com/ ( 圖台套件，以 BSD 授權釋出 )
3. http://gipong.github.io/shp2geojson.js/ (Shapefile-GeoJSON 轉換套件，以 MIT 授權釋出 )

18. 18
資料視覺化範例： Shapefile 預覽
from ckan import plugins as p
class SHPView(p.SingletonPlugin):
p.implements(p.IResourceView,
inherit=True)
SHP = ['shp zip']
def info(self):
return {'name': 'shp_view',
'title': 'shp',
'icon': 'map-marker',
'iframed': True,
'default_title': 'SHP',
}
def can_view(self, data_dict):
resource = data_dict['resource']
format_lower = resource['format'].lower()
if format_lower in self.SHP:
return self.same_domain or
self.proxy_is_enabled
return False
def view_template(self, context, data_dict):
return 'dataviewer/shp.html'
<div data-module="shppreview" id="data-
preview" … ></div>
// shapefile preview module
ckan.module('shppreview', function (jQuery, _)
{
Return {
initialize: function () {
(...)
}
showPreview: function (url, data) {
(…)
}
}
}
Python Plugin View Template
(shp.html)
JS Module (shp_view.js)
2.
指
定
實
作
抽
象
介
面
1. 進入點 : 繼承 SingletonPlugin
2. 實作抽象介面之方法
3. 前端網頁顯示
Source:
http://goo.gl/JIY8Il
http://goo.gl/jorVvx
http://goo.gl/BgNVlX

19. 19
自訂資料集過濾器
● 屬性過濾器 (Filters)
– 以指定條件過濾資料集
● 自訂過濾器
1. 實作 IPackageController 與 Ifacets 抽象介面
2. 新增 Solr 搜尋索引定義

20. 20
過濾器範例 1 ：關鍵字搜尋
from ckan import plugins as p
class TaijiangDatasets(p.SingletonPlugin):
p.implements(p.IPackageController, inherit=True)
p.implements(p.IFacets)
def before_index(self, data_dict):
data_dict.update({'theme_keyword_facets': []})
if data_dict.get('theme_keyword'):
data_dict['theme_keyword_facets'] =
json.loads(data_dict.get('theme_keyword'))
return data_dict
def dataset_facets(self, facets_dict, package_type):
facets_dict['theme_keyword_facets'] =
p.toolkit._('Theme Keyword')
return facets_dict
<field name=
"theme_keyword_facets"
type="string"
indexed="true"
stored="true"
multiValued="true"/>
Python Plugin Solr Schema
註：省略前端顯示部分程式碼
結果
指定為 string
型別索引
將詮釋資料定義之主題關
鍵字 ( 選項 ) 置入過濾器
新增主題關鍵字
過濾器
Source:
http://goo.gl/YxWx1U
http://goo.gl/BWuU6I

21. 21
過濾器範例 2 ：時間搜尋
from ckan import plugins as p
class TaijiangDatasets(p.SingletonPlugin):
p.implements(p.IPackageController, inherit=True)
p.implements(p.IFacets)
def before_search(self, search_params):
(…)
begin = parse_date(search_params['extras']
['ext_begin_date'])
end = parse_date(search_params['extras']['ext_end_date'])
(…)
query = ("(start_time: [* TO {0}Z] AND end_time: [{0}Z TO
*]) OR (start_time: [{0}Z TO {1}Z] AND end_time: [{0}Z TO *])")
query = query.format(begin.isoformat(), end.isoformat())
search_params['q'] = query
return search_params
def dataset_facets(self, facets_dict, package_type):
facets_dict['date_facet'] = p.toolkit._('Date of Dataset')
return facets_dict
<dynamicField
name="*_time"
type="date"
indexed="true"
stored="true"
multiValued="false"/>
Python Plugin Solr Schema
註：省略前端顯示部分程式碼
結果
指定以 time
結尾之欄位指定為 date
型別索引
start_time
end_time
Solr 搜尋定義
Source:
http://goo.gl/C98Pr2
http://goo.gl/9TA014

22. 22
資料採集 (Harvesting)
● 以自動化方式，探索 (discovery) 網路資源，並收集其資料
及詮釋資料，達成資料交換之目的
● 擴充套件 ckanext-harvest
– 支援自動、定時採集指定資料來源
– 僅採集詮釋資料 ( 亦即實體檔案仍位於資料來源 )
● 支援採集之資料來源
– CKAN( 內建 )
– CSW (Catalog Service for the Web)*
– WAF (Web Accessible Folder)*
– 自訂來源 (csv 、 xls 、網站等 )
* 由擴充套件 ckanext-spatial 提供

23. 23
資料採集：自訂採集來源 -SRDA*
from ckan import plugins as p
class SRDAHarvester(SingletonPlugin):
p.implements(IHarvester)
def info(self):
(...)
def gather_stage(self, harvest_job):
(…)
def fetch_stage(self, harvest_object):
(…)
def import_stage(self, harvest_object):
(…)
*SRDA=Survey Research Data Archive
( 中研院人社中心調研中心學術調查研究資料庫 )
結果
Python Plugin
取得 ( 詮釋 ) 資料清單
實際取得 ( 詮釋 ) 資料
匯入為 CKAN 資料集
Source: http://goo.gl/LS79s4

24. 24
資料採集：操作方式
●
paster --plugin=ckanext-harvest harvester command -c
/etc/ckan/default/production.ini
– gather_consumer ：取得 ( 詮釋 ) 資料清單
– fetch_consumer ：實際取得資料
– run ：匯入為 CKAN 資料集
●
可使用 Supervisor 與 cron job 排程執行採集工作
– 參見： https://github.com/ckan/ckanext-harvest#setting-up-
the-harvesters-on-a-production-server
需維持執行狀態

25. 25
多語系支援
● 介面翻譯
– GNU gettext
– 語法： _(' 待翻譯文字 ')
●
Python: p.toolkit._('String')
●
Jinja Template (HTML): {{ _('String') }}
●
JavaScript: _('String')_
– 主程式線上翻譯專案
●
Transifex.com Open Knowledge / CKAN→

26. 26
多語系支援
● 擴充套件翻譯
– opendatatrentino/ckan-custom-translations (GitHub)
– 將擴充套件與主程式之翻譯檔 (.po) 合併
– 需在環境設定檔指定新翻譯檔目錄 (ckan.i18n_directory
變數 )
● 詮釋資料翻譯
– 已設計於 JSON 詮釋資料定義中 *
– 例： "label": {"en": "Data Type", "zh_TW": " 資料類型 "}
* 使用 ckanext-scheming 自訂詮釋資料時

27. 27
多語系支援
● 中文關鍵字搜尋
– Solr + mmseg4j1
(Java 斷詞器 )
– Maximum Matching Algorithm2
– 複製 mmseg4j 至 Solr 目錄，並修改 Solr 索引定義檔
– 參考： http://is.gd/2Vpzgb
1. https://github.com/chenlb/mmseg4j-solr ( 以 Apache 2.0 授權釋出 )
2. http://technology.chtsai.org/mmseg/

28. 28
開發篇重點摘要
● 客製化 CKAN 功能之方法
– 網頁介面選項、修改系統設定檔、撰寫擴充套件
– 盡可能將客製部分置於擴充套件
● 常見客製化議題與實作
– JSON 自定義欄位
– PCA 擴充架構
– Gettext 介面翻譯語法
– Solr 中文搜尋

29. 29
感謝聆聽 敬請指教
Email: cjlee AT iis.sinica.edu.tw