API 使用

透過 CKAN 平台提供的預設 API 服務，使用者可以查詢/下載/管理資料。本資料市集使用 CKAN 平台提供 RESTful API 服務，方便使用者與開發者直接使用。常用的工具除了瀏覽器以外，也可以透過 Linux 指令 cURL，或是 ckanpi 指令/Python library 進行運用。相關工具說明如下：

cURL 是一個利用URL語法在命令列下工作的檔案傳輸工具，支援的通訊協定有 HTTP、HTTPS...等。

ckanapi 是一個專為 ckan 平台開發的應用程式、Python Library。除了可以直接使用指令也可用以快速進行 ckan api 程式開發之用。

資料存取步驟

資料存取主要有3個步驟：查詢資料集 -> 取得資料集詮釋資料 -> 取得資源列表資料(url)，即可下載檔案。

第一步: 查詢資料集列表

以 package_list 列出資料集清單, 也可以利用[tag], [group], [search] 等方式取得資料集清單與資料集ID

範例：

curl https://scidm.nchc.org.tw/api/action/package_list

{
"help": "https://scidm.nchc.org.tw/api/3/action/help_show?name=package_list",
"success": true,
"result": ["00000", ..... "mnist" ]
}

第二步: 顯示資料集內容

以 package_show 列出資料集詮釋資料

範例：

curl -X POST https://scidm.nchc.org.tw/api/3/action/package_show -d '{"id":"mnist"}' 

{
  "help": "https://scidm.nchc.org.tw/api/3/action/help_show?name=package_show",
  "success": true,
  "result": {
    "license_title": "cc-by",
    "relationships_as_object": [],
    "private": false,
    "num_tags": 1,
    "id": "ef890176-6fd9-499d-9687-5fe2863c6941",
    "metadata_created": "2018-03-07T08:41:56.898623",
    "metadata_modified": "2018-03-20T16:37:36.011714",
    "creator_user_id": "4360a7c1-74c3-467d-aeee-4a311390e03f",
    "type": "dataset",
    "resources": [
      {
        "description": "training set labels",
        "name": "train-labels-idx1-ubyte.gz",
        "url": "https://scidm.nchc.org.tw/dataset/ef890176-6fd9-499d-9687-5fe2863c6941/resource/c24b3977-b37e-40a9-88fc-993a65308830/download/train-labels-idx1-ubyte.gz",
        "datastore_active": false,
        "package_id": "ef890176-6fd9-499d-9687-5fe2863c6941",
        "created": "2018-03-07T08:41:56.913326",
        "state": "active",
        "last_modified": "2018-03-07T08:44:32.097055",
        "revision_id": "1fe43571-ffd8-4ef2-b28d-2d8a01dd5bd2",
        "url_type": "upload",
        "id": "c24b3977-b37e-40a9-88fc-993a65308830",
        "resource_type": null,
        "size": 28881
      },...],
    "num_resources": 4,
    "license_id": "cc-by",
    "name": "mnist",
    "isopen": false,
    "url": "",
    "notes": "mnist 手寫辨識資料",
    "owner_org": "1517dc0d-5312-4f7c-b602-1fdeecad09e4",
    "title": "MNIST",
    "revision_id": "38f46d2d-5c57-44af-93b0-5de4b3e40ddd"
  }
}

由以上範例可以取得 resourceid (資源ID) 與 url, 如果需要資源的詳細資料可以透過 [resource_show] 取得

第三步: 取得資源詳細資訊並下載資料

由上述資料集詮釋資料 或是由 特定 resource_show API 可以列出資源中的 url 資訊，即是檔案下載位置。

範例：

curl -X POST  https://scidm.nchc.org.tw/api/3/action/resource_show -d '{"id":"c24b3977-b37e-40a9-88fc-993a65308830"}'

{
  "help": "https://scidm.nchc.org.tw/api/3/action/help_show?name=resource_show",
  "success": true,
  "result": {
    "mimetype": null,
    "cache_url": null,
    "hash": "",
    "description": "training set labels",
    "name": "train-labels-idx1-ubyte.gz",
    "format": "",
    "url": "https://scidm.nchc.org.tw/dataset/ef890176-6fd9-499d-9687-5fe2863c6941/resource/c24b3977-b37e-40a9-88fc-993a65308830/download/train-labels-idx1-ubyte.gz",
    "datastore_active": false,
    "cache_last_updated": null,
    "package_id": "ef890176-6fd9-499d-9687-5fe2863c6941",
    "created": "2018-03-07T08:41:56.913326",
    "state": "active",
    "mimetype_inner": null,
    "last_modified": "2018-03-07T08:44:32.097055",
    "position": 0,
    "revision_id": "1fe43571-ffd8-4ef2-b28d-2d8a01dd5bd2",
    "url_type": "upload",
    "id": "c24b3977-b37e-40a9-88fc-993a65308830",
    "resource_type": null,
    "size": 28881
  }
}

以上的 url 描述：

"url": "https://scidm.nchc.org.tw/dataset/ef890176-6fd9-499d-9687-5fe2863c6941/resource/c24b3977-b37e-40a9-88fc-993a65308830/download/train-labels-idx1-ubyte.gz",

就是資源的實際位置。

再以 wget 或是 瀏覽器 下載檔案

wget https://scidm.nchc.org.tw/dataset/ef890176-6fd9-499d-9687-5fe2863c6941/resource/c24b3977-b37e-40a9-88fc-993a65308830/download/train-labels-idx1-ubyte.gz

資料上架步驟

資料上架前需先確認兩項資訊：個人API_金鑰與欲上架之資料集ID或其名稱

**API\金鑰:**_

資料集ID或其名稱，如： private01

確認後可使用下列方式進行資料上架：

範例

curl 上架範例：

$ curl -H 'Authorization: API_金鑰' 'https://scidm.nchc.org.tw/api/action/resource_create' --form [email protected] --form package_i
d=private01 --form name=my-test02 | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 10664  100   798  100  9866    165   2048  0:00:04  0:00:04 --:--:--     0
{
  "help": "https://scidm.nchc.org.tw/api/3/action/help_show?name=resource_create",
  "success": true,
  "result": {
    "cache_last_updated": null,
    "cache_url": null,
    "mimetype_inner": null,
    "hash": "",
    "description": "",
    "format": "text/x-python",
    "url": "https://scidm.nchc.org.tw/dataset/27141111-8bb4-4967-983e-5a243c2be17f/resource/54f49971-e61f-4056-ae58-f0aba4cd8143/download/plugin.py",
    "created": "2018-10-19T06:46:02.928884",
    "state": "active",
    "package_id": "27141111-8bb4-4967-983e-5a243c2be17f",
    "last_modified": "2018-10-19T06:46:02.689961",
    "mimetype": "text/x-python",
    "url_type": "upload",
    "position": 3,
    "revision_id": "366a6e66-a84e-43f5-b57a-047577511528",
    "size": 9453,
    "datastore_active": false,
    "id": "54f49971-e61f-4056-ae58-f0aba4cd8143",
    "resource_type": null,
    "name": "my-test02"
  }
}

python with ckanapi 範例如下：

from ckanapi import RemoteCKAN
ua = 'ckanapiexample/1.0 (+http://example.com/my/website)'

mysite = RemoteCKAN('http://scidm.example.com', apikey='API_金鑰', user_agent=ua)
mysite.action.resource_create(
    package_id='資料集ID/名稱',
    name='顯示名稱',
    upload=open('上架檔案完整路', 'rb'))

更多 ckan API 定義

可以參考官方 CKAN API 手冊