desknet's NEO 共通APIの仕様

共通仕様

HTTPを使用して送受信します。リクエスト、レスポンスともに文字コードはUTF-8です。

基本的にGETとPOST、どちらで送っても構いません。

リクエストパラメーターはクエリー文字列(key=value&…)で送ります。非ASCII文字や一部記号はURLエンコードしてください。ただし、送信するデータにファイルを含む場合、マルチパートで送る必要があります。

APIに複数のアクセスがあった時、2つ目以降のAPIは前のAPIが完了してから1つずつ処理されます。処理待機中のAPIが10件を超えると、約10秒間APIのレスポンスがHTTP429(Too Many Requests)になります。

URL

desknet's NEOのURLと同じパスを指定します。ファイル名の部分は各APIのモジュール名で置き換えます。

desknet's NEOのURLがhttps://local.yourdomain/cgi-bin/dneo/dneo.cgi、モジュール名がzrconstの場合のURL

https://local.yourdomain/cgi-bin/dneo/zrconst.cgi

認証

アクセスするユーザーを特定するためにアクセスキーを渡す必要があります。

アクセスキーの渡し方は以下のいずれかです。

access_keyという名前のリクエストパラメーター
X-Desknets-Authという名前のリクエストヘッダー

渡すことのできるアクセスキーは以下のいずれかです。

アクセスキー設定で発行したアクセスキー
ログインAPIで発行されたアクセスキー

レスポンス

処理の結果はJSONで返ります。処理に成功した場合、statusがokになりAPIごとに異なる形式の情報が出力されます。処理に失敗した場合、statusがngになり共通形式のエラー情報が出力されます。

【JSON】処理に成功した場合

{ "status":"ok", … }

【JSON】処理に失敗した場合

{ "status":"ng", "errorno":エラー番号, "errormessage": エラーメッセージ, "errmsgadd": 追加情報 }

キー	値	説明
status	[ok \| ng]	処理に成功したときはok、そうでないときはngになります。
errorno	[エラー番号]	エラーごとの番号です。エラーが発生した場合のみ設定されます。
errormessage	[エラーメッセージ]	エラーの内容を示すメッセージです。エラーが発生した場合のみ設定されます。
errmsgadd	[追加情報]	特定のパラメーターに関連するエラーが発生した場合、そのパラメーター名が設定されます。例えば必須パラメーターがない場合、そのパラメーター名が設定されます。

実行例

リクエストヘッダーで渡す場合

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/zrconst.cgi \
-H 'X-Desknets-Auth: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d action=list_users

Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/zrconst.cgi `
-Headers @{'X-Desknets-Auth'='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'} `
-Method Post `
-Body @{
'action' = 'list_users'
}

リクエストパラメーターで渡す場合

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/zrconst.cgi \
--data-urlencode access_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
-d action=list_users

Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/zrconst.cgi `
-Method Post `
-Body @{
'access_key' = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
'action' = 'list_users'
}

ログインAPI

モジュール名

dneor

概要

ユーザーの認証を行い、アクセスキーを発行します。
発行されたアクセスキーは3日経過後の午前0時まで有効です。

リクエストパラメーター

パラメーター名	指定する値	説明
action	login	固定値
login_id	[ログインID]	ユーザーのログインIDを設定します。
password	[パスワード]	ユーザーのパスワードを設定します。

レスポンス

【JSON】

{ "status": "ok", "access_key": アクセスキー, "user_id": ユーザーシステムID, "name": 氏名, "default_group_id": 代表組織システムID }

キー	値	説明
access_key	[アクセスキー]	他のAPIでユーザーを認証するために渡すキーです。有効期限は3日です。
user_id	[ユーザーシステムID]	ログインしたユーザーのシステムIDです。
name	[氏名]	ログインしたユーザーの氏名です。
default_group_id	[代表組織システムID]	ログインしたユーザーの代表組織のシステムIDです。

実行例

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/dneor.cgi \
-d action=login \
-d login_id=yamada \
-d password=xxxxxxxxxx

$response = Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/dneor.cgi `
-Method Post `
-Body @{
'action' = 'login'
'login_id' = 'yamada'
'password' = 'xxxxxxxxxx'
}
$response.Content

ログアウトAPI

モジュール名

dneor

概要

ログイン APIで発行したアクセスキーを削除します。

リクエスト

パラメーター名	指定する値	説明
action	logout	固定値

実行例

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/dneor.cgi \
-H 'X-Desknets-Auth: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d action=logout

$response = Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/dneor.cgi `
-Headers @{'X-Desknets-Auth'='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'} `
-Method Post `
-Body @{
'action' = 'action=logout'
}
$response.Content

ユーザー一覧API

モジュール名

zrconst

概要

ユーザー一覧を取得します。

リクエスト

パラメーター名	指定する値	説明
action	list_users	固定値
group_id	[組織システムID \| 個人グループシステムID]	指定すると、その組織、または個人グループのユーザーのみ取得します。省略すると、組織、個人グループに関係なくユーザーを取得します。正の値の場合: 指定したシステムIDの組織に所属するユーザーのみ取得します。負の値の場合: 指定したシステムIDの個人グループのユーザーのみ取得します。 0の場合: 組織に所属しないユーザーのみ取得します。
name	[氏名かふりがな]	指定すると、氏名かふりがなに入力値を含むユーザーのみ取得します。
offset	[開始位置]	何件目から取得するか(先頭は0)を指定します。省略すると、先頭から取得します。
limit	[取得件数上限]	最大何件取得するかを指定します。

レスポンス

【JSON】

{ "status": "ok", "allcnt": 総件数, "list": { "item": [ { "id": ユーザーシステムID, "name": 氏名, "assigned_groups": { "item": [ { "id": 所属組織システムID, "name": 所属組織名, "is_default": 代表組織 }, … ] } }, … ] } }

キー	値	説明
allcnt	総件数	範囲指定(limit、offset)を無視したユーザーの総件数です。
id	[ユーザーシステムID]	各ユーザーのシステムIDです。
name	[氏名]	各ユーザーの氏名です。
assigned_groups	[所属組織]	各ユーザーの所属組織です。
id	[所属組織システムID]	ユーザーの所属組織のシステムIDです。
name	[所属組織名]	ユーザーの所属組織の組織名です。
is_default	[代表組織]	ユーザーの代表組織である場合はon、そうでなければoffになります。

実行例

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/zrconst.cgi \
-H 'X-Desknets-Auth: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d action=list_users \
-d group_id=1 \
--data-urlencode name=山田 \
-d offset=0 \
-d limit=100

$response = Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/zrconst.cgi `
-Headers @{'X-Desknets-Auth'='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'} `
-Method Post `
-Body @{
'action' = 'list_users'
'group_id' = '1'
'name' = '山田'
'offset' = '0'
'limit' = '100'
}
$response.Content

組織一覧API

モジュール名

zrconst

概要

組織一覧を取得します。

リクエスト

パラメーター名	指定する値	説明
action	list_groups	固定値
area	[public \| private]	privateを指定した場合、ログインユーザーの個人グループを取得します。publicまたは省略した場合、組織を取得します。
group_id	[親組織システムID]	指定した場合、その組織の直下の組織を取得します。省略した場合、ルート直下の組織を取得します。 ※areaをprivateにした場合、このパラメーターは無視されます。
offset	[開始位置]	何件目から取得するか(先頭は0)を指定します。省略すると、先頭から取得します。
limit	[取得件数上限]	最大何件取得するかを指定します。

レスポンス

【JSON】

{ "status": "ok", "allcnt": 総件数, "list": { "item": [ { "id": 組織システムIDか個人グループシステムID, "name": 組織名か個人グループ名, "children": 子組織数 }, … ] } }

キー	値	説明
allcnt	総件数	範囲指定(limit、offset)を無視した組織、または個人グループの総件数です。
id	[組織システムIDか個人グループシステムID]	各組織、または個人グループのシステムIDです。
name	[組織名か個人グループ名]	各組織、または個人グループの名前です。
children	[子組織数]	各組織の子組織の件数です。

実行例

curl
PowerShell

curl https://local.yourdomain/cgi-bin/dneo/zrconst.cgi \
-H 'X-Desknets-Auth: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d action=list_groups \
-d group_id=1 \
-d offset=0 \
-d limit=100

$response = Invoke-WebRequest -Uri https://local.yourdomain/cgi-bin/dneo/zrconst.cgi `
-Headers @{'X-Desknets-Auth'='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'} `
-Method Post `
-Body @{
'action' = 'list_groups'
'group_id' = '1'
'offset' = '0'
'limit' = '100'
}
$response.Content