カスタム処理からKurocoのAPIを呼び出せますか？

カスタム処理からKurocoのAPIを呼び出したい場合は、下記2つの方法がございます。

api_internalプラグインを利用する
api_methodプラグインを利用する

それぞれの方法について説明します。

api_internalプラグインを利用する

api_internalプラグインを利用することで、API画面で設定した任意のエンドポイントを呼び出し、実行結果を取得できます。
以下に利用方法例を紹介します。

例1. GETメソッド (認証なし)

{* クエリパラメータ *}
{assign_array var='queries'        values=''}
{assign       var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
    var='response'
    status_var='status'
    endpoint='/rcms-api/1/topics'
    method='GET'
    queries=$queries}

HTTPリクエストを経由して対象のAPIを呼び出し、varで指定した変数にレスポンスをアサインします。

status_varで指定した変数には、リクエストの成否がアサインされます。成功した場合は1を、ネットワークエラーなどの要因で失敗した場合には0を返します。

上記サンプルコードの実行内容は、次のようなJavaScriptのコードに相当します。エンドポイント /rcms-api/1/topics のクエリパラメータにext_col_01 = "1"のfilter条件を指定し、リクエストを送信しています。

let queries = {};
queries.filter = 'ext_col_01 = "1"';

fetch(
  'https://your-site-key.g.kuroco.app/rcms-api/1/topics?' + (new URLSearchParams(queries)).toString(),
  // => https://your-site-key.g.kuroco.app/rcms-api/1/topics?filter=ext_col_01+%3D+%221%22
  {
    method: 'GET',
  }
);

filterの利用方法については、下記ドキュメントをご参照ください。
チュートリアル -> 検索機能を実装する
リファレンス -> 検索機能の使い方

例2. POSTメソッド (認証あり)

{* リクエスト ボディ *}
{assign_array var='body'            values=''}
{assign       var='body.subject'    value='Title'}
{assign       var='body.ext_col_01' value='2'}

{api_internal
    var='response'
    status_var='status'
    endpoint='/rcms-api/2/topics/insert'
    method='POST'
    queries=$body
    member_id=$smarty.session.member_id}

member_idパラメータを渡すと、指定したメンバーIDが認証された状態でリクエストを実行できます。

member_idパラメータを指定できるのは、対象のAPIの認証方式が「動的アクセストークン」に設定されている場合に限ります。利用する場合は、内部処理用のAPIを別途作成することを推奨します。
動的アクセストークンについては、APIセキュリティ -> 動的アクセストークンをご確認ください。

上記サンプルコードの実行内容は、次のようなJavaScriptのコードに相当します。

let body = {};
body.subject = 'Title';
body.ext_col_01 = '2';

fetch(
  'https://your-site-key.g.kuroco.app/rcms-api/2/topics/insert',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      // 指定したmember_idを元にアクセストークンを生成し、自動的に付与します
      'X-RCMS-API-ACCESS-TOKEN': '********',
    },
    body: JSON.stringify(body),
  }
);

例3. GETメソッド (サーバー上での直接実行)

{assign_array var='queries'        values=''}
{assign       var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
    var='response'
    status_var='status'
    endpoint='/rcms-api/1/topics'
    method='GET'
    queries=$queries
    direct=1}

例1・例2の処理はHTTPリクエストを経由して対象のエンドポイントを呼び出します。しかしながら、ネットワークの状況によっては以下の問題が発生する可能性もあります。

結果の取得に時間がかかる
結果の取得に失敗する

そこで、direct=1をパラメータに指定すると、HTTPリクエストを経由せずサーバー上で直接エンドポイントの処理を実行できます。
安定して結果を取得できるのが利点ですが、レスポンスのキャッシュが効かないため、利用料金を考慮の上ご利用ください。

direct=1をパラメータに指定できるのは、対象エンドポイントのHTTPメソッドがGETの場合に限ります。また、member_idの指定はできません。

例4. GETメソッド (セッション状態を引き継いだリクエスト)

{* クエリパラメータ *}
{assign_session key='my_session_name' value=true}

{assign_array var='queries'        values=''}
{assign       var='queries.filter' value='ext_col_01 = "1"'}
{api_internal
    var='response'
    status_var='status'
    endpoint='/rcms-api/1/topics'
    method='GET'
    queries=$queries
    direct=1
    use_current_session=1}

通常であれば、api_internalプラグインの呼び出し元と呼び出し先では別々のセッションが生成されます。
しかしながら、direct=1とuse_current_session=1を同時に指定すると、呼び出し元のセッションを引き継いだまま対象エンドポイントの処理を実行できます。
そのため、ログイン状態を引き継いだまま直接実行をしたい場合や、assign_sessionプラグインを利用して独自のセッション変数を管理するような場合に有効です。

呼び出し先のエンドポイントの前処理、または後処理に以下の記述をすることで、呼び出し元とセッション状態が同一であることを確認できます。

{* $my_session_value に呼び出し元で設定したセッションがアサインされます *}
{assign_session var='my_session_value' key='my_session_name'}

{* 呼び出し元のログイン状態が引き継がれます *}
{assign var='member_id' value=$smarty.session.member_id}

api_methodプラグインを利用する

api_methodプラグインを利用した場合、エンドポイントを作成せずにAPIの機能を直接呼び出すことができます。

api_internalプラグインをdirect=1パラメータ付きで呼び出した場合と同様、HTTPリクエストを経由せずにサーバー上で処理を実行します。呼び出したAPI機能は、呼び出し元と同じセッション状態を自動的に引き継ぎます。

api_methodで呼び出せるのは、対象機能のHTTPメソッドがGETの場合に限ります。例えば、Topicsのlistやdetailsは呼び出せますが、insertやupdateは呼び出せません。POSTメソッドを実行する必要がある場合は、予めエンドポイントを作成し、api_internalプラグインを経由して呼び出してください。

api_methodプラグイン利用例

{*  エンドポイント設定パラメータ *}
{assign_array var='method_params'                 values=''}
{assign_array var='method_params.topics_group_id' values='1'}
{assign       var='method_params.cnt'             value=10}
{* クエリパラメータ *}
{assign_array var='request_params'        values=''}
{assign       var='request_params.filter' value='ext_col_01 = "1"'}
{api_method
    var='topics'
    model='Topics'
    method='list'
    version='1'
    method_params=$method_params
    request_params=$request_params}

varで指定した変数に実行結果がアサインされます。

上記の例で$topics変数にアサインされるデータは、API画面で次のようなエンドポイントを設定し、リクエストを実行した場合の結果と同一になります。

エンドポイント設定

リクエスト

fetch(
  "https://your-site-key.g.kuroco.app/rcms-api/{api_id}/topics?filter=" + encodeURIComponent('ext_col_01 = "1"'),
  {
    "method": "GET",
  }
);

api_internalプラグインとapi_methodプラグインの使い分けについて

api_internalプラグインは既存のエンドポイントを呼び出す必要があり、api_methodプラグインはその必要がありません。

そのため、既存のエンドポイントを再利用したい場合はapi_internalを、エンドポイントを利用する必要がない場合はapi_methodを利用することを推奨いたします。

お探しのページは見つかりましたか？解決しない場合は、問い合わせフォームからお問い合わせいただくか、Slackコミュニティにご参加ください。