お手元のデータで実際の動きを確認したい場合は、無料評価版をお試しください。


現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。

注意:Yellowfin 本社の提供するサイト(英語)へリンクします。


主要な概念

REST APIは、/api ネームスペース配下で利用できます。例:https://yellowfin.myapp.com/api/stories

このスイートには、/api/rpc ネームスペースにある、RPCの呼び出しも含まれます。

すべてのAPIリクエストには、認証ヘッダーが必要です。形式は、以下の通りです。

YELLOWFIN ts=1600224140615 nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf token=securityToken

要素説明
YELLOWFINカスタム認証スキーマ
ts1970年1月1日午前0時0分0秒(UTC)であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。
nonceクライアントにより生成されるランダムUUID
tokenユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン


すべてのAPIリクエストには、Accept ヘッダーが必要です。

  • このヘッダーは、APIのバージョンを識別するために使用されます。
  • その形式は、各endpointのAPIドキュメントで指定されています。通常は次の通りです。application/vnd.yellowfin.api-v1+json
  • APIは下位互換性があります。v1リソースのリクエストは、Yellowfin インスタンスの現在のAPIバージョンがv2でも動作します。

APIを利用するためのキーとなるセキュリティトークンが2つあります。

トークン説明
リフレッシュこれは、ログイン時に取得される不透明なセキュリティトークンです。リフレッシュトークンは有効期限がなく、アクセストークンを取得するためクライアントアプリケーションに安全に保存される場合があります。
アクセスこれはJSON Web Token (JWT)で、20分で有効期限が切れます。アクセストークンは、ほぼすべてのAPIリクエストの認証ヘッダーで送信される必要があります。有効期限が切れると、クライアントアプリケーションは、リフレッシュトークンを使用して、新しいアクセストークンを取得することができます。



すべてのAPIリソースは、ひとつ以上の「_links」オブジェクトを持ちます。

  • すべてのリンクは、ユーザーがアクセスできる関連リソースを表します。
  • クライアントは、アプリケーションコードでハードコーディングするのではなく、href属性のリンクを使用して、リソースにアクセスします。
  • 「options」配列は、ユーザーがリンクの使用を許可されているHTTPメソッドを示します。例えば、下の例では、ユーザーはコメントリストを読むことができる(GET)、または新しいコメントを作成できる(POST)ことを示しています。すべてのコメントを削除することはできないため、「comments」リンクでDELETEを利用できません。


APIの使用

REST APIの呼び出しは、以下のカテゴリーにグループ化されることがあります。

  1. ログイン - 新しいリフレッシュトークンを作成します。
  2. アクセストークン - ユーザーにREST APIリソースへのアクセスを許可するために使用します。
  3. ログアウト - リフレッシュトークンを削除します。
  4. リソースのリクエスト - REST APIを使用して、実際にデータを取得します。


ログイン(リフレッシュトークンの作成)

セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST endpointを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。

  1. HTTP操作はPOSTを使用します。どのようなリソースを作成するリクエストでも、常にPOST操作を使用します。これにより、リフレッシュトークンが作成されます。



  2. リフレッシュトークンendpointのURLを使用します。有効なURLは常に名前(例:http://yellowfin.myapp.com/api/...)または、IPアドレス(例:http://127.0.0.1/api/…)のいずれかを持ちます。ポートが指定されている場合もあります(http://yellowfin.myapp.com:8080/api/...)。



  3. 必須のリクエストヘッダーをいくつか設定する必要があります。APIリクエストを行うために必要なヘッダーの完全な一覧については、こちらを参照してください。



  4. リクエスト本文には、ユーザー名とパスワードのJSON表現が含まれます。本文が生JSONとして送信されていることを確認してください。



    このリクエストの応答には、新しく作成されたリフレッシュトークンと、_embedded プロパティ配下にあるアクセストークンが含まれます。


クライアントアプリケーションは、これらのトークンを安全に保存しなくてはいけません。ログアウトに必要になるため、「self」リンクも保存します。


アクセストークン

アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。

  • HTTP操作にPOSTを選択します。
  • アクセストークンendpointのURLを使用します。
  • リフレッシュトークンリクエストと同様のヘッダーを使用します。
    • 認証ヘッダーは、リフレッシュトークンを「token」という名前のプロパティで指定しなくてはいけません。

リフレッシュトークンの応答はアクセストークンを提供し、ログイン後にAPIの利用を開始しやすくします。


ログアウト(リフレッシュトークンの削除)

POST /refresh-tokens リクエストの応答には、REST APIから効果的に「ログアウト」するために必要な情報、つまりリフレッシュトークンを削除するために必要な情報が含まれています。POST /refresh-tokens リクエストの応答には、_links プロパティが含まれています。


「self」リンクのオプション配列には、新しいリフレッシュトークンで実行できる操作が表示されます。DELETEはひとつだけ必要です。DELETE /refresh-tokensを呼び出すと、REST APIから効果的にユーザーをログアウトさせます。

この操作を実行するには、有効なアクセストークンが必要です。これは、認証ヘッダーのtokenプロパティに含まれていなくてはいけません。


リソースのリクエスト

リソースのリクエストをするには、API クライアントに有効なアクセストークンが必要です。各endpointに指定する必要のあるヘッダー、必須およびオプションパラメーターについては、APIドキュメントを参照してください。



Web SSO

APIの一般的な使用例は、Web SSOです。ログイントークンの生成には、2つのAPI endpointを使用できます。生成されたトークンを使用して、Yellowfinのブラウザインターフェースにログインできます。これを行う最も簡単な方法は、RPC endpoint POST / longin-tokens/create-sso-tokenを使用することです。

  • HTTPメソッドをPOSTに、URLを/login-tokens/create-sso-tokenに設定します。
  • 必要なヘッダーを設定します。


  • リクエスト本文は、生JSONに設定します。



  • 応答にはログイントークンと、セッションを終了するためのAPI endpointが含まれます。



  • Yellowfin Web UI、またはJavaScript APIにログインするために、トークンが使用される場合があります。詳細は、こちらを参照してください。



トラブルシューティング

  • クロックスキュー - 最も一般的に発生するエラーのひとつです。これは、認証ヘッダーのタイムスタンプが、サーバ時刻と同期していないために発生します。±5分の許容値がありますが、この範囲を外れると、APIはエラーで応答します。



  • トークンの有効期限切れ - 有効期限の切れたアクセストークンを使用すると、APIはエラーで応答します。



  • 認証の失敗 - 無効なユーザー名、またはパスワードを使用すると発生します。



  • 不明なバージョン - Accept ヘッダーに誤ったAPIバージョンを指定すると発生します。



  • ライセンスエラー - GET /stories/uuidのようなコンテンツサービスは、サーバライセンスが存在する場合のみ利用できます。そうではない場合、APIは401 Unauthorized errorを返します。



  • CORS - CORSはブラウザにのみ適用されるため、一般的にREST APIにとって問題にはなりません。トークンの安全な保存が容易ではないため、Webブラウザは推奨されるREST クライアントではありません。

  • SSO エラー - 資格情報とOrg Referenceが正しいことを確認します。noPassword認証を使用している場合は、サーバ側で有効になっていることを確認します。これは、システム構成テーブルにレコードを挿入し、Yellowfinを再起動することで実行します。

    INSERT INTO Configuration values (1, 'SYSTEM', 'SIMPLE_AUTHENTICATION', 'TRUE');



  • Error 500 Internal Server Error - これは、サーバ上で何か問題が発生したことを示す一般的なエラーメッセージです。詳細については、サーバログにあるエラートレースをサポートに連絡してください。



現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。

注意:Yellowfin 本社の提供するサイト(英語)へリンクします。



  • No labels