API 列表

以下列出常見的CKAN API使用方式,詳細列表請見CKAN API Reference

取得資料集列表

  • 請求類型: GET

  • 用途: 取得資料集名稱列表

  • 參數:

    • limit (int) : (選用) 取得最多limit筆資料集。

    • offset (int) : (選用) 從第offset + 1 筆資料集開始,取出資料集。

  • 回傳型態: 資料集名稱列表

取得資料集及其資料列表

  • 請求類型: GET

  • 用途: 取得資料集及其相關資料列表,以最近修改的資料集開始列表排序。

  • 參數:

    • limit (int) : (選用) 設定一個頁面中,取得最多limit筆資料集。

    • offset (int) : (選用) 從第offset + 1 筆資料集開始,取出資料集。

    • page (int) : (選用) 設定從第page頁開始取得列表。

  • 回傳型態: 資料集名稱及其資料列表

取得指定資料集的版本列表

取得資料群組的成員列表或是資料集列表

  • 請求類型: GET

  • 用途: 列出資料群組的成員列表(ex. 使用者、資料集)。 注意,使用此API的使用者,必須有取得群組資訊的權限(ex. 群組管理員、系統管理員)

  • 參數:

    • id (string) : (必填) 資料群組的識別碼(identifier)或是名稱

    • object_type (string): (選填) 指定回傳的成員型態。可用選項為 user(使用者), package(資料集)

    • capacity (string): (選填) 指定回傳的成員權限。可用選項為member, editor, admin, public, private

  • 回傳型態: 資料群組的成員列表或是資料集列表

取得本站的群組清單

  • 請求類型: GET

  • 用途: 列出本站的群組清單

  • 參數:

    • order_by (string) : (選填) 依照指定欄位進行排序。可用選項為 name, packages (資料集id),預設為使用名稱排序。limit (int) : (選用) 設定一個頁面中,取得最多limit筆群組。

    • offset (int) : (選用) 從第offset + 1 筆群組開始,取出群組。

    • groups (a list of strings) : (選用) 給定一個群組列表,列出屬於此群組列表的群組相關資訊。

    • all_fields (bool): (選用) 是否列出所有欄位資訊?此運算極度耗用資源,請三思使用。(預設:false)

    • include_extras (bool): (選用) 是否包含額外欄位資訊?(預設: false)

    • include_tags (bool): (選用) 是否包含標籤資訊?(預設: false)

    • include_groups (bool): (選用) 是否包含上層群組資訊?(預設: false)

    • include_users (bool): (選用) 是否包含使用者資訊?(預設: false)

  • 回傳型態: 本站的群組清單

取得本站的組織清單

  • 請求類型: GET

  • 用途: 列出本站的組織清單

  • 參數:

    • order_by (string) : (選填) 依照指定欄位進行排序。可用選項為 name, packages (資料集id),預設為使用名稱排序。limit (int) : (選用) 設定一個頁面中,取得最多limit筆群組。

    • offset (int) : (選用) 從第offset + 1 筆群組開始,取出群組。

    • organizations (a list of strings) : (選用) 給定一個群組列表,列出屬於此群組列表的群組相關資訊。

    • all_fields (bool): (選用) 是否列出所有欄位資訊?此運算極度耗用資源,請三思使用。(預設:false)

    • include_extras (bool): (選用) 是否包含額外欄位資訊?(預設: false)

    • include_tags (bool): (選用) 是否包含標籤資訊?(預設: false)

    • include_groups (bool): (選用) 是否包含上層群組資訊?(預設: false)

    • include_users (bool): (選用) 是否包含使用者資訊?(預設: false)

  • 回傳型態: 本站的組織清單

取得授權列表

取得標籤列表

  • 請求類型: GET

  • 用途: 列出本站的標籤清單。

  • 參數:

    • query (string): (必填) 搜尋的標籤名關鍵字

    • vocabulary_id (string): (選用) 指定語彙的名稱或是id, 如果標籤屬於該語彙名稱或是id,則回傳該標籤。

    • all_fields (bool): (選用) 是否回傳全部的標籤資訊?(預設: false)

  • 回傳型態: 本站使用的標籤清單

取得使用者列表

  • 請求類型: GET

  • 用途: 列出本站的使用者清單。

  • 參數:

    • query (string): (選用) 搜尋的使用者名稱關鍵字

    • order_by (string): (選用) 指定排序欄位根據。可用選項為edits(編輯數), name(名稱), number_created_packages(建立的資料集數量)。(預設: name)

  • 回傳型態: 本站的使用者清單

取得資料集詳細資訊

  • 請求類型: GET

  • 用途: 取得資料集詳細資訊。

  • 參數:

    • id (string): (必填) 資料集id或是名稱

    • use_default_schema (bool): (選用) 使用預設的資料表內的資料集schema而不是使用IDatasetForm外掛的自定義schema(預設: false)

    • include_tracking (bool): 加入資料集與資料間的追蹤軌跡紀錄。(預設: false)

  • 回傳型態: (Dictionary) 資料集詳細資訊

取得資料(或稱做資源)詳細資訊

  • 請求類型: GET

  • 用途: 取得指定資料(或稱做資源)的詳細資訊。

  • 參數:

    • id (string): (必填) 資料或資源的ID或是名稱

    • include_tracking (bool): 加入資料集與資料間的追蹤軌跡紀錄。(預設: false)

  • 回傳型態: (Dictionary) 資料的詳細資訊

取得更新紀錄的細目

  • 請求類型: GET

  • 用途: 取得更新紀錄的細目。

  • 參數:

    • id (string): (必填) 更新紀錄的ID或是名稱

  • 回傳型態: (Dictionary) 該筆更新紀錄的詳細資訊

取得資料群組的詳細資訊

  • 請求類型: GET

  • 用途: 取得資料群組的詳細資訊。

  • 參數:

    • id (string): (必填) 資料群組的ID或是名稱

    • include_datasets (bool): (選用) 是否包含資料集列表? (預設: false)

    • include_extras (bool): (選用) 是否包含群組的額外欄位? (預設: true)

    • include_users (bool): (選用) 是否包含使用者列表? (預設: true)

    • include_groups (bool): (選用) 是否包含子群組列表? (預設: true)

    • include_tags (bool): (選用) 是否包含群組標籤? (預設: true)

    • include_followers (bool): (選用) 是否顯示該群組的追蹤人員數量? (預設: true)

  • 回傳型態: (Dictionary) 該資料群組的詳細資訊

  • 備註:只有前1000筆資料集會被回傳。

取得組織的詳細資訊

  • 請求類型: GET

  • 用途: 取得組織的詳細資訊。

  • 參數:

    • id (string): (必填) 組織的ID或是名稱

    • include_datasets (bool): (選用) 是否包含資料集列表? (預設: false)

    • include_extras (bool): (選用) 是否包含組織的額外欄位? (預設: true)

    • include_users (bool): (選用) 是否包含使用者列表? (預設: true)

    • include_groups (bool): (選用) 是否包含子群組列表? (預設: true)

    • include_tags (bool): (選用) 是否包含組織使用的標籤? (預設: true)

    • include_followers (bool): (選用) 是否顯示該組織的追蹤人員數量? (預設: true)

  • 回傳型態: (Dictionary) 該組織的詳細資訊

  • 備註:只有前1000筆資料集會被回傳。

取得群組的資料集列表

  • 請求類型: GET

  • 用途: 取得群組的資料集列表

  • 參數:

  • id (string): (必填) 群組的ID或是名稱

  • limit (int): (選用) 顯示的資料集最多數量

  • 回傳型態: (List of Dictionary) 該群組的資料集列表

取得標籤列表

  • 請求類型: GET

  • 用途: 取得該標籤和所有資料集的詳細資訊。

  • 參數:

    • id (string): (必填) 標籤的ID或是名稱

    • vocabulary_id (string): (選用) 標籤所在的詞彙,(沒有指定的話會假設是一個任意的標籤)

    • include_datasets (bool): (選用) 包含標籤的資料集列表(最高限制為1000。) (預設: False)

  • 回傳: 該標籤的所有資料集與詳細資料的列表

  • 回傳型態: (Dictionary) 標籤列表的詳細資訊

取得使用者資訊

  • 請求類型: GET

  • 用途: 取得使用者帳號資訊。iduser_obj這兩個參數其中一個必須給值

  • 參數:

    • id (string): (選用)使用者ID或是名稱

    • user_obj (user dictionary): (選用)使用者的用戶字典

    • include_datasets (boolean): (選用)包含使用者已經創造的資料集列表,若是系統管理員或是相同使用者的請求,則該資料集會包含草稿資料和私人資料 (預設:False,限制:50)

    • include_num_followers (boolean): (選用)包含使用者所擁有的追隨人數(預設:False)

    • include_password_hash (boolean): (選用)包含存儲密碼(系統管理員專屬可用,預設:False)

  • 回傳型態: (Dictionary) 使用者的詳細資訊。包含email_hash、 number_of_edits、 number_created_packages(發出請求的除非是系統管理員或是相同使用者,否則不包含草稿與私人資料) ,不包含密碼(hash)跟reset_key。如果是系統管理員或是相同使用者的請求的話,則包含電子郵件和apikey資料。

格式自動完成

  • 請求類型: GET

  • 用途: 取得名稱包含字串的資料格式列表

  • 參數:

    • q (string): 要搜索的字串

    • limit (int): (選用,預設:5) 回傳資料格式的最大數量

  • 回傳型態: (List of strings)字串列表

資料集搜尋

  • 請求類型: GET

  • 用途: 搜尋符合條件的資料集。可以使用Solr查詢參數,回傳資料集的詳細資訊(以Dictionary方式呈現),其中包含符合查詢條件的指定資料集、搜尋次數和其他方面的資訊。

  • Solr參數: 若要了解每個參數更深入的處理,請參考 Solar文件。在此接受的參數為Solr查詢參數的子集合。

    • q (string): (選用,預設: "*:*") solr 查詢語句

    • fq (string): 任何篩選的條件。注意: 在執行搜尋之前,+site_id:{ckan_site_id}會被加入到這個查詢字串前面。

    • sort (string): (選用,預設:'relevance asc, metadata_modified desc') 將搜尋結果排序,根據Solr文件,這是以欄位名稱作為逗號分隔的字串和排序。

    • rows (int): 符合的資料筆數。每次查詢的上限為1000個資料集。

    • start (int): 回傳的資料偏移量,用來作為搜尋結果的起始點。

    • facet (string): 是否開啟其它方面的顯示資訊(預設:true)

    • facet.mincount (int): 需要包含其它方面資訊欄位的最小數量

    • facet.limit (int): 回傳其它方面資訊欄位的最大數量。負值代表沒有上限,這可以參考search.facets.limit進行設定(預設:50)

    • facet.field (list of strings): 欲顯示的其它資訊欄位名稱。(預設:空,若為空值則回傳的facet資訊也為空值)

    • include_drafts (bool): (選用,預設:false) 若是ture則會包含草稿資料集,使用者只會取得自己的資料集,系統管理員可以取得所有草稿資料集。

    • include_private: (選用,預設:False) 若是True則會包含私人資料集,使用者只能取得自己所屬組織的私人資料集,系統管理員可以取得所有私人資料集。

    • use_default_schema (bool): 使用預設資料集架構,而非使用IDatasetForm外掛定義的客製化架構(預設:false)

    • qf,wt,bf,boost,tie,defType,mm: 上述參數是進階的Solr參數,他們只在特定的Solr版本可以執行,參考dismaxedismax會有更多資訊。

      • 範例:

        • q=flood 包含單字flood,floods,flooding的資料集

        • fq=tags:economy 有標籤economy的資料集

        • facet.field=["tags"] facet.limit=10 rows=0 前10個tags

  • 回傳結果: 有以下關鍵字的詳細資料

    • 參數:

      • count (int): 找到的結果數量。(注意:這是所有找到的結果數量,不是返回的結果數量,會受到輸入limit參數和row參數的影響)

      • results (list of dictized datasets):符合查詢的有序資料集列表。順序會定義在查詢的sort參數。

      • facets (DEPRECATED dict): DEPRECATED。facet數量的聚合資料。

      • search_facets (nested dict of dicts.): facet數量的聚合資料。

      • 範例輸出:

        {'count': 2, 
         'results': [ { <snip> }, { <snip> }],
         'search_facets': {u'tags': {'items': [{'count': 1,
                                        'display_name': u'tolstoy',
                                        'name': u'tolstoy'},
                                       {'count': 2,
                                        'display_name': u'russian',
                                        'name': u'russian'}
                                      ]
                            }
                  }
        }
  • 回傳型態: dictionary

  • 限制:完整的solr查詢語言不會外露和包含。

備註: 控制欄位從solr查詢不能被改變的參數,CKAN總是會回傳符合的資料集(dictionary物件)

資料搜尋

  • 請求類型: GET

  • 用途: 搜尋符合搜尋條件的資料

    • 將回傳一個含有2個欄位的字典集('count', 'results') 'count' 包含在沒有限制的情況下所找到的資料總數, 'results' 為搜尋結果列表),當指定多個搜尋條件時將對這些條件進行AND運算. 所有的比對皆忽略大小寫及 'hash' ,除非他是子字串的值.

    • 注意: 搜尋僅限於搜尋配置設定 'ckan.extra_resource_fields' 中聲明的額外字串

    • 注意: 由於資料的額外字段儲存型態為json blob,所以是針對json顯示字串做比對. 因此可能會有誤報發生(若搜尋條件為 'query = "field1:term1"' 然後一個json blob字串顯示形式為 '{"field1": "foo", "field2": "term1"}' 便會發生誤報)

    • 上下文可包含一個標誌(tag),其標誌若為 'search_query' ,且該值為true,將使此方法作為內部搜尋API使用(即:結果不會被編為字典且 'SearchErrors' 拋出錯誤訊息而非 'ValidationErrors')

  • 參數:

    • query (string or list of strings of the form {field}:{term1}): 搜尋條件

      • (資料格式為 {field}:{term} 或一個字串列表,所有字串接使用相同格式. {field}是資料領域物件的字串或額外字段

      • 若 {field} 是 "hash" 則嘗試將{term}與 'Resource.hash' 詞首進行比對

      • 若 {field} 是 額外字段則嘗試與針對資料儲存的額外字串進行比對)

    • fields (dict of fields to search terms.): 已禁用 (因為它與使用API操作的GET請求呼叫不相容)

    • order_by (string): 在資料模型中用於對結果做排序的字串 (目前僅提供一個字段使用且僅按升序排序)

    • offset (int): 查詢偏移量,作為查詢結果的顯示起點

    • limit (int): 查詢結果的數量上限

  • 回傳型態:(dict) 一具有計數字串、結果字串的字典

標籤搜尋

  • 請求類型: GET

  • 用途: 回傳符合指定字串的標簽名稱列表 (在預設情況下僅搜尋任意標籤,亦即不屬於任何詞的標籤。如果使用 'vocabular_id' 那麼將只搜尋屬於該詞彙表的標籤)

  • 參數:

    • query (string or list of strings): (必填) 欲搜尋之字串

    • vocabulary_id (string): (選用) 欲搜尋之標籤辭彙表id或名稱

    • fields (dictionary): 已禁用

    • limit (int): (選用) 回傳標籤數量上限

    • offset (int): 當給定 'limit' 時,將回傳標籤的偏移量

  • 回傳型態:(dictionary) 符合指定字串的字典列表('count': 結果中的標籤數, 'result': 符合指定字串的標籤列表、字典列表)

標籤自動完成

  • 請求類型: GET

  • 用途: 回傳包含指定字串的標籤名稱列表 (在預設情況下僅搜尋自由標籤(不屬於任何詞的標籤)。 如果使用 'vocabular_id' 那麼將只搜尋屬於該詞彙表的標籤)

  • 參數:

    • query (string): (必填) 欲搜尋之字串

    • vocabulary_id (string): (選用) 欲搜尋之標籤辭彙表id或名稱

    • fields (dictionary): 已禁用

    • limit (int): (選用) 回傳標籤數量上限

    • offset (int): 當給定 'limit' 時,將回傳標籤的偏移量

  • 回傳型態:(list of strings) 包含指定字串的標籤名稱列表

建立資料集

  • 請求類型: POST

  • 用途: 新增資料集 (您必須具有創建資料集的權限,若欲將新資料集指定任何資料群組則需授權使用者可編輯這些資料群組。 外掛可根據參數 'type' 的值更改此函數參數,請參閱 'IDatasetForm' 外掛介面)

  • 參數:

    • name (string): (必填) 資料集名稱 (長度需介於2~100個英文字元且僅能包含小寫字元,'-','_'. ex:warandpeace)

    • title (string): (選用) 資料集標題 (預設: 與 'name' 相同)

    • author (string): (選用) 資料集作者名稱

    • author_email (string): (選用) 資料集作者電子信箱

    • maintainer (string): (選用) 資料集維護者名稱

    • maintainer_email (string): (選用) 資料集維護者電子信箱

    • license_id (license id string): (選用) 資料集許可證id (相關可用值請參閱 license_list())

    • notes (string): (選用) 資料集描述

    • url (string): (選用) 資料集連結網址

    • version (string, 不超過100個字元): (選用) 資料集版本

    • state (string): (選用) 資料集目前狀態 (ex. 'active' or 'deleted', 僅有'active'資料集能顯示在搜尋結果和其他資料集列表中,如果您沒有更改資料集狀態的權限此參數將被忽略) (預設: 'active')

    • type (string): (選用) 資料集類型 (IDatasetForm 外掛將自身與不同的資料集類型相連接,並為這些資料集類型提供自定義處理行為)

    • resources (list of resource dictionaries): (選用) 資料集中的資料 (請參閱 'resource_create()' 了解資料字典格式)

    • tags (list of tag dictionaries): (選用) 資料集標籤 (請參閱 'tag_create()' 了解標籤字典格式)

    • extras (list of dataset extra dictionaries): (選用) 資料集的客製化欄位, 此欄位可以添加任意的(key: value)到metadata中 (每個額外的字典應有 'key'(字串), 'value'(字串))

    • relationships_as_object (list of relationship dictionaries): (選用) 物件關聯 (請參閱 'package_relationship_create()' 了解關係字典格式)

    • relationships_as_subject (list of relationship dictionaries): (選用) 子物件關聯 (請參閱 'package_relationship_create()' 了解關係字典格式)

    • groups (list of dictionaries): (選用) 資料集所屬群組 (每個群組應具有一個或多個用於標記現有群組的關鍵'id'或'name'(群組名稱, 字串), 以查看共有哪些群組存在 'group_list()')

    • owner_org (string): (選用) 資料集所屬組織 (相關可用值請參閱 'organization_list()'或'organization_list_for_user()')

  • 回傳型態:(dictionary) 新增資料集 (若 'return_id_only' 設為 "True" 則只回傳資料集標籤)

建立資料

  • 請求類型: POST

  • 用途: 新增資料進資料集列表中.

  • 參數:

    • package_id (string): (必填) 資料集id

    • url (string): (必填) 資料連結網址

    • revision_id (string): (選用) 版本id

    • description (string): (選用) 資料描述

    • format (string): (選用) 資料格式

    • hash (string): (選用) 資料雜湊值

    • name (string): (選用) 資料名稱

    • resource_type (string): (選用) 資料格式

    • mimetype (string): (選用) 資料mime類型

    • mimetype_inner (string): (選用) 資料mime內容

    • cache_url (string): (選用) 暫存連結網址

    • size (int): (選用) 資料大小

    • created (iso date string): (選用) 新增資料

    • last_modified (iso date string): (選用) 最新資料

    • cache_last_updated (iso date string): (選用) 最新暫存資料

    • upload (FieldStorage (optional) needs multipart/form-data): (選用) 上傳資料

  • 回傳型態: (dictionary) 新增的資料

資料集關係建立

  • 請求類型:POST

  • 用途: 建立兩個資料集之間的關係

  • 參數:

    • subject (string): (必填)資料集的名稱或是id。用來作為關係的主語。

    • object (string): (必填)資料集的名稱或是id。用來作為關係的受語。

    • type (string): (必填) 兩個資料集的關係定義。可使用這些選項來描述資料集之間的關係:”depends_on”, “dependency_of”, “derives_from”, “has_derivation”, “links_to”, “linked_from”, “child_of”, “parent_of”。

    • comment (string): 用來描述此關係的註解 (選用)

  • 回傳型態: (Dictionary) 新建立的關係

建立語彙

  • URL: http:://base_url/api/3/action/vocabulary_create

  • 請求類型: POST

  • 用途:建立語彙。必須為系統管理人員才能使用此功能。

  • 參數:

    • name (string): (必填) 語彙名。長度為2 ~ 100個字元,可用字元集為英數字、”_” (底線) 、”-”(連字號)、”.” (句號)。

    • tags (list of strings): (必填) 指定要建立的標籤名。長度為2 ~ 100個字元,可用字元集為英數字、”_” (底線) 、”-”(連字號)、”.” (句號)。

  • 回傳型態: (Dictionary) 新建立的語彙。

建立語彙標籤

  • 請求類型:POST

  • 用途: 建立語彙標籤。必須為系統管理人員才能使用此功能。你只能使用此功能來建立屬於此語彙的標籤。但是不能隨意建立不屬於任何一個語彙的標籤。

  • 參數:

    • name (string): (必填) 標籤名。長度為2 ~ 100個字元,可用字元集為英數字、”_” (底線) 、”-”(連字號)、”.” (句號)。

    • vocabulary_id (string): (必填)欲建立的標籤名對應的語彙id。

  • 回傳型態: (Dictionary) 新建立的標籤

資料更新

  • 用途: 更新指定資料集的資料。更多參數,請參照”建立資料”.

  • 參數:

    • id (string): (必填) 要更新的資料識別名稱。

    • package_id (string): (必填) 指定該資料要置放於哪個資料集底下?

    • url (string): (選用) 資料的URL

    • revision_id (string): (選用) 更新版本號

    • description (string): (選用) 此資料的描述

    • format (string): (選用) 資料格式

    • hash (string): (選用) 資料雜湊碼,用來驗證資料。

    • name (string): (選用) 資料名稱

    • resource_type (string): (選用) 資料類型

    • mimetype (string): (選用) MIME類型

    • mimetype_inner (string): (選用) 內建的MIME類型

    • cache_url (string): (選用) 快取URL

    • size (int): (選用) 資料大小

    • created (iso date string): (選用) 建立日期

    • last_modified (iso date string): (選用) 修改日期

    • cache_last_updated (iso date string): (選用) 最新更新的快取日期

    • upload (FileStorage) : (選用) 上傳的檔案。需要透過multipart/form-data 編碼。

  • 回傳型態: (Dictionary) 更新的資料

資料集關係更新

  • 用途: 更新兩個資料集之間的關係

  • 參數:

    • subject (string): (必填)資料集的名稱或是id。用來作為關係的主語。

    • object (string): (必填)資料集的名稱或是id。用來作為關係的受語。

    • type (string): (必填) 兩個資料集的關係定義。可使用這些選項來描述資料集之間的關係:”depends_on”, “dependency_of”, “derives_from”, “has_derivation”, “links_to”, “linked_from”, “child_of”, “parent_of”。

    • comment (string): 用來描述此關係的註解 (選用)

  • 回傳型態: (Dictionary) 更新完畢的資料集關係

資料集部分更新

  • 用途: 將資料集做部分更新。有提供的欄位更新資料才做異動,沒有提供的欄位就不做異動。

  • 參數: 請參見 “資料集更新” API說明。

  • 回傳型態: (Dictionary) 更新的資料集

資料部分更新

  • 用途: 將資料做部分更新。有提供的欄位更新資料才做異動,沒有提供的欄位就不做異動。

  • 參數: 請參見 “資料更新” API說明。

  • 回傳型態: (Dictionary) 更新的資料。

Last updated