.png)
dRofus REST APIの概要
このドキュメントは、指定したデータベースのデータに対して dRofus REST API を使用するための参考資料をまとめたものです。
データベース管理REST APIについては、以下をご参照ください：管理システム REST API
このAPIは、APIを説明した OpenAPI 仕様 を提供しています。また、このAPIを探索し、ブラウザで試すことができる対話型GUIも用意しています。
データベース/プロジェクト固有のプロパティを取得する方法を公開し、ドキュメント化しているため、ドキュメントを参照するにはログインが必要です。下記の認証をご参照ください。
フィードバックを提供します
APIを使用したい使用例について、お気軽にお問い合わせください。
URLS
APIは現在、以下の場所にデプロイされています。今後も続く予定です。API ドキュメントではプロジェクト固有のプロパティが公開されるため、
そのプロパティを確認するにはログインする必要があります。dRofusのユーザー名とパスワードで接続する方法については、下記の dRofus REST API#認証 をご覧ください。
| URL | Swagger Gui | Swagger JSON | |
|---|---|---|---|
https://api-no.drofus.com | API documentation and test it in web GUI | Open API Specification | use for db2.nosyko.no projects |
https://api-eu.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-ca.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-us.drofus.com | API documentation and test it in web GUI | Open API Specification | |
| https://api-au.drofus.com/ | API documentation and test it in web GUI | Open API Specification |
認証
Bearer
APIは一般的にOAauth2標準のBearerトークンをサポートしています。OAuth2 クライアントの登録プロセスは現在手動で行っています。
必要な情報は support@drofus.com までご連絡ください。ご希望のredirect_uri(s) (および必要であればpost_logout_redirect_uri(s))をお送りください。
テスト目的では、HTTP ベーシック認証 も使用できます。ただし、本番アプリケーションでは避ける必要があります。
APIキー
APIは、"API-key "を使用したデータの読み取りをサポートしています。このアクセス・モードは、ダッシュボード、PowerQuery (Excel, PoweBI)などのアドホック・データ (ad-hoc data) および/または定期的なAPIコール (recurring API-calls)の読み取りに使用されます。
キーは、ここで説明されているように生成することができます：パワー・クエリ#3.-認証情報/ログイン 生成されたキーには、ログインしたユーザーとプロジェクトが反映されます。
APIキーを使用した場合の備考
- 読み取り操作のみをサポートします
- API キーは単一のプロジェクトに有効です。ユーザーは、異なるプロジェクトにアクセスするために複数の API キーを生成できます。
同じプロジェクトで API-Key を二度生成すると、同じキーになります。 - API キーは単一のユーザーに属し、機密であるため、共有しないでください。
- API キーはマシン間通信に使用することを意図しておらず、そのように使用すべきではありません。
テクニカルな説明
各 HTTP リクエストでは、標準の Authorization ヘッダとして API-key を Reference scheme で送信する必要があります。
認証：Reference <API-key>
多くのクライアントは、認証ヘッダー（Excel やブラウザのアドレス バーへの URL の貼り付けなど）の設定を許可していませんが、サーバーが "Unauthorized" を送信すると
ユーザー名とパスワードの入力を求められることに注意してください。このようなプロンプトは、Basic スキームを使用した認証ヘッダーを使用してリクエストを送信します。
そこでフォールバックとして、アプリケーションはBasicスキームのAuthorizationヘッダーとして、
ユーザー名が定数の apikey パスワードがAPI-keyとなるようにエンコードされたAPI-keyも受け入れます。したがって、ワイヤーのフォーマットは以下のようになります：
認証：Basic base64urlencode(apikey:<API-key>)
これはあくまでも例であり、可能な限り参照スキームを使用することを推奨します。
クライアントがリクエストヘッダを完全に制御できるのであれば、ベーシック・スキーム (Basic scheme,)でエンコードされたAPI-keyを使う必要はありません。
データベースとプロジェクトIDの提供
すべてのAPIエンドポイントは、URLのパスの一部としてデータベースとプロジェクト番号を提供する必要があります。例えば、https://api-host/api/database/projectId/resources
クエリ
現在、OData 標準のクエリ構文をモデルとしていますが、そのごく一部しかサポートしていません。
| 引数 | 説明 | 例 | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| $select | 返す列 (コラム) のカンマ区切りリスト。'id' は常に返されます。 | $select=name,architect_no | ||||||||||||||||||
| $orderby | ソートする列 (コラム)のカンマ区切りリスト。ソートの方向はascまたはdescで指定することができます。 デフォルトはasc。orderbyが指定されていない場合は、idでソートされます。 | $orderby=name,architect_no desc, | ||||||||||||||||||
| $filter | 返される行 (ロウ)を制限するために使用します。 列 (コラム) にはフィルタをかける条件を指定することができます。 操作:
| $filter=created gt '2019-1-1' $filter=name in ('kitchen', 'office') $filter=id in (1001, 1003, 1005) $filter=contains(name,'kitch') | ||||||||||||||||||
| $top | 返す行 (ロウ)の最大数。デフォルトは10000。返されるデータよりも多くのデータが利用可能な場合、 結果には RFC5988 ヘッダ値が含まれます。 | $top=123 | ||||||||||||||||||
| $skip | 結果セットでスキップする行数 (ロウ)。デフォルトは 0。 $top と組み合わせてページングを行うこともできます。 | $skip=100 |
完全なAPIドキュメント
APIはOpen API (以前はSwaggerとして知られていました) と呼ばれる標準フォーマットで記述されています。
APIの基本的な一般ドキュメントは'swagger/default/swagger.json'にあります。
ただし、データベースは機密性が高いため、データベース固有のファイルをすべてスキーマに含むバージョンは'swagger/v1/swagger.json'にありますが、ログインが必要です。
RFC5988
Rfc5988 は、結果セット内のページ間を移動するためのインターネット標準です。基本的にはこのようであり、レスポンスヘッダーに付加データの完全なリンクが含まれています：
<http://localhost/api/database/01/rooms?$skip=1&$top=1>; rel=\"next\">例
APIの使用例：