API 가이드

이 섹션에서는 데이터포털 사이트 및 해당 데이터와 상호 작용하는 코드를 작성하려는 개발자를위한 API에 대해 설명합니다.

CKAN의 Action API 는 강력한 CKAN의 핵심 기능을 API 클라이언트에 노출시키는 강력한 RPC 스타일 API입니다. CKAN 웹 사이트의 핵심 기능 (웹 인터페이스 등으로 할 수있는 모든 것)은 CKAN API를 호출하는 외부 코드에서 사용할 수 있습니다. 예를 들어 CKAN API를 사용하면 앱에서 다음을 수행 할 수 있습니다.

Note

CKAN의 FileStore 및 DataStore에는 자체 API가 있습니다:

Making an API request

CKAN API를 호출하려면 HTTP POST 요청의 JSON 사전을 CKAN의 API URL 중 하나에 게시하십시오. API 함수의 매개 변수는 JSON 사전에 제공되어야합니다. CKAN은 또한 응답을 JSON 사전으로 반환합니다.

JSON 사전을 URL에 게시하는 한 가지 방법은 명령 행 클라이언트 Curl을 사용하는 것 입니다. 예를 들어 data-explorer 의 그룹에 있는 모든 데이터 세트의 이름 목록을 얻으려면 curl을 설치 한 다음 group_list 터미널에서 이 명령을 실행 하여 API 함수 를 호출하십시오:

curl https://demo.ckan.org/api/3/action/group_list

CKAN의 응답은 다음과 같습니다:

{
    "help": "...",
    "result": [
        "data-explorer",
        "department-of-ricky",
        "geo-examples",
        "geothermal-data",
        "reykjavik",
        "skeenawild-conservation-trust"
    ],
    "success": true
}

응답은 세 개의 키가있는 JSON 사전입니다:

  1. "success": true or false.

    API는 항상 “200 OK”를 HTTP 응답의 상태 코드로 반환하는 것을 목표로 합니다. 그렇지만 요청에 오류가 있었는지 여부를 확인해야 하므로 결과의 반환된 값에서 항상 "success" 키 값을 확인하고 (success의 키 값이 "false" 인 경우) "error" 키 값을 확인하는 것이 중요합니다.

  2. "result": 호출한 함수에서 반환된 결과입니다. 결과의 유형과 값은 호출한 함수에 따라 다릅니다. group_list 함수의 경우 해당 함수의 문자열 목록, 즉 그룹에 속한 모든 데이터 집합의 이름입니다.

요청에 응답하는 동안 오류가 발생하면 사전에 "result" 키 대신 오류 세부 정보가 포함된 "error" 키가 포함됩니다. 오류가 포함된 응답 사전은 다음과 같습니다:

{
    "help": "Creates a package",
    "success": false,
    "error": {
        "message": "Access denied",
        "__type": "Authorization Error"
        }
 }
  1. "help": 호출한 함수의 문서 문자열입니다.

아래의 Python코드와 함께 Python의 표준 urllib2 모듈을 사용하여 동일한 HTTP 요청을 할 수 있습니다:

#!/usr/bin/env python
import urllib2
import urllib
import json
import pprint

# Make the HTTP request.
response = urllib2.urlopen('http://demo.ckan.org/api/3/action/group_list', data_string)
assert response.code == 200

# Use the json module to load CKAN's response into a dictionary.
response_dict = json.loads(response.read())

# Check the contents of the response.
assert response_dict['success'] is True
result = response_dict['result']
pprint.pprint(result)

Example: Importing datasets with the CKAN API

웹 인터페이스를 사용하여 데이터셋을 추가 할 수 있지만 많은 데이터셋을 가져올 때 일반적으로 프로세스를 자동화하는 것이 더 효율적입니다. 이 예에서는 API를 사용하여 데이터셋을 저장소로 가져 오는 Python 스크립트를 작성하는 방법을 보여줍니다.

#!/usr/bin/env python
import urllib2
import urllib
import json
import pprint

# Put the details of the dataset we're going to create into a dict.
dataset_dict = {
    'name': 'my_dataset_name',
    'notes': 'A long description of my dataset',
    'owner_org': 'org_id_or_name'
}

# Use the json module to dump the dictionary to a string for posting.
data_string = urllib.quote(json.dumps(dataset_dict))

# We'll use the package_create function to create a new dataset.
request = urllib2.Request(
    'http://www.my_ckan_site.com/api/action/package_create')

# Creating a dataset requires an authorization header.
# Replace *** with your API key, from your user account on the CKAN site
# that you're creating the dataset on.
request.add_header('Authorization', '***')

# Make the HTTP request.
response = urllib2.urlopen(request, data_string)
assert response.code == 200

# Use the json module to load CKAN's response into a dictionary.
response_dict = json.loads(response.read())
assert response_dict['success'] is True

# package_create returns the created package as its result.
created_package = response_dict['result']
pprint.pprint(created_package)

API versions

API는 버전이 있습니다. 버전 번호없이 API URL을 요청하면 최신 버전의 API를 선택합니다:

http://demo.ckan.org/api/action/package_list

또는 요청한 URL에 원하는 API 버전 번호를 지정할 수 있습니다:

http://demo.ckan.org/api/3/action/package_list

버전 3은 현재 Action API의 유일한 버전입니다.

요청 시 API 번호를 지정하는 것이 좋습니다. 이렇게 하면 다른 버전의 CKAN을 실행하는 여러 사이트에서 API 클라이언트가 작동하고 동일한 사이트에서 동일한 버전의 CKAN으로 업그레이드될 수 있기 때문입니다. 사이트를 새로운 버전의 CKAN으로 업그레이드하면 최신 버전의 API가 변경되거나 다른 버전의 CKAN을 실행하는 사이트마다 다를 수 있기 때문에 API 버전 번호를 지정하지 않은 API 요청의 결과를 신뢰할 수 없습니다.

Authentication and API tokens

일부 API 기능에는 인증이 필요합니다. API는 웹 인터페이스와 동일한 권한 부여 기능 및 구성을 사용하므로 사용자가 웹 인터페이스에서 무언가를 수행 할 권한이있는 경우 API를 통해서도 권한을 부여받을 수 있습니다.

권한이 필요한 API 함수를 호출 할 때 HTTP 요청에 인증 키를 제공하여 자신을 인증해야합니다. 이는 UI (사용자 프로필> 관리> API 토큰) 또는 api_token_create() 기능을 통해 수동으로 생성 할 수있는 암호화 된 키입니다 . 사용자는 다른 용도로 필요한만큼 많은 토큰을 생성하고 언제든지 하나 이상의 토큰을 취소 할 수 있습니다. 또한 expire_api_token 핵심 플러그인을 활성화하면 토큰의 만료 타임 스탬프를 정의 할 수 있습니다.

사이트 관리자는 API 토큰 설정 을 사용하여 토큰 생성을 구성 할 수 있습니다 .

HTTP 요청에 API 토큰을 제공하려면 Authorization 또는 X-CKAN-API-Key 헤더에 해당 토큰을 포함합니다. (HTTP 헤더의 이름은 CKAN 구성 파일의 apikey_header_name 옵션으로 구성할 수 있습니다.)

예를 들어, 현재 curl을 사용하여 demo.ckan.org의 사용자 표시에 따르고 있는지 여부를 확인하려면 다음 명령을 실행합니다:

curl -H "Authorization: XXX"  https://demo.ckan.org/api/3/action/am_following_user?id=markw
# XXX를 API 토큰으로 대체합니다.

또는 demo.ckan.org의 사용자 대시보드에서 작업 목록을 가져오려면 다음 Python 코드를 실행합니다:

request = urllib2.Request('https://demo.ckan.org/api/3/action/dashboard_activity_list')
request.add_header('Authorization', 'XXX')
response_dict = json.loads(urllib2.urlopen(request, '{}').read())

GET-able API functions

ckan.logic.action.get 에 정의된 함수 는 HTTP GET 요청으로 호출 할 수도 있습니다. 예를 들어 demo.ckan.org에서 데이터셋 목록을 얻으려면 브라우저에서이 URL을 엽니다:

http://demo.ckan.org/api/3/action/package_list

또는 demo.ckan.org에서 검색어 와 일치하는 데이터셋을 검색하려면 브라우저에서이 URL을여십시오:

http://demo.ckan.org/api/3/action/package_search?q=spending

검색어는 URL 매개 변수로 ?q=spending 이 제공됩니다 . 여러 URL 매개 변수를 문자로 구분하여 추가하려면 & 를 사용하십시요. 예를 들어 아래 URL은 처음 10 개의 일치하는 데이터셋만 열도록 할 수 있습니다:

http://demo.ckan.org/api/3/action/package_search?q=spending&rows=10

여러번 요청동작에서 매개 변수의 값으로 문자열 목록이 필요한 경우 URL에서 매개 변수를 여러 번 지정하여 값을 전송할 수 있습니다:

http://demo.ckan.org/api/3/action/term_translation_show?terms=russian&terms=romantic%20novel

JSONP support

API에 액세스하려는 다른 사이트의 스크립트를 제공하기 위해 JSONP 형식으로 데이터를 리턴 할 수 있습니다. 여기서 JSON 데이터는 함수 호출로 ‘padded’됩니다. 함수는 ‘callback’매개 변수에 이름이 지정됩니다. 예를 들면 다음과 같습니다:

http://demo.ckan.org/api/3/action/package_show?id=adur_district_spending&callback=myfunction

Note

이것은 GET 요청에 대해서만 작동합니다

Action API reference

Note

API중 하나를 호출할 때 해당 기능이 예외를 발생시키면 API에서 "success": false 와 제기된 예외를 나타내는 "error" 키가 JSON 사전에 반환 됩니다.

예를 들어 member_list() (그룹 구성원의 목록을 반환하는) 그룹이 없으면 NotFound 가 발생합니다. API를 통해 호출하면 다음과 같은 JSON결과값을 받을 수 있습니다:

{
    "success": false
    "error": {
        "__type": "Not Found Error",
        "message": "Not found"
    },
    "help": "...",
}

ckan.logic.action.get

CKAN에서 데이터를 검색하고 가져 오기위한 API 함수.

Note

ckan.logic.action.get.site_read(context, data_dict=None)

return

true

return type

bool

Note

ckan.logic.action.get.package_list(context, data_dict)

싸이트별 데이터셋의 이름 목록을 반환 합니다.

Parameters:
  • limit (int) – if given, the list of datasets will be broken into pages of at most limit datasets per page and only one page will be returned at a time (optional)

  • offset (int) – when limit is given, the offset to start returning packages from

Return type:

list of strings

ckan.logic.action.create

CKAN에 데이터를 추가하기위한 API 함수.

Note

ckan.logic.action.create.package_create(context, data_dict)

새 데이터 집합(패키지)을 생성합니다.

새 데이터 세트를 생성할 수 있는 권한이 있어야 합니다. 새 데이터 집합에 대한 그룹을 지정하는 경우 이러한 그룹을 편집할 권한도 있어야 합니다. 플러그인은 유형 매개 변수의 값에 따라 이 기능의 매개 변수를 변경할 수 있습니다.

Parameters:
  • name (string) – the name of the new dataset, must be between 2 and 100 characters long and contain only lowercase alphanumeric characters, - and _, e.g. ‘warandpeace’

  • title (string) – the title of the dataset (optional, default: same as name)

  • private (bool) – If True creates a private dataset

  • author (string) – the name of the dataset’s author (optional)

  • author_email (string) – the email address of the dataset’s author (optional)

  • maintainer (string) – the name of the dataset’s maintainer (optional)

  • maintainer_email (string) – the email address of the dataset’s maintainer (optional)

  • license_id (license id string) – the id of the dataset’s license, see license_list() for available values (optional)

  • notes (string) – a description of the dataset (optional)

  • url (string) – a URL for the dataset’s source (optional)

  • version (string, no longer than 100 characters) – (optional)

  • state (string) – the current state of the dataset, e.g. ‘active’ or ‘deleted’, only active datasets show up in search results and other lists of datasets, this parameter will be ignored if you are not authorized to change the state of the dataset (optional, default: ‘active’)

  • type (string) – the type of the dataset (optional), IDatasetForm plugins associate themselves with different dataset types and provide custom dataset handling behaviour for these types

  • resources (list of resource dictionaries) – the dataset’s resources, see resource_create() for the format of resource dictionaries (optional)

  • tags (list of tag dictionaries) – the dataset’s tags, see tag_create() for the format of tag dictionaries (optional)

  • extras (list of dataset extra dictionaries) – the dataset’s extras (optional), extras are arbitrary (key: value) metadata items that can be added to datasets, each extra dictionary should have keys ‘key’ (a string), ‘value’ (a string)

  • relationships_as_object (list of relationship dictionaries) – see package_relationship_create() for the format of relationship dictionaries (optional)

  • relationships_as_subject (list of relationship dictionaries) – see package_relationship_create() for the format of relationship dictionaries (optional)

  • groups (list of dictionaries) – the groups to which the dataset belongs (optional), each group dictionary should have one or more of the following keys which identify an existing group: ‘id’ (the id of the group, string), or ‘name’ (the name of the group, string), to see which groups exist call group_list()

  • owner_org (string) – the id of the dataset’s owning organization, see organization_list() or organization_list_for_user() for available values. This parameter can be made * optional if the config option ckan.auth.create_unowned_dataset is set to True.

Returns:

the newly created dataset (unless ‘return_id_only’ is set to True in the context, in which case just the dataset id will be returned)

Return type:

dictionary

ckan.logic.action.update

CKAN에서 기존 데이터를 업데이트하기위한 API 함수.

Note

ckan.logic.action.update.resource_update(context, data_dict)

리소스를 업데이트합니다. 리소스를 업데이트하려면 해당 리소스가 속한 데이터 집합을 업데이트할 수 있는 권한이 있어야 합니다.

Parameters:
  • id (string) – the id of the resource to update

Returns:

the updated resource

Return type:

string

ckan.logic.action.patch

CKAN에서 기존 데이터의 부분 업데이트를위한 API 함수

Note

ckan.logic.action.patch.package_patch(context, data_dict)

데이터셋을 패치 합니다.

Parameters:
  • id (string) – the id or name of the dataset

Update와 Patch의 차이점은 Patch가 제공된 매개 변수를 업데이트하는 동시에 다른 모든 매개 변수를 변경하지 않고 data_dict에서 명시적으로 제공되지 않은 매개 변수를 모두 삭제한다는 점입니다.

package_patch로 리소스를 부분적으로 업데이트하거나 생성할 수 있습니다. 기존 리소스를 업데이트하는 경우 리소스 ID를 제공해야 합니다. package_patch data_dict에서 제외된 기존 리소스가 제거됩니다. ID가 없는 패키지 data_dct의 리소스는 새 리소스로 처리되고 추가됩니다. 패치 방법으로 추가된 새 리소스는 기본 보기를 생성하지 않습니다.

ckan.logic.action.delete

CKAN에서 데이터를 삭제하기위한 API 함수.

Note

ckan.logic.action.delete.package_delete(context, data_dict)

데이터셋을 삭제 합니다.

이렇게 하면 휴지통을 제외한 모든 웹 및 API 보기에서 데이터 집합이 사라집니다. 데이터 집합을 삭제할 권한이 있어야 합니다.

Parameters:
  • id (string) – the id or name of the dataset to delete