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のモジュール名で置き換えます。
https://local.yourdomain/cgi-bin/dneo/zrconst.cgi
認証
アクセスするユーザーを特定するためにアクセスキーを渡す必要があります。
アクセスキーの渡し方は以下のいずれかです。
- access_keyという名前のリクエストパラメーター
- X-Desknets-Authという名前のリクエストヘッダー
渡すことのできるアクセスキーは以下のいずれかです。
- アクセスキー設定で発行したアクセスキー
- ログインAPIで発行されたアクセスキー
レスポンス
処理の結果はJSONで返ります。処理に成功した場合、statusがokになりAPIごとに異なる形式の情報が出力されます。処理に失敗した場合、statusがngになり共通形式のエラー情報が出力されます。
| キー | 値 | 説明 |
| 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 | [パスワード] | ユーザーのパスワードを設定します。 |
レスポンス
| キー | 値 | 説明 |
| 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] |
指定すると、その組織、または個人グループのユーザーのみ取得します。省略すると、組織、個人グループに関係なくユーザーを取得します。
|
| name | [氏名かふりがな] |
指定すると、氏名かふりがなに入力値を含むユーザーのみ取得します。 |
| offset | [開始位置] | 何件目から取得するか(先頭は0)を指定します。省略すると、先頭から取得します。 |
| limit | [取得件数上限] | 最大何件取得するかを指定します。 |
レスポンス
| キー | 値 | 説明 |
| 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] |
指定した場合、その組織の直下の組織を取得します。省略した場合、ルート直下の組織を取得します。 |
| offset | [開始位置] | 何件目から取得するか(先頭は0)を指定します。省略すると、先頭から取得します。 |
| limit | [取得件数上限] | 最大何件取得するかを指定します。 |
レスポンス
| キー | 値 | 説明 |
| 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