管理システム REST API
これは、RESTコール (GET, POST, PUT, PATCH, DELETE) を使用して管理システムと対話する可能性を文書化したもので、プロジェクトやユーザーの作成などのタスクの自動化を可能にします。
すべての例はcurl ユーティリティを使用して作成されています。
- 1 一般
- 2 リソース：
- 2.1 GET リソース：リスト
- 2.1.1 コードブロック
- 2.1 GET リソース：リスト
- 3 POSTリソース：オブジェクトの作成
- 3.1 例
- 3.1.1 コードブロック
- 3.2 新規プロジェクトの作成 ( POST /プロジェクト)
- 3.2.1 コードブロック
- 3.3 新規プロジェクト・ユーザーの作成 (POST /project_users)
- 3.1 例
- 4 GETリソース： オブジェクト操作など
- 5 POST リソース：トグルとその他の変更
- 5.1 ユーザー
- 6 PUT/PATCHリソース 最新情報
- 7 リソースを削除
- 7.1 コードブロック
- 8 パスワードのリセット
- 9 プロジェクトの統計
一般
認証
システムはベーシック認証を使っています。ログインには管理システムユーザーが必要で、通常の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は使用できません。代わりに必ずヘッダーに "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 | 過去5年間のプロジェクトのログイン統計を、使用したクライアントの種類 (Revit、dRofusなど) でグループ化して取得します。 |
/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でパスワードを変更するには、トークンとともにこれを使用します。 |
GET リソース：リスト
リソース | 説明 | パラメータ |
|---|---|---|
/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 /プロジェクト)
新しいプロジェクトを作成するには、いくつかの特別なパラメータが必要です。新しいプロジェクトを作成する際に、最低限必要なデータは以下の通りです。
パラメータ | 説明 |
|---|---|
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)
コードブロック
Wherer data.json contains
コードブロック
パラメータ | 説明 |
|---|---|
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: ユーザーがスーパーユーザーの場合、ウェブ管理者へのアクセスを拒否する。 hide_price: ユーザーが価格を確認する際に真または偽を指定。 |
user | username: 追加するユーザーのユーザー名。 first_name: 追加するユーザーの名前。 last_name: 追加するユーザーの姓。 email: 追加するユーザーの電子メール。 ユーザーが存在する場合、与えられた情報がサーバーに登録されている情報と同じであることを確認します。 |
mail_type | ユーザーに送信するメールのID (/emailsより)。"skip_email "はメールを送信しないことを意味します。 |
GETリソース： オブジェクト操作など
データベース
リソース | |
|---|---|
/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 リソース：トグルとその他の変更
ユーザー
リソース | |
|---|---|
/users/[username]/toggle_otp | ユーザーが多要素認証を使用してログインするかどうかを切り替えます。 |
/users/[username]/toggle_force_weblogin | モダンログイン/SSOを使用してログインするかどうかを切り替えます。 |
PUT/PATCHリソース 最新情報
リソース | |
|---|---|
/projects/[id] | プロジェクトの更新 |
/project_users/username,projectid | プロジェクトユーザーの更新 |
例1：プロジェクトの更新
コードブロック
data.jsonに含まれる内容
例 2: プロジェクトユーザーを更新
コードブロック
data.jsonに含まれる内容
コードブロック
リソースを削除
また、削除オペレーション (DELETE operation )を使用して、ほとんどのオブジェクトを削除することができます。
この例では、プロジェクト内のユーザーを削除します。
コードブロック
パスワードのリセット
この本文と正しいユーザ名を使用して "/password/request_reset" に json リクエストを投稿すると、パスワードのリセット処理が開始されます。
ユーザーには、トークン付きのパスワード再設定リクエストが電子メールで送信されます：
コードブロック
実際にパスワードを変更するには、メールに記載されたトークンを使って以下のjsonを使用します：
コードブロック
プロジェクトの統計
リソース | コメント |
|---|---|
/project_data | 長期にわたるプロジェクトの統計を提供。 |
/project_data/latest | 各プロジェクトの最新の統計情報を提供します。 |
フィルタ
from_date=[date] | project_dataに限り、時刻が指定された日付より大きいデータのみを表示する。 |
field=[field] | 特定フィールドのみ。 |
owner=[owner_id] | 特定の所有者IDのみ。 |