管理システム REST API
このドキュメントでは、RESTコール(GET、POST、PUT、PATCH、DELETE)を使用して管理システムと連動し、プロジェクトやユーザーの作成などのタスクを自動化する可能性について説明します。
すべての例は、curl ユーティリティを使用して作成されています。
一般
認証
システムはBASIC AUTH認証を使用しています。ログインには管理システムユーザーが必要で、通常のWEBアクセスと同じユーザー名とパスワードの組み合わせでログインできます。
データ形式とURLs
すべてのリソースは、HTML、XML、JSON形式でアクセスできます。
これは通常のREST APIとは別のAPIであり、ベースURLはアクセスしようとしている管理システム (例:https://adm-us.drofus.com/)と、同じでなければなりません。
リンク先として、http://[admin-url]/projects は、通常のHTMLのプロジェクト一覧を、http://[admin-url]/projects は、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 | 有効なユーザー名でのPOSTリクエストは、パスワードリセットメールをトリガーします。 |
/password/reset | GET | APIでパスワードを変更するには、トークンとともにこれを使用します。 |
/owners/[id]/tasks/[TaskName]/run?source=[sourcedb]©_ids=[ids] | POST | 指定されたオーナーの全データベースに対してタスクを実行します。タスク名は以下のいずれかです。
|
リソース取得:リスト
リソース | 説明 | パラメータ |
---|---|---|
/projects | すべてのプロジェクトをリスト | ?query=xx は、名前に xx を含むすべてのプロジェクトをリストアップ。 ?show_all=1 非アクティブ・プロジェクトも含める。 |
/projects/1 | id 1のプロジェクトをリスト | |
/owners | すべてのオーナーをリスト | |
/owners/1 | ID1のオーナーをリストのオーナーをリスト | |
/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が割り当てられていることがわかります。
$ curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -u testadmin:testpw -d '{"owner":{"name":"Test"}}' http://[admin-url]/owners
{"owner":{"address":null,"billing_address":null,"contact":null,"id":11,"image":null,"name":"Test","network":null,"note":null,"tech_contact":null}}
新規プロジェクトの作成 (POST /プロジェクト)
新しいプロジェクトを作成するには、いくつかの特別なパラメータが必要です。新しいプロジェクトを作成する際に必要となる最小限のデータは以下の通りです。
パラメータ | 説明 |
---|---|
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 │ 名前 |
すべてのパラメータは必須です。
例
{
"project": {
"new_db": "1",
"new_db_template": "dev-template",
"new_db_name": "rest_test",
"project_type_id": 1,
"name": "REST TEST",
"owner_id": 5,
"description": "TEST CREATE FROM REST",
"constructor" : "dRofus AS"
}
}
新規プロジェクト・ユーザーの作成 (POST /project_users)
$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X POST -u testadmin:testpw -d @data.json http://[admin-url]/project_users
{"project_user":{"created_at":"2016-11-28T12:22:35Z","project_id":408,"role":null,"superuser":null,"user_role_id":null,"username":"hakonhc"}}
data.jsonには、以下が含まれます。
{
"project_user": { "project_id": 408,"room_rights":1 },
"user": {"username": "hakonhc", "first_name":"Håkon","last_name":"Clausen","email":"hhc@drofus.com"},
"mail_type": "6"
}
パラメータ | 説明 |
---|---|
project_user (プロジェクト_ユーザー) | project_id: 追加するプロジェクトのID room_rights: 部屋の権限レベル equipment_rights tender_rights consignation_rights system_rights modelstore_rights superuser. Project Administrator addon_admin: BIM管理者 no_web_admin_access: ユーザーがスーパーユーザーの場合、Web管理者へのアクセスを拒否します。 hide_price: 価格が表示されるか否かを、trueまたはfalseで設定。 |
ユーザー | username: 追加するユーザー名 first_name: 追加するユーザーの名前 last_name: 追加するユーザーの姓名 email: 追加するユーザーのEメール ユーザーが存在する場合、与えられた情報がサーバーに登録されている情報と同じであることを確認します。 |
mail_type (メール_タイプ) | ユーザーに送信するメールのID (from /emails)、”skip_email” は、メールを送信しないことを意味します。 |
リソース取得: オブジェクト操作とその他
データベース
Resource | ||
---|---|---|
/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 Resources: 更新情報
リソース | |
---|---|
/projects/[id] | プロジェクトの更新 |
/project_users/username,projectid | プロジェクトユーザーの更新 |
例1:プロジェクトの更新
$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X PATCH -u testadmin:testpw -d @data.json http://[admin-url]/projects/1
data. json には以下が含まれます。
{
"project": {
"name": "REST TEST",
"description": "TEST UPDATE FROM REST",
"active":true
}
}
例 2: プロジェクトユーザーを更新
$ curl -H "Accept: application/json" -H "Content-type: application/json; charset=UTF-8" -X PATCH -u testadmin:testpw -d @data.json http://[admin-url]/project_user/testuser,1
data. json には以下が含まれます。
{
"project_user":{
"username":"test",
"project_id":647,
"room_rights":1,
"equipment_rights":3,
"tender_rights":4,
"room_surface_treatment_rights":4
}
}
リソースの削除
また、ほとんどのオブジェクトを削除するには、削除 (DELETE)操作を使用します。
この例では、プロジェクト内のユーザーを削除します。
curl -H "Accept: application/json" -s -u http://[admin-url]/project_users/[username],[project_id] -X DELETE
パスワードのリセット
この本文と正しいユーザー名を指定して “/password/request_reset” にJSONリクエストを投稿すると、パスワードのリセット処理が開始されます。ユーザはトークンと一緒にパスワードリセットリクエストをメールで受け取ります:
// Post to {server}/password/request_reset
{
"username": "user"
}
パスワードを変更するには、以下のJSONとEメールのトークンを使用します:
// Post to {server}/password/reset
{
"token": "5f2pi2zW7wO3nodwWznmDQ",
"password": "pass",
"password_confirm": "pass"
}
プロジェクトの統計
リソース | コメント |
---|---|
/project_data | 長期にわたるプロジェクトの統計。 |
/project_data/latest | 各プロジェクトの最新の統計情報を提供します。 |
フィルタ
from_date=[date] | project_dataの場合のみ、時刻が指定された日付より大きいデータを表示します。 |
field=[field] | 特定の分野のみ。 |
owner=[owner_id] | 特定のオーナーIDにのみ対応。 |
出力の例
{
"field": "sum_programmed_area",
"project_id": 1262,
"time": "2019-12-16T10:56:46.848+01:00",
"value": "1233.0"
},
{
"field": "sum_designed_area",
"project_id": 1262,
"time": "2019-12-16T10:56:46.848+01:00",
"value": "1176.0"
},