---
title: "REST API"
canonical: "https://wiki.yellowfin.co.jp/space/USER80/2622053/REST%20API"
format: markdown
---
> Macro (toc)
> ℹ️ 現在利用可能なREST サービスの詳細については、[開発者サイト](https://developers.yellowfinbi.com/dev/api-docs/yf-api.html)をご確認ください。
> ℹ️
> ℹ️ **注意：**Yellowfin 本社の提供するサイト（英語）へリンクします。
## 主要な概念
REST APIは、/api ネームスペース配下で利用できます。例：[https://yellowfin.myapp.com/api/stories](https://yellowfin.myapp.com/api/stories)
このスイートには、/api/rpc ネームスペースにある、RPCの呼び出しも含まれます。
すべてのAPIリクエストには、**認証ヘッダー**が必要です。形式は、以下の通りです。
**YELLOWFIN ****ts=1600224140615** **nonce=3370ddc4-37d9-41b9-9f24-ada181fdc4bf** **token=securityToken**
| | |
| --- | --- |
| **要素** | **説明** |
| **YELLOWFIN** | カスタム認証スキーマ |
| **ts** | 1970年1月1日午前0時0分0秒（UTC）であるUNIXエポックからのミリ秒単位時刻です。これは、APIを呼び出すプログラムの現在時刻です。すべてのプログラミング言語には、この形式で現在時刻を取得する方法があります。 |
| **nonce** | クライアントにより生成されるランダムUUID |
| **token** | ユーザーを認証し、リソースへのアクセスを許可するために使用されるセキュリティトークン |
すべてのAPIリクエストには、**Accept ヘッダー**が必要です。
- このヘッダーは、APIのバージョンを識別するために使用されます。
- その形式は、各endpointのAPIドキュメントで指定されています。通常は次の通りです。application/vnd.yellowfin.api-v**1**+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. [ログイン - 新しいリフレッシュトークンを作成します。](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#ログイン（リフレッシュトークンの作成）)
2. [アクセストークン - ユーザーにREST APIリソースへのアクセスを許可するために使用します。](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#アクセストークン)
3. [ログアウト - リフレッシュトークンを削除します。](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#ログアウト（リフレッシュトークンの削除）)
4. [リソースのリクエスト - REST APIを使用して、実際にデータを取得します。](https://yellowfinjp.atlassian.net/wiki/spaces/yfcurrent/pages/1903272/REST+API#リソースのリクエスト)
### ログイン（リフレッシュトークンの作成）
セッションではなく、リフレッシュトークンを使用してユーザーを識別します。使用者は、他のREST endpointを使用する前に、リフレッシュトークンを作成して、アクセストークンを取得する必要があります。リフレッシュトークンの作成は、ログインプロセスと考えることができます。
1. HTTP操作はPOSTを使用します。どのようなリソースを作成するリクエストでも、常にPOST操作を使用します。これにより、リフレッシュトークンが作成されます。
> Macro (inline-media-image)
2. リフレッシュトークンendpointのURLを使用します。有効なURLは常に名前（例：[http://yellowfin.myapp.com/api/](http://yellowfin.myapp.com/api/)...）または、IPアドレス（例：[http://127.0.0.1/api/…](#))のいずれかを持ちます。ポートが指定されている場合もあります（[http://yellowfin.myapp](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」リンクも保存します。
### アクセストークン
アクセストークンの作成は、リフレッシュトークン作成のプロセスとほぼ同じです。作成時には、以下を確認します。
- 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ドキュメント**](https://developers.yellowfinbi.com/dev/api-docs/current/)**を参照してください。**
## 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に設定します。
- 必要なヘッダーを設定します。
> Macro (inline-media-image)
- リクエスト本文は、生JSONに設定します。
> Macro (inline-media-image)
- 応答にはログイントークンと、セッションを終了するためのAPI endpointが含まれます。
> Macro (inline-media-image)
- Yellowfin Web UI、またはJavaScript APIにログインするために、トークンが使用される場合があります。詳細は、[こちら](https://yellowfinjp.atlassian.net/wiki/spaces/USER80/pages/2622712)を参照してください。
## トラブルシューティング
- クロックスキュー - 最も一般的に発生するエラーのひとつです。これは、認証ヘッダーのタイムスタンプが、サーバ時刻と同期していないために発生します。±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 本社の提供するサイト（英語）へリンクします。