--- title: "REST API" canonical: "https://wiki.yellowfin.co.jp/space/yfcurrent/1903272/REST%20API" format: markdown --- > Macro (anchor) > Macro (toc) > ℹ️ 現在利用可能なREST サービスの詳細については、[開発者サイト](https://developers.yellowfinbi.com/dev/api-docs/yf-api.html)をご確認ください。 > ℹ️ > ℹ️ **注意：**Yellowfin 本社の提供するサイト（英語）へリンクします。 ## 概要 Yellowfinは、一般的なREST APIを公開することで、外部の開発者は独自のユーティリティやアプリケーションを作成したり、Yellowfinのシステムやコンテンツと統合したりすることができます。これは、JS API、SOAP API、完全アプリケーション統合などの既存の統合と並行して、または完全にスタンドアローンの統合ツールとして機能します。 このAPIは、レポート、ダッシュボード、プレゼンテーション、ストーリー、シグナル、ディスカッションストリーム、ユーザー、ユーザータイムラインなど、すべての主要なコンテンツタイプの機能を公開します。また、ユーザー管理、カテゴリー管理、インポート/エクスポート、システム構成、ユーザーセッション管理などの機能を提供する管理機能も備えているため、開発者は独自のユーティリティを使用して、Yellowfinシステムを管理および制御できます。 このAPIには、次のような用途があります。 - シグナルやその他のコンテンツを閲覧したり、表示したりするなど、Yellowfinのコンテンツをサードパーティ製アプリケーション内に統合します。また、コンテンツがどのように表示され、ユーザーがどのように対話し、移動するかを制御することができます。 - Web インターフェースにログインすることなく、Yellowfin インスタンスの構成や設定を管理できるサードパーティ製アプリケーションなどの管理ユーティリティを作成します。 - Yellowfin アプリケーションユーザーインタフェースの完全にカスタマイズされた実装を構築し、開発者がアプリケーションの表示方法や操作方法を制御したり、ユーザーやその他の特定の要件に基づいて機能を制限したりできるようにします。 ## 主要な概念 REST APIは、/api ネームスペース配下で利用できます。例：https://yellowfin.myapp.com/api/stories さらに、このスイートにはRPC (Remote Procedure Call: リモートプロシージャコール) エンドポイントが含まれており、RESTパラダイムに適合するのが難しいワークフローをサポートします。これらは、/api/rpc ネームスペースに配置されています。 すべてのAPIリクエストには、**認証ヘッダー**が必要です。形式は、以下の通りです。 **YELLOWFIN ****ts=1600224140615,** **nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf,** **token=securityToken** | | | | --- | --- | | **要素** | **説明** | | **YELLOWFIN** | カスタム認証スキーマ
このテキストは、アプリケーション名と一致する必要があります。これは、[カスタムインストーラープロパティファイル](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1905109/Yellowfin#Yellowfinのシステム構成-アプリケーション名)、または[Yellowfin構成データベース](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1905271#id-管理コンソール-appname)を使用して設定できます。
**注意：**テキストはスペースを入れずに大文字で記述する必要があります。例えば、アプリケーション名が「YELLOWFIN」ではなく「BigFishReporting」の場合、認証スキーマは「BIGFISHREPORTING」と記述する必要があります。 | | **ts** | 1970年1月1日午前0時0分0秒（UTC）であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。 | | **nonce** | クライアントにより生成されるランダムUUID | | **token** | ユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン。 一部のエンドポイントは認証なしでアクセスできるため、すべてのエンドポイントがこの項目を必要とするわけではありません (詳細は[こちら](https://developers.yellowfinbi.com/dev/api-docs/current/#tag/access-tokens)を参照してください)。 | すべてのAPIリクエストには、**Accept ヘッダー**が必要です。 - このヘッダーは、APIのバージョンを識別するために使用されます。 - その形式は、各エンドポイントのAPIドキュメントで指定されています。大部分のリソースはJSON表現を備えているため、例えばv1 JSONリソースは、application/vnd.yellowfin.api-v**1**+jsonを必要とします。 - APIは下位互換性があります。v1リソースのリクエストは、Yellowfin インスタンスの現在のAPIバージョンがv2でも動作します。 APIを利用するためのキーとなるセキュリティトークンが2つあります。 | | | | --- | --- | | **トークン** | **説明** | | リフレッシュ | これは、ログイン時に取得される不透明なセキュリティトークンです。リフレッシュトークンは有効期限がなく、アクセストークンを取得するためクライアントアプリケーションに安全に保存される場合があります。 | | アクセス | これはJSON Web Token (JWT)で、20分で有効期限が切れます。アクセストークンは、ほぼすべてのAPIリクエストの認証ヘッダーで送信される必要があります。有効期限が切れると、クライアントアプリケーションは、リフレッシュトークンを使用して、新しいアクセストークンを取得することができます。 | すべてのAPIレスポンスは、ひとつの「_links」オブジェクトを持ちます。「_links」オブジェクトには、ひとつまたは複数のリンクオブジェクトを含めることもできます。 - すべてのリンクは、ユーザーがアクセスできる関連リソースを表します。 - クライアントは、アプリケーションコードでハードコーディングするのではなく、href属性のリンクを使用して、リソースにアクセスします。 - 「options」配列は、ユーザーがリンクの使用を許可されているHTTPメソッドを示します。例えば、下の例では、ユーザーはコメントリストを読むことができる（GET）、または新しいコメントを作成できる（POST）ことを示しています。すべてのコメントを削除することはできないため、「comments」リンクでDELETEを利用できません。 ![image](media://bd849343-58d2-4795-8685-95020d620d0c) 一部のAPIレスポンスは「_embedded」オブジェクトを持ちます。このオブジェクトには、現在のリソースに関連する追加の有用な情報を含むサブオブジェクトを含めることができますが、そのリソースには直接属しません。これらは、独自のプロパティとリンクを持つ個別のリソースです。 ![image](media://57a0acab-6620-45f4-9597-ec3986a51258) --- ## 認証 > Macro (styleclass) > > [ページトップ](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#top) APIの大部分のエンドポイントでは認証が必要です。主な例外は、次の通りです。 - base /apiリソース。これは、apiコンシューマーアプリケーションによって一般的に使用され、基本api情報を取得するために、認証の有無にかかわらず使用できます。 - 要求された資格情報がリクエストの一部として渡される独自のインライン認証を提供する一部のエンドポイント (より詳細な情報は、[REST API ドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください)。 ### ログイン REST APIは、リフレッシュトークンおよびアクセストークンを使用して、リソースへのアクセスを認証および許可します。これらのトークンは、いくつかの異なる方法で生成することができます。 #### 標準的なログイン 標準的なログインフローは、リフレッシュトークンの認証と生成のために、サーバーにユーザーの資格情報を渡します。また、利便性のためにアクセストークンも渡します。リフレッシュトークンはその後アクセストークンを作成するために使用し、その他のリソースへのアクセスに使用することができます。 セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST エンドポイントを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。 1. HTTP操作はPOSTを使用します。どのようなリソースを作成するリクエストでも、常にPOST操作を使用します。これにより、リフレッシュトークンが作成されます。 > Macro (inline-media-image) 2. リフレッシュトークンエンドポイントのURLを使用します。有効なURLは常に名前（例：http://yellowfin.myapp.com/api/...）または、IPアドレス（例：http://127.0.0.1/api/…)のいずれかを持ちます。ポートが指定されている場合もあります（http://yellowfin.myapp.com:**8080**/api/...）。 > Macro (inline-media-image) 3. 必須のリクエストヘッダーをいくつか設定する必要があります。APIリクエストを行うために必要なヘッダーの完全な一覧については、[こちら](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください。 > Macro (inline-media-image) 4. リクエストボディには、ユーザー名とパスワードのJSON表現が含まれます。ボディが生JSONとして送信されていることを確認してください。 > Macro (inline-media-image) このリクエストのレスポンスには、新しく作成されたリフレッシュトークンと、_embedded プロパティ配下にあるアクセストークンが含まれます。 > Macro (inline-media-image) > ⚠️ クライアントアプリケーションは、これらのトークンを安全に保存しなくてはいけません。ログアウトに必要になるため、「self」リンクも保存します。 #### シングルサインオン このAPIは、REST API自体にシングルサインオン (SSO) 機能を提供します。これにより、RESTユーザーは別のRESTユーザーにログオンし、そのユーザーのリフレッシュトークンを生成できます。リフレッシュトークンは、そのユーザー (または、他のアプリケーション) に転送して、APIの使用を許可することができます。このエンドポイントは、SSOリクエストを行っているRESTユーザーのインライン認証をサポートし、単純な認証をサポートします (SSOでのnoPassword SSOエラーについては、下記の[REST API#トラブルシューティング](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#トラブルシューティング)項目を参照してください)。 #### オンボーディング これは基本的に、Web アプリケーションから実行できる別の形式のSSOです。管理者は、特定のユーザー用のオンボーディングトークンを生成して外部アプリケーションに渡すことで、外部アプリケーションは、ユーザーの資格情報を使用してリフレッシュトークンを生成する代わりに、そのトークンを認証フローに渡すことができます。トークンがリフレッシュトークンのPOSTリクエストとともに渡された場合 (これは、上記通常のREST SSOリクエストではありません) 、このトークンは、Web アプリケーションで作成されたトークンと照合され、ユーザーをログオンさせます。 #### Web SSO Web アプリケーションとJavaScript APIの両方で、シングルサインオンを処理するために異なるトークンシステムを使用します。つまり、これらのトークンを相互に使用することはできません。幸いなことに、REST APIには、必要なWeb SSOトークン (REST APIではログイントークンと呼ばれます) を生成する方法がいくつか用意されています。これらのトークンを生成する主な方法は、以下の3つです。 | | | | --- | --- | | **生成方法** | **説明** | | ログイン中に他のユーザーのトークンを生成する | リクエスト内で/login-tokensにユーザーの資格情報を渡すと、そのユーザーが認証され、そのユーザーのWeb SSOトークンが作成されます。これは、管理者アカウントが他の管理者以外のユーザーにログオンするために使用できます。 | | 現在ログインしているRESTユーザーのトークンを生成する | これは上記と同じフローを使用しますが、セカンダリーユーザーの資格情報が渡されない場合は、代わりに現在のユーザー用のトークンが生成されます。これは、現在のユーザをJS APIやWeb コンテンツにリダイレクトする統合に役立ちます。 | | ログインしていないときに他のユーザーのトークンを生成する | /rpc/login-tokens エンドポイントを使用することで、インライン認証を使用して、管理ユーザーの資格情報だけではなく、ログインするユーザーの資格情報も渡すことができます。 | APIの一般的な使用例は、Web SSOです。ログイントークンの生成には、2つのAPI エンドポイントを使用できます。生成されたトークンを使用して、Yellowfinのブラウザインターフェースにログインできます。これを行う最も簡単な方法は、RPC エンドポイント POST / longin-tokens/create-sso-tokenを使用することです。 - HTTPメソッドをPOSTに、URLを/login-tokens/create-sso-tokenに設定します。 - 必要なヘッダーを設定します。 > Macro (inline-media-image) - リクエストボディは、生JSONに設定します。 > Macro (inline-media-image) - レスポンスにはログイントークンと、セッションを終了するためのAPI エンドポイントが含まれます。 > Macro (inline-media-image) - Yellowfin Web UI、またはJavaScript APIにログインするために、トークンが使用される場合があります。詳細は、[こちら](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1901664)を参照してください。 ### アクセストークン アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。 - HTTP操作にPOSTを選択します。 - アクセストークンエンドポイントのURLを使用します。 - リフレッシュトークンリクエストと同様のヘッダーを使用します。 - 認証ヘッダーは、リフレッシュトークンを「token」という名前のプロパティで指定しなくてはいけません。 ![image](media://8867bb29-65b7-451a-8cff-39a74ca3f90b) リフレッシュトークンのレスポンスはアクセストークンを提供し、ログイン後にAPIの利用を開始しやすくします。 ### ログアウト リフレッシュトークンが生成されるログオンフローも、同じ方法でログアウトできます。シングルログオフ (SLO: Single Log-off) は、現在ログインしているユーザーにその権限がある限り、/refresh-tokens エンドポイントによって削除される別のユーザーのトークンIDを渡すことで実現できます。 また、(ログイントークンの作成時に返される) トークンIDを、/login-tokens DELETE エンドポイントに渡すことによって、Web SSOセッションをSLOすることもできます。同じアクセス制限が適用されます。 POST/refresh-tokens リクエストのレスポンスには、REST APIから効果的に「ログアウト」するために必要な情報、つまりリフレッシュトークンを削除するために必要な情報が含まれています。POST/refresh-tokens リクエストのレスポンスには、_links プロパティが含まれています。 ![image](media://4ca055e3-1084-4e1a-9fdb-f7e6ed317076) 「self」リンクのオプション配列には、新しいリフレッシュトークンで実行できる操作が表示されます。DELETEのみが表示されるはずです。DELETE/refresh-tokensを呼び出すと、REST APIから効果的にユーザーをログアウトさせます。 この操作を実行するには、有効なアクセストークンが必要です。これは、認証ヘッダーのtokenプロパティに含まれていなくてはいけません。 ![image](media://63d0f018-70a5-46d2-964e-b16f507ea4d8) --- ## リソースへのアクセス 各エンドポイントに指定する必要のあるヘッダー、必須およびオプションパラメーターについては、[APIドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください。 ### Base API リソース このエンドポイントは、標準RESTリソースとして表されるAPI自体の現在の状態を示します。これは、ログインしているユーザーとログインしていないユーザーの両方が使用できるため、アクセストークンの有無にかかわらずアクセスできます。これは、現在のAPIバージョンなどのAPI情報、現在のアプリケーションバージョンなどのサーバ情報を返します (以下の注意を参照してください) 。エンドポイントは、現在のユーザーが使用できるすべての最上位レベルのリソースも返します (ログインしているユーザーがいない場合は、ログインしていないユーザーがアクセスできる最上位のエンドポイントを返します)。 > ℹ️ 同じRESTバージョンのアプリケーションバージョン間で使用可能なエンドポイントが異なる場合があるため、APIバージョンと同様にこの値に注意することが重要です。 ### 標準リソース ほとんどすべての標準リソースは、アクセストークン認証を必要とし、大部分はJSONとして表現されます (エンドポイントの詳細については、[REST APIドキュメント](https://developers.yellowfinbi.com/dev/api-docs/v1.2/)を参照してください) 。これらは通常、標準構造を共有し、オブジェクトのプロパティ、ナビゲーション用の_linksおよび_embeddedプロパティ、その他の有用な情報を持ちます。 大部分のリストエンドポイントは、JSONでシリアライズされたオブジェクトを使用してエンドポイントにフィルタリング情報を渡すフィルタリングシステムを実装しています。これらのエンドポイントには、通常、現在のユーザーが使用できるフィルター値を示す直接の子/metadata リソースも付随します。各エンドポイントのより詳細な情報については、[REST APIドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください。 APIレスポンスで返されるモデルフィールドを制御できるフィールドパラメーターを提供するエンドポイントがいくつかあります。これらは、含める必要があるプロパティ名のシリアル化されたJSONリストとして送信されます。この機能は、すべてのエンドポイントで均一に実装されているわけではなく、すべてのフィールドをすべてのエンドポイントで除外できるわけではありません。各エンドポイントについて、より詳細な情報は、[REST APIのドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください。 ### RPC リソース RPC (Remote Procedure Call: リモートプロシージャコール)  エンドポイントは、認証 (一部のRPC エンドポイントはインライン認証を備えています。詳細は、[REST API ドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/#operation/deleteLoginTokenRPC)参照) およびレスポンス構造の同じルールに従いますが、REST パラダイムには従わないという点で、標準リソースエンドポイントに類似しています。これらは、リソースを直接表すのではなく、サーバー上で実行されるプロシージャを表します。すべてのRPCエンドポイントは、POST操作を使用します。 これらが存在する理由は、ステートフルな相互作用を必要とするエンドポイントや、複雑なマルチリクエスト呼び出し構造など、RESTパラダイムに適合するのが非常に難しい機能を実装しているからです。これらは通常、既存のSOAPサービスまたはWeb アプリケーションインタフェースから移行された機能であり、明確にリファクタリングすることは非常に困難です。これらの機能の一部は、将来完全なRESTful実装に変換される可能性があります。 --- ## リクエストボディパラメーター 使用可能なPOST操作を持つほとんどのエンドポイントは、追加のパラメーターを必要としないほど単純でない限り、リクエストボディにパラメーターを渡す必要があります。必要とされるリクエストボディの形式が異なるのは、主に次2つの状況です。 - application/form-dataを必要とするリクエストは、通常、何らかのファイルアップロードを必要とするリクエストです。つまり、ボディはform-dataとして渡され、正しいエンコーディングを使用する必要があります。ファイルアップロードパラメーターを参照しないサブオブジェクトは、form-data内で生のJSONとしてエンコードする必要があります。 - ファイルアップロードパラメーターを持たない他のすべてのリクエストは、リクエストボディで生のJSONを使用します。 各エンドポイントの正確な要件については、[REST API ドキュメント](https://developers.yellowfinbi.com/dev/api-docs/current/)を参照してください。 --- ## ログインフローの例 一般的に、APIのほとんどの使用例では、REST APIへのログインと同様のアプローチに従う必要があります。このアプローチは、REST APIへの初期接続およびユーザーログインを構成します。ユーザーまたは管理者による強制ログアウトによってトークンが無効化されない限り、後続の接続で別のリフレッシュトークンを生成する必要はありません。一部のサーバーより上位の機能をサポートするアプリケーションの場合は、セッション間でサーバーのバージョンが変更されていないことを確認することを推奨します。 1. APIのバージョンについてサーバーをプローブします。 - これは、base/api エンドポイントにGETリクエストを行うことで実現できます (詳細は、[REST API#Base API リソース](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#BaseAPIリソース)項目を参照してください) 。ここで返される結果は、サーバのAPIバージョンおよびアプリケーションバージョンを決定します。これにより、API使用者は、サーバのサポートされているバージョン範囲内にあるサポートされているバージョンを使用して対話できます。 - base/api エンドポイントは、バージョン1.0と1.1には存在しなかったことに注意してください。バージョン1.0と1.1は本質的に同一であり、ほぼ100%の互換性があります (相違点については、[各バージョンのドキュメント](https://developers.yellowfinbi.com/dev/api-docs/)を参照してください) 。そのため、このエンドポイントから404応答を受け取ることは、サーバーはこれらのバージョンのいずれかを実行していることを示し、v1にフォールバックすると、v1.1からの非常にマイナーな変更を除いて、すべてのケースで動作することになります。 2. 利用可能ないずれかの方法でリフレッシュトークンを生成します（詳細は、[REST API#ログイン](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#ログイン)項目を参照してください）。 3. リフレッシュトークンレスポンスから自動的に生成されたアクセストークンを使用するか、必要に応じて独自のアクセストークンを作成してください（しばらくアクティビティがなかった場合、生成されたアクセストークンは期限切れになることがあります）。 4. これで、アクセストークンを使って、この種のトークンを必要とするすべてのAPIリソースにアクセスできるようになります。 --- ## トラブルシューティング - クロックスキュー - 最も一般的に発生するエラーのひとつです。これは、認証ヘッダーのタイムスタンプが、サーバ時刻と同期していないために発生します。±5分の許容値がありますが、この範囲を外れると、APIはエラーでレスポンスします。 > Macro (inline-media-image) - トークンの有効期限切れ - 有効期限の切れたアクセストークンを使用すると、APIはエラーでレスポンスします。 > Macro (inline-media-image) - 認証の失敗 - 無効なユーザー名、またはパスワードを使用すると発生します。 > Macro (inline-media-image) - 不明なバージョン - Accept ヘッダーに誤ったAPIバージョンを指定すると発生します。 > Macro (inline-media-image) - ライセンスエラー - GET /stories/uuidのようなコンテンツサービスは、サーバライセンスが存在する場合のみ利用できます。そうではない場合、APIは401 Unauthorized errorを返します。 > Macro (inline-media-image) - CORS - CORSはブラウザにのみ適用されるため、一般的にREST APIにとって問題にはなりません。トークンの安全な保存が容易ではないため、Webブラウザは推奨されるREST クライアントではありません。 - SSO エラー - 資格情報とOrg Referenceが正しいことを確認します。noPassword認証を使用している場合は、サーバ側で有効になっていることを確認します。これは、システム構成テーブルにレコードを挿入し、**Yellowfinを再起動**することで実行します。 INSERT INTO Configuration values (1, 'SYSTEM', 'SIMPLE_AUTHENTICATION', 'TRUE'); > Macro (inline-media-image) - Error 500 Internal Server Error - これは、サーバ上で何か問題が発生したことを示す一般的なエラーメッセージです。詳細については、サーバログにあるエラートレースをサポートに連絡してください。 現在利用可能なREST サービスの詳細については、[開発者サイト](https://developers.yellowfinbi.com/dev/api-docs/yf-api.html)をご確認ください。 **注意：**Yellowfin 本社の提供するサイト（英語）へリンクします。 --- ## APIの新しいバージョンへの移行ガイドライン Yellowfin REST APIは、サーバー側コードとクライアント側コードが独立して進化できるように設計されています。これにより、APIの新しいバージョンがリリースされても、以前のバージョンで開発されたAPIクライアントは引き続きサポートされます。例えば、Yellowfin 9.14にはREST API v3が搭載されていますが、API v1.0~2.2は並行して動作します。v1.3を使用して開発されたAPIクライアントは、Yellowfin 9.14と動作させるために変更する必要はありません。 REST APIのバージョン管理 schemeは、メジャーバージョン番号とマイナーバージョン番号を使用しています。 - 新しいエンドポイントが追加された場合、または既存のエンドポイントのリクエストにパラメーターが追加された場合、または既存のエンドポイントのレスポンスにフィールドが追加された場合、APIのマイナーバージョンがインクリメントされます。APIクライアントは、変更を加えることなく新しいバージョンのAPIを使用できます。v1.2を使用して開発されたAPIクライアントは、v1.3とも互換性があります。 - APIに重大な変更（エンドポイントの削除、エンドポイントのリクエスト構造やデータ型の変更、レスポンスフィールドの削除またはリネームなど）が発生した場合、APIのメジャーバージョンがインクリメントされます。APIクライアントは、互換性のない変更に対応するためのリファクタリングを行わない限り、新しいバージョンを使用できません。ただし、APIクライアントは変更なしで古いバージョンを継続して使用できます。例えば、Yellowfin 8でv1.2を使用して開発されたAPIクライアントは、Yellowfin 9.14でもv1.2のAPIを継続して使用できます。 - バグ修正は、バグを修正するために互換性のない変更が必要でない限り、APIのバージョン変更を引き起こしません。 APIクライアントは、HTTP Acceptヘッダーを使用して使用するAPIバージョンを選択できます。例えば、Yellowfin 9.14では、APIクライアントはAccept=application/vnd.yellowfin.api-v2.2+jsonを指定してv2.2 REST APIを使用し、Accept=application/vnd.yellowfin.api-v3.0+jsonを指定してv3 REST APIを使用できます。このヘッダーは各リクエストで送信する必要があるため、APIクライアントは1つのエンドポイントではv2.2を、別のエンドポイントではv3を消費するように選択できます。 ### v2.2 から v3.0 への移行 Yellowfin 9.14 には REST API v3.0 が搭載されています。新しいエンドポイントがいくつか追加されていますが、このセクションでは、メジャーバージョン変更を必要とした互換性のない変更点を一覧表示します。以下のエンドポイントは、両バージョン間で互換性のない変更が施されています： GET /admin/users POST /admin/users GET /admin/users/{userId} PATCH /admin/users/{userId} PUT /admin/users/{userId}/password GET /users/{userId} PATCH /users/{userId} GET /rpc/users/user-details-by-email/{email} GET /rpc/users/user-details-by-username/{username} これらのエンドポイントから返されるJSONオブジェクトは、ユーザー定義の統一化を図るため変更されました。v2.2およびそれ以前のバージョンでは、/admin/users エンドポイントのユーザー構造は/users エンドポイントと大幅に異なっていました。 **変更の詳細** 1.以下のエンドポイントのレスポンスにおける重大な変更点は、name フィールドの削除です。これらは firstName と lastName フィールドに置き換えられました。新しいフィールドがいくつか追加されましたが、v2.2 から v3.0 への移行時に互換性の問題は発生しません。 ![image-20250514-101814.png](media://3d95e5c2-e832-49f2-877e-0a664b9a8e2a) GET /users/{userId} PATCH /users/{userId} GET /rpc/users/user-details-by-email/{email} GET /rpc/users/user-details-by-username/{username} 2.以下のエンドポイントのリクエスト構造が変更され、より多くのフィールドの更新に対応しました。 PATCH /users/｛userId｝ v3.0以前では、このエンドポイントはユーザーのタイトルと説明のみを更新可能でしたが、現在はリクエスト本体にJSONオブジェクトを送信することで、ファーストネーム、ラストネーム、タイムゾーン、ジョブタイトル、プレファレンスなど、より多くのフィールドを更新できるようになりました。 3.以下のエンドポイントのレスポンスに複数の互換性のない変更があります： GET /admin/users POST /admin/users 変更点は以下の通りです： - フィールド「ipId」は「userId」にリネームされました - フィールド「userId」は「userName」にリネームされました - フィールド「userId」は「userName」にリネームされました - フィールド「initial」は空の場合、返却されません - パスワード、リセットパスワード、ユーザーセッション、および組織アクセスへのリンクが削除されました。これらのリンクは/admin/users/｛userId｝からアクセス可能です - 新しいフィールドがいくつか追加されましたが、v2.2からv3.0への移行時に互換性の問題は発生しません。 ![image-20250514-102240.png](media://9803aebc-c21e-49a4-bae7-432abf3c880a) 4.以下のエンドポイントのリクエスト構造が変更され、ユーザー作成時により多くのフィールドをサポートするようになりました。 POST /admin/users このエンドポイントのリクエスト本体には、上記で詳細に説明されたUserオブジェクトのスキーマを使用する必要があります。 5.以下のエンドポイントのレスポンスには、複数の互換性のない変更が含まれています： GET /admin/users/｛userId｝ PATCH /admin/users/｛userId｝ 変更点は以下の通りです： - フィールド「ipId」は「userId」に名称変更されました - フィールド「userId」は「userName」に名称変更されました - フィールド「languageCode」は「preferredLanguageCode」に名称変更されました - フィールド「emailAddress」は「email」に名称変更されました - 新しいフィールドがいくつか追加されましたが、v2.2からv3.0への移行時に互換性の問題は発生しません。 ![image-20250514-102538.png](media://f2ea63bb-a715-4d2c-a24e-f79899443d03) 6.以下のエンドポイントのリクエスト構造が変更され、ユーザー更新時により多くのフィールドをサポートするようになりました。 PATCH /admin/users/｛userId｝ このエンドポイントのリクエスト本体には、上記で詳細に説明されたUserオブジェクトのスキーマを使用する必要があります。 ### v3.0 から v4.0 への移行 Yellowfin 9.15にはREST API v4.0が搭載されています。このセクションでは、メジャーバージョン変更を必要とした互換性のない変更点を一覧で示します。v4.0には、互換性のない変更に該当しないその他の機能強化とバグ修正が含まれています。変更点の完全な一覧については、リリースノートをご参照ください。 以下のエンドポイントでは、2つのバージョン間で互換性のない変更が実施されています： GET /categories POST /categories DELETE /categories GET /categories/｛categoryCode｝ PATCH /categories/｛categoryCode｝ DELETE /categories/｛categoryCode｝ POST /rpc/categories/｛categoryCode｝/refresh-access-cache GET /content GET /dashboards GET /dashboards/｛id｝ GET /presentations GET /presentations/｛id｝ GET /themes GET /themes/｛id｝ GET /reports GET /reports/｛id｝ **変更の詳細** 1.v4.0において、Categories エンドポイントのスイートに根本的な変更が加えられました。これらのエンドポイントは、カテゴリコードの代わりにUUIDを使用してトップレベルカテゴリとサブカテゴリを参照するように再実装されました。v4.0では、リクエスト構文とレスポンスJSONが変更されています。サポートされるフィルターとその構文も変更されています。 GET /categories POST /categories DELETE /categories GET /categories/｛categoryCode｝ PATCH /categories/｛categoryCode｝ DELETE /categories/｛categoryCode｝ POST /rpc/categories/｛categoryCode｝/refresh-access-cache 上記のエンドポイントには多くの重大な変更が含まれており、以下に主要な変更点のみを列挙します。 カテゴリAPIの以前のバージョンを使用して作成されたAPIクライアントは、v4で慎重にレビューおよびテストする必要があります。 - categoryCode は、上記のいずれのエンドポイントへのリクエストでも使用されず、そのレスポンスにも返されません。代わりに、categoryUUID を受け付け、返します。 ![image-20250514-103116.png](media://0bab9116-cad2-4c7f-84c4-43401d3a7800) - GET /categories などのエンドポイント（カテゴリ一覧を返すもの）には、menu、api、collection などの汎用リンクが含まれていますが、これらのリンクはリストアイテム内では不要と判断されました。これらのリンクは、リストアイテムの配列の外側にリンクとして利用可能です。 - フィルターを指定しない場合、v4のGET /categoriesはアクセス可能な最上位カテゴリのみを返します。以前のバージョンでは、アクセス可能な最上位カテゴリとサブカテゴリのすべてが返されていました。この動作をv4で維持するには、APIクライアントはフィルターINCLUDE_CHILDRENをtrueに設定する必要があります。 - フィルターは完全に再設計されました。カテゴリエンドポイントでフィルターを使用するAPIクライアントは、再検討が必要です。例えば、STATUS フィルターは廃止されました。 - DELETE /categories エンドポイントでは、常にフィルターを指定する必要があります。すべてのカテゴリを削除するオプションはありません。 - GET /categories/｛categoryUUID｝ などのエンドポイントから返されるカテゴリ リソースは、以前のバージョンの対応するエンドポイント（例：GET /categories/｛categoryCode｝）からいくつかの変更が加えられています。 　・フィールド「deletePeriodUnit」は「maxContentAge」に名称変更されました 　・フィールド「deleteUnitCode」は「maxContentAgeUnit」に名称変更されました 　・フィールド「approvalUserId」は「approverId」に名称変更されました 　・フィールド「usersWithAccess」は、プライベートカテゴリの場合のみレスポンスに表示されます ![image-20250514-103423.png](media://3d6b2ff7-3630-4307-8dd9-0901de665e81) 2.以下のエンドポイントにおける変更は、レスポンス内のカテゴリの_linksの変更です。_linksを使用していないAPIクライアントは、この変更による影響を受けません。 以前のバージョンでは2つのrel（categoryとsubCategory）が存在しましたが、v4.0ではcategoryのみになります。これはコンテンツアイテムを格納する「フォルダー」を表し、トップレベルのカテゴリではありません。これは、v3.0 以前のコンテンツ項目のサブカテゴリに相当します。以下の例では、v3.0 の subCategory リレーションと v4.0 の category リレーションは同じ「フォルダー」を指します。v3.0 の category リレーションは v4.0 では表現されていません。 ![image-20250514-103537.png](media://9c5a4d1c-2875-4006-b852-cce600ceef9d) GET /content GET /dashboards GET /dashboards/｛id｝ GET /presentations GET /presentations/｛id｝ GET /themes GET /themes/｛id｝ GET /reports GET /reports/｛id｝ ### v4.0 から v4.1 への移行 Yellowfin 9.16.1 には REST API v4.1 が搭載されています。本リリースには互換性を損なう変更はなく、機能強化やバグ修正が含まれます。具体的には、他のユーザーがアクセス権を持つコンテンツ項目を一覧表示するための新しい管理用エンドポイントが追加されました。変更点の完全なリストについてはリリースノートをご参照ください。 ### v4.1 から v4.2 への移行 Yellowfin 9.17 には REST API v4.1 が搭載されています。このリリースでは互換性を損なう変更はありません。導入された変更の概要は以下の通りです：- - RESTドキュメントv4.1 (9.16) は修正を加えて再公開されました：以前のドキュメントでは、GET /api/content および GET /api/admin/users/{userId}/content がコンテンツタイプでフィルタリングするためにEQUAL_TO演算子を使用すると誤って記載されていました。ドキュメントはIN_LIST演算子を使用すべきであると修正されました。 - POST /data-sources/id/client-data-sources は、リクエストパラメータ「includeOnlyNewSourceInResponse」を受け付けるようになりました。このパラメータが true の場合、API は「items」配列に新しくマッピングされたクライアントソースのみを返すよう指示されます。 - クライアント参照IDを使用して組織リソースを取得するための新しいRPCエンドポイント GET /api/rpc/orgs/org-by-referenceid/{clientRefId} を追加しました。 - 姓が空の場合、REST経由でユーザーを作成できない問題を修正しました。（V3以降） - ユーザーに関連するすべてのREST APIを更新し、ユーザーが見つからない場合に404レスポンスを返すようにしました（以前は曖昧すぎるエラー500を返していました）。 - ユーザーグループ REST エンドポイントに検証チェックを追加し、削除されたユーザーグループに対して操作を試行した場合に 404 応答を返すようにしました。 - APIリクエストを使用してデータソースをインポートする際、アクセスフィルターの更新スケジュールが有効化されない問題を修正しました。 - REST API経由でユーザーを作成してもライセンス更新が即時に行われない問題を修正しました。