| Anchor | ||||
|---|---|---|---|---|
|
| Table of Contents | ||
|---|---|---|
|
| Info |
|---|
現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。 注意：Yellowfin 本社の提供するサイト（英語）へリンクします。注意: Yellowfin 本社の提供するサイト (英語) へリンクします。 |
概要
Yellowfinは、一般的なREST APIを公開することで、外部の開発者は独自のユーティリティやアプリケーションを作成したり、Yellowfinのシステムやコンテンツと統合したりすることができます。これは、JS API、SOAP API、完全アプリケーション統合などの既存の統合と並行して、または完全にスタンドアローンの統合ツールとして機能します。
このAPIは、ストーリー、シグナル、ディスカッションストリーム、レポート (近日公開予定) 、ユーザー、ユーザータイムラインなど、いくつかの主要なコンテンツタイプの大部分の機能を公開します。また、ユーザー管理、カテゴリー管理、インポートこのAPIは、レポート、ダッシュボード、プレゼンテーション、ストーリー、シグナル、ディスカッションストリーム、ユーザー、ユーザータイムラインなど、すべての主要なコンテンツタイプの機能を公開します。また、ユーザー管理、カテゴリー管理、インポート/エクスポート、システム構成、ユーザーセッション管理などの機能を提供する管理機能も備えているため、開発者は独自のユーティリティを使用して、Yellowfinシステムを管理および制御できます。
...
YELLOWFIN ts=1600224140615, nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf, token=securityToken
| 要素 | 説明 |
| YELLOWFIN | カスタム認証スキーマ このテキストは、アプリケーション名と一致する必要があります。これは、カスタムインストーラープロパティファイル、またはYellowfin構成データベースを使用して設定できます。 注意：テキストはスペースを入れずに大文字で記述する必要があります。例えば、アプリケーション名が「YELLOWFIN」ではなく「BigFishReporting」の場合、認証スキーマは「BIGFISHREPORTING」と記述する必要があります。 |
| ts | 1970年1月1日午前0時0分0秒（UTC）であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。 |
| nonce | クライアントにより生成されるランダムUUID |
| token | ユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン。 一部のエンドポイントは認証なしでアクセスできるため、すべてのエンドポイントがこの項目を必要とするわけではありません (詳細はこちらを参照してください)。 |
...
一部のAPIレスポンスは「_embedded」オブジェクトを持ちます。このオブジェクトには、現在のリソースに関連する追加の有用な情報を含むサブオブジェクトを含めることができますが、そのリソースには直接属しません。これらは、独自のプロパティとリンクを持つ個別のリソースです。
...
認証
APIの大部分のエンドポイントでは認証が必要です。主な例外は、次の通りです。
- base /apiリソース。これは、apiコンシューマーアプリケーションによって一般的に使用され、基本api情報を取得するために、認証の有無にかかわらず使用できます。
- 要求された資格情報がリクエストの一部として渡される独自のインライン認証を提供する一部のエンドポイント (より詳細な情報は、REST API ドキュメントを参照してください)。
ログイン
REST APIは、リフレッシュトークンおよびアクセストークンを使用して、リソースへのアクセスを認証および許可します。これらのトークンは、いくつかの異なる方法で生成することができます。
標準的なログイン
標準的なログインフローは、リフレッシュトークンの認証と生成のために、サーバーにユーザーの資格情報を渡します。また、利便性のためにアクセストークンも渡します。リフレッシュトークンはその後アクセストークンを作成するために使用し、その他のリソースへのアクセスに使用することができます。
セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST エンドポイントを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。
...
| Note |
|---|
クライアントアプリケーションは、これらのトークンを安全に保存しなくてはいけません。ログアウトに必要になるため、「self」リンクも保存します。 |
シングルサインオン
このAPIは、REST API自体にシングルサインオン (SSO) 機能を提供します。これにより、RESTユーザーは別のRESTユーザーにログオンし、そのユーザーのリフレッシュトークンを生成できます。リフレッシュトークンは、そのユーザー (または、他のアプリケーション) に転送して、APIの使用を許可することができます。このエンドポイントは、SSOリクエストを行っているRESTユーザーのインライン認証をサポートし、単純な認証をサポートします (SSOでのnoPassword SSOエラーについては、下記のトラブルシューティング項目を参照してください)。
オンボーディング
これは基本的に、Web アプリケーションから実行できる別の形式のSSOです。管理者は、特定のユーザー用のオンボーディングトークンを生成して外部アプリケーションに渡すことで、外部アプリケーションは、ユーザーの資格情報を使用してリフレッシュトークンを生成する代わりに、そのトークンを認証フローに渡すことができます。トークンがリフレッシュトークンのPOSTリクエストとともに渡された場合 (これは、上記通常のREST SSOリクエストではありません) 、このトークンは、Web アプリケーションで作成されたトークンと照合され、ユーザーをログオンさせます。
Web SSO
Web アプリケーションとJavaScript APIの両方で、シングルサインオンを処理するために異なるトークンシステムを使用します。つまり、これらのトークンを相互に使用することはできません。幸いなことに、REST APIには、必要なWeb SSOトークン (REST APIではログイントークンと呼ばれます) を生成する方法がいくつか用意されています。これらのトークンを生成する主な方法は、以下の3つです。
...
APIの一般的な使用例は、Web SSOです。ログイントークンの生成には、2つのAPI エンドポイントを使用できます。生成されたトークンを使用して、Yellowfinのブラウザインターフェースにログインできます。これを行う最も簡単な方法は、RPC エンドポイント POST / longin-tokens/create-sso-tokenを使用することです。
- HTTPメソッドをPOSTに、URLを/login-tokens/create-sso-tokenに設定します。
- 必要なヘッダーを設定します。
...
アクセストークン
アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。
- HTTP操作にPOSTを選択します。
- アクセストークンエンドポイントのURLを使用します。
- リフレッシュトークンリクエストと同様のヘッダーを使用します。
- 認証ヘッダーは、リフレッシュトークンを「token」という名前のプロパティで指定しなくてはいけません。
リフレッシュトークンのレスポンスはアクセストークンを提供し、ログイン後にAPIの利用を開始しやすくします。
...
リフレッシュトークンが生成されるログオンフローも、同じ方法でログアウトできます。シングルログオフ (SLO: Single Log-off) は、現在ログインしているユーザーにその権限がある限り、/refresh-tokens エンドポイントによって削除される別のユーザーのトークンIDを渡すことで実現できます。
また、(ログイントークンの作成時に返される) トークンIDを、/login-tokens DELETE エンドポイントに渡すことによって、Web SSOセッションをSLOすることもできます。同じアクセス制限が適用されます。
POST/refresh-tokens リクエストのレスポンスには、REST APIから効果的に「ログアウト」するために必要な情報、つまりリフレッシュトークンを削除するために必要な情報が含まれています。POST/refresh-tokens リクエストのレスポンスには、_links プロパティが含まれています。
「self」リンクのオプション配列には、新しいリフレッシュトークンで実行できる操作が表示されます。DELETEのみが表示されるはずです。DELETE/refresh-tokensを呼び出すと、REST APIから効果的にユーザーをログアウトさせます。
この操作を実行するには、有効なアクセストークンが必要です。これは、認証ヘッダーのtokenプロパティに含まれていなくてはいけません。
リソースへのアクセス
各エンドポイントに指定する必要のあるヘッダー、必須およびオプションパラメーターについては、APIドキュメントを参照してください。
Base API リソース
このエンドポイントは、標準RESTリソースとして表されるAPI自体の現在の状態を示します。これは、ログインしているユーザーとログインしていないユーザーの両方が使用できるため、アクセストークンの有無にかかわらずアクセスできます。これは、現在のAPIバージョンなどのAPI情報、現在のアプリケーションバージョンなどのサーバ情報を返します (以下の注意を参照してください) 。エンドポイントは、現在のユーザーが使用できるすべての最上位レベルのリソースも返します (ログインしているユーザーがいない場合は、ログインしていないユーザーがアクセスできる最上位のエンドポイントを返します)。
| Info |
|---|
同じRESTバージョンのアプリケーションバージョン間で使用可能なエンドポイントが異なる場合があるため、APIバージョンと同様にこの値に注意することが重要です。 |
標準リソース
ほとんどすべての標準リソースは、アクセストークン認証を必要とし、大部分はJSONとして表現されます (エンドポイントの詳細については、REST APIドキュメントを参照してください) 。これらは通常、標準構造を共有し、オブジェクトのプロパティ、ナビゲーション用の_linksおよび_embeddedプロパティ、その他の有用な情報を持ちます。
大部分のリストエンドポイントは、JSONでシリアライズされたオブジェクトを使用してエンドポイントにフィルタリング情報を渡すフィルタリングシステムを実装しています。これらのエンドポイントには、通常、現在のユーザーが使用できるフィルター値を示す直接の子/metadata リソースも付随します。各エンドポイントのより詳細な情報については、REST APIドキュメントを参照してください。
APIレスポンスで返されるモデルフィールドを制御できるフィールドパラメーターを提供するエンドポイントがいくつかあります。これらは、含める必要があるプロパティ名のシリアル化されたJSONリストとして送信されます。この機能は、すべてのエンドポイントで均一に実装されているわけではなく、すべてのフィールドをすべてのエンドポイントで除外できるわけではありません。各エンドポイントについて、より詳細な情報は、REST APIのドキュメントを参照してください。
RPC リソース
RPC (Remote Procedure Call: リモートプロシージャコール) エンドポイントは、認証 (一部のRPC エンドポイントはインライン認証を備えています。詳細は、REST API ドキュメント参照) およびレスポンス構造の同じルールに従いますが、REST パラダイムには従わないという点で、標準リソースエンドポイントに類似しています。これらは、リソースを直接表すのではなく、サーバー上で実行されるプロシージャを表します。すべてのRPCエンドポイントは、POST操作を使用します。
これらが存在する理由は、ステートフルな相互作用を必要とするエンドポイントや、複雑なマルチリクエスト呼び出し構造など、RESTパラダイムに適合するのが非常に難しい機能を実装しているからです。これらは通常、既存のSOAPサービスまたはWeb アプリケーションインタフェースから移行された機能であり、明確にリファクタリングすることは非常に困難です。これらの機能の一部は、将来完全なRESTful実装に変換される可能性があります。
リクエストボディパラメーター
使用可能なPOST操作を持つほとんどのエンドポイントは、追加のパラメーターを必要としないほど単純でない限り、リクエストボディにパラメーターを渡す必要があります。必要とされるリクエストボディの形式が異なるのは、主に次2つの状況です。
- application/form-dataを必要とするリクエストは、通常、何らかのファイルアップロードを必要とするリクエストです。つまり、ボディはform-dataとして渡され、正しいエンコーディングを使用する必要があります。ファイルアップロードパラメーターを参照しないサブオブジェクトは、form-data内で生のJSONとしてエンコードする必要があります。
- ファイルアップロードパラメーターを持たない他のすべてのリクエストは、リクエストボディで生のJSONを使用します。
各エンドポイントの正確な要件については、REST API ドキュメントを参照してください。
ログインフローの例
一般的に、APIのほとんどの使用例では、REST APIへのログインと同様のアプローチに従う必要があります。このアプローチは、REST APIへの初期接続およびユーザーログインを構成します。ユーザーまたは管理者による強制ログアウトによってトークンが無効化されない限り、後続の接続で別のリフレッシュトークンを生成する必要はありません。一部のサーバーより上位の機能をサポートするアプリケーションの場合は、セッション間でサーバーのバージョンが変更されていないことを確認することを推奨します。
- APIのバージョンについてサーバーをプローブします。
- これは、base/api エンドポイントにGETリクエストを行うことで実現できます (詳細は、Base API リソース項目を参照してください) 。ここで返される結果は、サーバのAPIバージョンおよびアプリケーションバージョンを決定します。これにより、API使用者は、サーバのサポートされているバージョン範囲内にあるサポートされているバージョンを使用して対話できます。
- base/api エンドポイントは、バージョン1.0と1.1には存在しなかったことに注意してください。バージョン1.0と1.1は本質的に同一であり、ほぼ100%の互換性があります (相違点については、各バージョンのドキュメントを参照してください) 。そのため、このエンドポイントから404応答を受け取ることは、サーバーはこれらのバージョンのいずれかを実行していることを示し、v1にフォールバックすると、v1.1からの非常にマイナーな変更を除いて、すべてのケースで動作することになります。
- 利用可能ないずれかの方法でリフレッシュトークンを生成します（詳細は、ログイン項目を参照してください）。
- リフレッシュトークンレスポンスから自動的に生成されたアクセストークンを使用するか、必要に応じて独自のアクセストークンを作成してください（しばらくアクティビティがなかった場合、生成されたアクセストークンは期限切れになることがあります）。
- これで、アクセストークンを使って、この種のトークンを必要とするすべてのAPIリソースにアクセスできるようになります。
トラブルシューティング
...
- Error 500 Internal Server Error - これは、サーバ上で何か問題が発生したことを示す一般的なエラーメッセージです。詳細については、サーバログにあるエラートレースをサポートに連絡してください。
現在利用可能なREST サービスの詳細については、開発者サイトをご確認ください。
...