V2. dRofus REST API 概要
- Midori Kajitani
このドキュメントは、dRofus REST API を使用して、特定のデータベースからデータを取得するための参考資料を示すものです。
データベース管理 REST API については、こちらを参照してください： 管理システム REST API
このAPIは、APIを記述したOpen API 仕様を提供しています。また、このAPIを探索し、ブラウザ上で試すことができる
インタラクティブなGUIも用意しています。データベース/プロジェクト特有のプロパティを取得する方法を公開し、
文書化しているため、文書を参照するにはログインする必要があります。下記の認証を参照してください。
フィードバックを提供
APIをどのような用途でお使いになりたいか、ご遠慮なくお問い合わせください。
URLS
APIは現在、以下の場所に配備されています。今後も増える予定です。APIドキュメントはプロジェクト特有のプロパティを
公開するので、それを見るにはログインする必要があります。 dRofusのユーザー名とパスワードを使用して、
接続する方法については、以下の、dRofus REST API#認証 のセクションをご参照ください。
URL | Swagger Gui | Swagger JSON | 備考 |
|---|---|---|---|
https://api-no.drofus.com | db2.nosyko.no のプロジェクトで使用。 | ||
https://api-eu.drofus.com |
| ||
https://api-ca.drofus.com |
| ||
https://api-us.drofus.com |
| ||
https://api-au.drofus.com/ |
|
認証
ベアラ
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) で送信する必要があります。
Authorization: Reference <API-key>
多くのクライアントは、認証ヘッダー（Excel やブラウザのアドレス バーへの URL の貼り付けなど）の設定を許可していませんが、サーバーが "Unauthorized" を送信すると
ユーザー名とパスワードの入力を求められることに注意してください。このようなプロンプトは、Basic スキームを使用した認証ヘッダーを使用してリクエストを送信します。
そこでフォールバックとして、アプリケーションも、ベーシック・スキームで認証ヘッダーとしてエンコードされたAPI-keyを受け入れ、
ユーザー名は定数のapikey パスワードはAPI-keyになります。したがって、ワイヤーのフォーマットは以下のようになります：
Authorization: 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で指定することができます。 | $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。返されるデータよりも多くのデータが利用可能な場合、 | $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の使用例です：