V2. 管理システム REST API
- Midori Kajitani
これは、RESTコール（GET、POST、PUT、PATCH、DELETE）を使用して管理システムと相互作用する可能性を文書化したもので、プロジェクトやユーザーを作成するようなタスクの自動化を可能にします。
すべての例は、curl ユーティリティを使って作成されています。
- 1 一般
- 1.1 認証
- 1.2 データフォーマットとURL
- 2 リソース:
- 2.1 リソースを取得：リスト
- 3 リソースのPOST：オブジェクトの作成
- 4 リソースを取得：オブジェクトの操作とその他
- 5 POSTリソース：トグルとその他の変更
- 5.1 ユーザー
- 6 PUT/PATCHリソース：最新情報
- 6.1 リソースの削除
- 6.2 パスワードのリセット
- 6.3 プロジェクトの統計
- 6.4 フィルタ
- 6.5 出力の例
一般
認証
システムは、BASIC AUTH認証を使用しています。ログインには管理者ユーザが必要で、通常のWEBアクセスと同じユーザ名
パスワードの組み合わせでログインできます。
データフォーマットとURL
すべてのリソースは、HTML、XML、JSON形式でアクセスできます。
これは通常のREST APIとは別のAPIで、ベースURLはアクセスしようとしている管理システム
(つまり、https://adm-us.drofus.com/) と同じでなければなりません。
例えば、http://[admin-url]/projects というリンクは、通常のHTMLのプロジェクト一覧を表示し、
http://[admin-url]/projects .json は、JSONフォーマットでプロジェクトとプロジェクトユーザーを表示します。
一部のリソース (特にユーザー) はリソース名にドット(.)を含むため、.jsonを使用できません。
代わりに、ヘッダーに “Accept: application/json” を送るようにしてください。
（これはすべてのタイプのクライアント (例：postmanなど) に当てはまります）
Acceptヘッダーを、”application/json”に設定することは、json形式のレスポンスを得るための推奨方法です。
.jsonを使用するのは、テストするときだけにしてください。
curl -H "Accept: application/json" -s -u testadmin:testpw http://[admin-url]/users/hakonhcと同じになります。
curl -s -u testadmin:testpw http://[admin-url]/users/hakonhc.jsonリソース:
リソース | 説明 |
|---|---|
/projects | プロジェクトのリストと操作 |
/owners | プロジェクト所有者のリスト |
/users | サーバー上のユーザーの一覧と操作 |
/database | データベースの一覧表示と操作 |
/project_users | プロジェクトのユーザー一覧と操作 |
多くのリソースは、GET、PATCH、DELETEの両方に応答します。
さらに、以下のような特別なエンドポイントもあります：
リソース | メソッド | 説明 |
|---|---|---|
/node/logins | GET | 過去5年間のプロジェクトのログイン統計を、クライアントの使用タイプ(Revit、dRofusなど)別にグループ化して取得します。 |
/node/logins?from_date=2018-01-01&to_date=2019-12-31 | GET | 指定された期間のプロジェクトのログイン統計情報を、使用しているクライアントのタイプごとにグループ化して取得します (Revit、dRofusなど)。 |
/node/unique_users | GET | 過去5年間の各プロジェクトのユニーク・ユーザー数を取得します。 |
/node/unique_users?from_date=2018-01-01&to_date=2019-12-31 | GEt | 指定された期間における各プロジェクトのユニークユーザー数を取得します。 |
/project_data?from_date=2018-01-01&to_date=2019-12-31 | GEt | プロジェクトの統計値を取得、to_dateとfrom_dateは、日付のオプション制限です。 |
/password/request_reset | GET | 有効なユーザー名でのポスト リクエストは、パスワードリセットメールをトリガーします。 |
/password/reset | GET | APIでパスワードを変更するには、トークンとともにこれを使用します。 |
/owners/[id]/tasks/[TaskName]/run?source=[sourcedb]©_ids=[ids] | POST | 特定の所有者の全データベースに対して特定のタスクを実行します。タスク名 (TaskName)は以下のいずれかです。
|
リソースを取得：リスト
リソース | 説明 | パラメータ |
|---|---|---|
/projects | すべてのプロジェクトをリスト | ?query=xx は、プロジェクト名に xx を含むすべてのプロジェクトをリストアップします。 ?show_all=1 活動休止中のプロジェクトも含める。 |
/projects/1 | id 1のプロジェクトをリスト |
|
/owners | すべての所有者をリスト |
|
/owners/1 | 所有者を id 1 でリスト |
|
/users | 全ユーザーのリスト | ?query=xxを検索する。 |
/users/username | ユーザー名でユーザーをリスト |
|
/database | データベースのリスト |
|
/project_users/username,projectid | プロジェクトユーザーを表示 |
|
例
$ curl -s -u testadmin:testpw http://[admin-url]/projects.json?query=template|json_reformat
[
{
"project": {
"active": true,
"contact": null,
"created_at": "2016-11-01T09:39:14Z",
"created_by": null,
"database_id": "akl-test",
"description": null,
"gross_area": null,
"id": 399,
"name": "dRofus dev template",
"no": "01",
"owner_id": 5,
"status": null,
"updated": null,
"updated_by": null,
"unit_type": "SM" #SM for square meters or SF for square feet
}
},
.....リソースのPOST：オブジェクトの作成
例
これにより “テスト (Test)”という名前の所有者が作成され、ID 11が割り当てられていることがわかります。
新規プロジェクトの作成 (POST/projects)
新しいプロジェクトを作成するには、いくつかの特別なパラメータが必要です。新しいプロジェクトを作成する際に、最低限必要なデータは以下の通りです。
パラメータ | 説明 |
|---|---|
new_db | 新しいデータベースを作成する場合は1、既存のデータベースにプロジェクトを追加する場合は0。 |
new_db_template | 新しいデータベースを作成する場合は、テンプレートとして使用するデータベース名を指定。 |
new_db_name | 新しいデータベースを作成する場合は、新しいデータベースの名前を入力してください。 |
existing_db_name | 新しいデータベースを作成しない場合（new_dbを0に設定）、新しいプロジェクトを追加する既存のデータベース名を指定。 |
name | プロジェクト名。 |
constructor | 新規プロジェクトの施工者 (建設者)／会社名。 |
description | プロジェクトの内容。 |
owner_id | 所有者 (オーナー) のID。 |
project_type_id | プロジェクトのタイプ。以下の値のいずれかを使用します。
id │ 名前
|
すべてのパラメータは必須です。
例
新規プロジェクト・ユーザーの作成 (POST /project_users)
data.jsonには以下の内容が含まれます。
パラメータ | 説明 |
|---|---|
project_user | project_id：追加するプロジェクトのID room_rights：部屋の許可レベル equipment_rights tender_rights consignation_rights system_rights modelstore_rights superuser. プロジェクト管理者 addon_admin：BIM管理者 no_web_admin_access：ユーザーがスーパーユーザーの場合、Web管理者へのアクセスを拒否 hide_price: ユーザーが価格を見た場合、true (真)またはfalse (偽) |
ユーザー | username：追加するユーザのユーザー名 first_name：追加するユーザーの名前 last_name：追加するユーザーの姓名 email: Email of the user to add ユーザーが存在する場合、与えられた情報がサーバーに登録されている情報と同じであることを確認します。 |
mail_type | ユーザーに送信するメールのID (from /emails)、”skip_email”はメールを送信しないことを意味します。 |
リソースを取得：オブジェクトの操作とその他
データベース
リソース |
|
|---|---|
/database/[dbname]/disableall | dbnameという名前のデータベース内のすべてのプロジェクトユーザーを無効にする。 |
/database/[dbname]/enableall | dbname という名前のデータベース内のすべてのプロジェクト・ユーザーを有効にする。 |
/database/[dbname]/kickall | dbname という名前のデータベース内のすべてのユーザーをログアウトする。 |
/database/[dbname]/get_backup_now | データベースのバックアップをダウンロードする。 |
ユーザー
リソース |
|
|---|---|
/users/[username]/disable | プロジェクトにログインできないようにユーザーを無効にする。 |
/users/[username]/enable | ユーザーを有効にする。 |
/users/[username]/kick | データベースxxxの全ユーザーをログアウトする。 |
POSTリソース：トグルとその他の変更
ユーザー
リソース |
|
|---|---|
/users/[username]/toggle_otp | ユーザーが、多要素認証を使用してログインしなければならないかどうかを切り替えます。 |
/users/[username]/toggle_force_weblogin | モダン・ログイン/SSOを使用してログインするかどうかを切り替えます。 |
/users/[username]/toggle_local_authentication | ユーザが、ローカル認証を使用できるか、外部認証 (Entra) を使用しなければならないかを切り替えます。 |
/users/[username]/toggle_enable | ユーザの有効/無効を切り替えます。 |
/users/[username]/merge?to=[to_username] | ユーザーを別のユーザーに統合。 |
PUT/PATCHリソース：最新情報
リソース |
|
|---|---|
/projects/[id] | プロジェクトの更新 |
/project_users/username,projectid | プロジェクトユーザーの更新 |
例1：プロジェクトの更新
data.jsonに含まれる内容
例 2: プロジェクトユーザーを更新
data.jsonに含まれる内容
リソースの削除
また、削除 (DELETE)オペレーションを使用して、ほとんどのオブジェクトを削除することができます。
この例では、プロジェクト内のユーザーを削除します。
パスワードのリセット
この本文と正しいユーザー名を含むjsonリクエストを “/password/request_reset”にポストすると、パスワードのリセット処理が開始されます。ユーザーはトークン付きのパスワードリセットリクエストをメールで受け取ります：
実際のパスワード変更には、メールに記載されたトークンと以下のjsonを使用します：
プロジェクトの統計
リソース | コメント |
|---|---|
/project_data | 長期にわたるプロジェクトの統計 |
/project_data/latest | 各プロジェクトの最新の統計情報を提供 |
フィルタ
|
|
|---|---|
from_date=[date] | project_dataにのみ適用され、時刻が指定された日付より大きい |
field=[field] | 特定のフィールドのみ |
owner=[owner_id] | 特定の所有者 idのみ |
|
|
出力の例