RESTAPIは、他のアプリケーションが直接にBellaDatiによって提供されたデータにアクセスすることを可能にし、モバイルBusiness Intelligence BellaDati Mobileの基礎となるインタフェースです。 APIを介して、ユーザーが独自のカスタム・クライアント・アプリケーションと統合するためレポート、チャート、全体のダッシュボードを取得できます。
一般的な備考
REST APIを有効にします
APIにアクセスする前に、あなたのドメインの設定でそれを有効にする必要があります。
- ドメインの設定ページを開きます。このページに遷移するため、右上にある自分の名前の上にマウスを移動し、ドメインのリンクをクリックしてください。
- OAuth Settingsの下にConfigureをクリックします
- Consumer KeyとConsumer Secretを入力します。今、他の設定を無視することができます。
基本的なURL
REST APIにアクセスするための基本的なアドレスはhttps://service.belladati.com/api/です。
もしオンプレミス展開を使用している場合は、https://your-server/belladati/api/になります。
SSLのみ
BellaDatiクラウドサービスへのすべてのAPIリクエストは、SSL経由で送信する必要があります。
オンプレミス展開では必須ではありませんが、セキュリティ用SSLを使用することを強くお勧めます。
UTF-8エンコーディング
BellaDati REST APIへのすべての文字列はUTF8でエンコードする必要があります。最大の互換性のために、UTF-8エンコーディングの前にUnicodeのUnicode C 正規化(NFC)に正規化します。
ロケール
BellDati RESTAPIは、コンテンツレスポンスの言語設定を指定するためロケールパラメータを使用しています。あなたが英語以外の言語でデータを取得したい場合は、適切なIETF言語タグを挿入します。サポートされている言語が指定されている場合、BellaDatiはコンテンツを翻訳返されます。
レスポンスフォーマット
BellaDati REST APIは、API呼び出しへのレスポンスにJSONフォーマットを使用しています。また、いくつかのレスポンスが映像のためにHTMLとPNG形式を返すことができます。
Error Handling
エラーは、標準HTTPエラーコードの構文を使用して返却される。任意の追加情報はJSONフォーマットで返却コールの本体に含まれます。ここに記載されていないエラー・コードは、それぞれのREST APIメソッドに記述されます。
標準API HTTPエラーは
コード | 説明 |
---|---|
400 | 不正なインポートパラメータ。その理由を見つけるためにエラー・メッセージを参照してください。 |
401 | 不良または有効期限が切れたトークン。これは、アクセストークンの有効期限が切れているまたは無効でいる場合に発生する可能です。この問題を解決するには、ユーザーを再認証してください。 |
403 | 不良OAuthリクエスト(間違ったコンシューマキー、不良ナンス、期限切れのタイムスタンプなど)。詳細については、エラー・メッセージを参照してください。 |
404 | ファイルまたはフォルダが指定されたパスに見つからない。あなたがアクセスしようとしているURLが正しいかどうかを確認してください。 |
405 | 予期しないリクエストメソッド。リクエストメソッドは作るしようとしているの要求に応じてGETするかPOSTになる。 |
503 | アプリが多くの要求を作成すると速度が制限されます。 503sにアプリまたはユーザーごとにトリガすることができます。 |
5xx | サーバーエラー。詳細については、エラー・メッセージを参照してください。 |
アプリケーションのランタイムエラーは、次のとおりです。
コード | 説明 |
---|---|
request_token_unauthorized | 合格したリクエストトークンが不正となって、使用できません。新しいリクエストトークンを作成します。 |
request_token_rejected | リクエストトークンが検証に不合格。間違ったフォーマットまたは破損しているかもしれません。。 |
access_token_already_issued | アクセストークンはすでに合格したリクエストトークンのために発行されました。 |
invalid_consumer | コンシューマキーが見つからないまたは要求に存在していませんでした。ドメインの設定とログファイルを確認してください。 |
request_token_not_found | アクセストークンのためにそれを交換するときにリクエストトークンが存在しないまたは見られません。 |
token_not_found | アクセストークンは存在していないまたは要求には見られない。これは、要求の整合性とコンシューマキーなどの他の前提条件が満たされていまるという意味です。 |
token_unauthorized | 合格したアクセストークンは、不正とになって、使用できません。新しいリクエストトークンを作成します。 |
parameter_absent | 必須パラメータは、リクエストには存在しません。 |
user_not_found | xAuth リクエスト(x_auth_username)で合格したユーザーパスが見つかりませんでした。 |
too_many_login_failures | xAuthを使用している時に組み合わせにユーザ/パスワード失敗になったログインが多すぎてあります。 |
user_login_failed | 組み合わせユーザー/パスワードがxAuthを使用している時に有効になりません。。 |
user_not_active | xAuthを使用するときに、合格したユーザーがアクティブになりません。 |
user_expired | xAuthを使用するときに合格したユーザーアカウントがアクティブになりません。 |
no_domain | ユーザーがドメインに連結していません。 |
domain_expired | xAuthを使用している時にユーザーのドメインの有効期限が切れています。 |
api_disabled | REST APIはライセンスキーで有効になりません。 |
次のステップ
REST APIは、他のアプリケーションがBellaDatiが提供するデータに直接アクセスすることを可能にし、当社のモバイルビジネス・インテリジェンスBellaDati Mobileの基礎となるインターフェースとなっています。APIを通じて、ユーザーはレポート、チャート、そしてダッシュボード全体を取得し、独自のカスタムクライアントアプリケーションと統合することができます。
General Notes
Enable REST API
REST APIにアクセスする前に、ドメインの設定でREST APIを有効にする必要があります。
- ドメインの設定ページを開きます。このページを開くには、右上のお客様の名前の上にマウスを移動し、ドメインのリンクをクリックします。
- OAuth SettingsでConfigure をクリックします。
- Consumer Key と Consumer Secretを入力します。その他の設定は当面省略してかまいません。
Base URL
REST APIにアクセスするためのベースアドレスは https://service.belladati.com/api/
.
オンプレミスのデプロイメントを使用している場合は https://your-server/belladati/api/
.
SSL Only
BellaDatiクラウドサービスへのAPIリクエストは、全てSSLで送信される必要があります。
オンプレミスの場合、必須ではありませんが、セキュリティ上の理由からSSLを使用することを強く推奨します。
UTF-8 Encoding
BellaDati REST APIとやり取りする文字列は、すべてUTF-8でエンコードする必要があります。最大限の互換性を保つために、UTF-8エンコードの前にUnicode Normalization Form C (NFC)に正規化してください。
Locale
BellDati REST APIは、コンテンツレスポンスの言語設定を指定するためにlocaleパラメータを使用します。英語以外の言語でデータを取得したい場合は、適切なIETF言語タグを挿入してください。サポートされる言語が指定された場合、BellaDatiは該当する場合、翻訳されたコンテンツを返します。
Response Format
ellaDati REST APIは、APIコールの応答にJSON形式を使用します。また、一部のレスポンスでは、HTMLやPNG形式の画像を返すことがあります。
Error Handling
エラーは、標準的なHTTPエラーコードの構文で返されます。追加情報は、JSON形式のリターンコールのボディに含まれます。ここに記載されていないエラーコードは、それぞれのREST APIメソッドに記載されています。
標準的なAPIのHTTPエラーは以下の通りです:
Code | Description |
---|---|
400 | 入力パラメータに問題があります。エラーメッセージを参照し、どのパラメータが原因かを確認してください。 |
401 | 不正なトークン、または期限切れのトークンです。アクセストークンの有効期限が切れているなど、無効な場合に発生する可能性があります。この問題を解決するには、ユーザーを再認証してください。 |
403 | OAuth リクエストが不正です(不正なコンシューマーキー、不正な nonce、期限切れのタイムスタンプ...)。詳細は、エラーメッセージを参照してください。 |
404 | 指定されたパスにファイルまたはフォルダが見つかりませんでした。アクセスしようとしているURLが正しいかどうか確認してください。 |
405 | 予期しないリクエストメソッドです。取得しようとしているリクエストに応じて、リクエストメソッドはGETまたはPOSTであるべきです。 |
503 | アプリのリクエスト数が多すぎるため、レート制限を受けています。503は、アプリごと、またはユーザーごとに発生する可能性があります。 |
5xx | サーバーのエラーです。詳細はエラーメッセージを参照してください。 |
Application runtime errors are:
Code | Description |
---|---|
request_token_unauthorized | 受け取ったリクエスト・トークンは不正に使用されたため、使用できません。新しいリクエスト・トークンを作成してください。 |
request_token_rejected | リクエスト・トークンがバリデーションに失敗しました。間違った形式か破損している可能性があります。 |
access_token_already_issued | 受け取ったリクエスト・トークンに対応するアクセストークンがすでに発行されています。 |
invalid_consumer | コンシューマーキーが見つからないか、リクエストに存在しない。ドメイン設定とログファイルを確認してください。 |
request_token_not_found | アクセストークンに交換しようとしましたが、リクエストトークンが存在しないか、見つかりませんでした。 |
token_not_found | アクセストークンが存在しないか、リクエストの中に見つかりませんでした。この場合、リクエストの整合性やコンシューマキーのような他の前提条件が満たされていることを意味する場合があります。 |
token_unauthorized | 受け取ったアクセストークンは不正に使用されたため、使用できません。新しいリクエスト・トークンを作成してください。 |
parameter_absent | 必須パラメータがリクエストに存在しません。 |
user_not_found | xAuthリクエストで渡されたユーザー(x_auth_username)が見つかりませんでした。 |
too_many_login_failures | xAuth使用時に、ユーザーとパスワードの組み合わせでログインに失敗することが多すぎます。 |
user_login_failed | xAuthを使用する際、ユーザーとパスワードの組み合わせが有効ではありません。 |
user_not_active | xAuthを使用している間、パスしたユーザはアクティブではありません。 |
user_expired | xAuthを使用している間、渡されたユーザーアカウントはアクティブではありません。 |
no_domain | ユーザーがドメインと関連付けられていません。 |
domain_expired | xAuthの使用中にユーザードメインの有効期限が切れています。 |
api_disabled | ライセンスキーでREST APIが有効になっていません。 |