管理システムREST API

このドキュメントでは、RESTコール (GET、POST、PUT、PATCH、DELETE) を使用して管理システムと対話する可能性があり、プロジェクトやユーザーの作成などのタスクを自動化することができます。

すべての例は、curl ユーティリティを使用して作成されています。

一般

認証

本システムは、基本認証 (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はテスト時のみ使用するようにしてください。

CODE

curl -H "Accept: application/json" -s -u testadmin:testpw http://[admin-url]/users/hakonhc

と同じになります。

CODE

curl -s -u testadmin:testpw http://[admin-url]/users/hakonhc.json

リソース :

リソース	説明
/projects	プロジェクトのリストと操作
/owners	プロジェクトオーナーリスト
/users	サーバー上のユーザーのリストと操作
/database	データベースのリストと操作
/project_users	プロジェクト内のユーザーの一覧表示と操作

ほとんどのリソースは、GET、PATCH、DELETEの両方に応答します。

さらに、の特別なエンドポイントがいくつかあります :

リソース	説明
/node/logins	使用したクライアントのタイプ(Revit、dRofusなど)ごとにグループ化された、過去5年間のプロジェクトのログイン統計を取得します。
/node/logins?from_date=2018-01-01&to_date=2019-12-31	使用されているクライアントのタイプ（Revit、dRofusなど）ごとにグループ化された、指定された期間のプロジェクトのログイン統計を取得します。
/node/unique_users	過去5年間の各プロジェクトの一意のユーザー数を取得します。
/node/unique_users?from_date=2018-01-01&to_date=2019-12-31	指定された期間の各プロジェクトの一意のユーザー数を取得します。
/project_data?from_date=2018-01-01&to_date=2019-12-31	プロジェクトの統計値を取得する to_dateとfrom_dateはオプションで日付の制限をかけることができます。
/password/request_reset	有効なユーザー名を持つ投稿要求は、パスワードリセットメールをトリガーします。
/password/reset	APIでパスワードを変更するには、トークンと一緒に使用します。

リソースの取得 : リスト

リソース	説明	パラメータ
/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	プロジェクトユーザーを表示

Example

CODE

$ 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が割り当てられていることがわかります

CODE

$ 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 /project)

新規プロジェクトを作成するには、いくつかの特別なパラメータが必要です。これは、新しいプロジェクトを作成するときに提供する最小限のデータです

パラメータ	説明
new_db	1なら新規データベース作成、0なら既存データベースへのプロジェクト追加
new_db_template	新規にデータベースを作成する場合は、テンプレートとして使用するデータベース名を入力してください。
new_db_name	新しいデータベースを作成する場合は、新しいデータベースの名前を指定します。
existing_db_name	新しいデータベースを作成しない場合 (new_db set to 0)、新しいプロジェクトを追加する既存のデータベースの名前を入力します。
name	プロジェクト名
constructor	新規プロジェクトの建設者/会社名
description	プロジェクトの内容
owner_id	所有者のID
project_type_id	プロジェクトの種類。以下の値のいずれかを使用します。 ID│ 名称 ─┼──────────────────── 1 │ 稼働中のプロジェクト 2 │ 非稼働中のプロジェクト 3 │ デモ 4 │ コピー / バックアップ 5 │ テンプレート 6 │ サンドボックス / テスト 7 │ トレーニング 8 │ 体験版(トライアル)

すべてのパラメータは必須です。

例

CODE

{
  "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)

CODE

$ 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"}}

Wherer data.json contains

CODE

{
  "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

スーパーユーザー. プロジェクト管理者

addon_admin: BIM 管理者

no_web_admin_access: ユーザーがスーパーユーザーの場合、ウェブ管理者へのアクセスを拒否します。

user

username: 追加するユーザーのユーザー名

first_name: 追加するユーザーの名前

last_name: 追加するユーザーの姓

email: 追加するユーザーのEメール

ユーザーが存在する場合、与えられた情報がサーバーに登録された情報と同じであることを確認する。

mail_type

ユーザーに送信するメールのID (/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	ユーザーが多要素認証を使用してログインする必要があるかどうかを切り替えます。
POST /users/[username]/toggle_force_weblogin	ユーザーがモダンログイン/SSOを使用してログインする必要があるかどうかを切り替えます。

POSTリソース : 切り替えとその他の変更

ユーザー

Resource
/users/[username]/toggle_otp	ユーザーが多要素認証を使用してログインする必要があるかどうかを切り替えます。
/users/[username]/toggle_force_weblogin	ユーザーがモダンログイン/SSOを使用してログインする必要があるかどうかを切り替えます。

PUT/PATCH リソース:アップデート

リソース
/projects/[id]	プロジェクトの更新
/project_users/username,projectid	プロジェクトユーザーの更新

Example 1: Update project

CODE

$ 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が含まれる場所

CODE

{
  "project": {
    "name": "REST TEST",
    "description": "TEST UPDATE FROM REST",
	"active":true
  }
}

例2：プロジェクトユーザーの更新

CODE

$ 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が含まれる場所

CODE

{
  "project_user":{
	"username":"test",
	"project_id":647,
	"room_rights":1,
	"equipment_rights":3,
	"tender_rights":4,
	"room_surface_treatment_rights":4
  }
}

リソースを削除

また、削除操作を使用して、ほとんどのオブジェクトを削除することもできます。

この例では、プロジェクト内のユーザーを削除します

CODE

curl -H "Accept: application/json" -s -u http://[admin-url]/project_users/[username],[project_id] -X DELETE

パスワードの再設定

この本文と正しいユーザー名を使用して “/ password/request_reset” にJSONリクエストを投稿すると、パスワードのリセットプロセスが開始されます。ユーザーは、トークンを含む電子メールでパスワードリセット要求を受け取ります:

CODE

// Post to {server}/password/request_reset
{
	"username": "user"
}

実際にパスワードを変更するには、メールに記載されたトークンを使って、以下のjsonを使用します :

CODE

// Post to {server}/password/reset
{
	"token": "5f2pi2zW7wO3nodwWznmDQ",
	"password": "pass",
	"password_confirm": "pass"
}

プロジェクト統計

Resource	コメント
/project_data	時間の経過に伴うプロジェクトの統計を表示。
/project_data/latest	各プロジェクトの最新のプロジェクト統計が表示。

フィルター


from_date=[date]	/project_dataの場合のみ、指定した日付よりも時間が長いデータのみが表示
field=[field]	特定のフィールドのみ
owner=[owner_id]	特定の所有者IDのみ

出力例

CODE

{
"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"
},