開発情報・ナレッジ

投稿者:SPIRERS ナレッジ向上チーム 2022年7月20日 (水)

参照フィールドをAPIで更新するサンプルプログラム

標準機能では、参照フィールドをサイト側から登録・更新できません。(ver.2.20時点)
サイト側から登録・更新する際に、参照フィールドを更新させるPHPのサンプルプログラムを紹介します。
参考になれば幸いです。

変更・改定履歴

  • 改定

    「ID」と記載していた箇所が「識別名」が正しかったため修正

  • 改定

    PHP環境変数を使用している旨の追記

  • 追記

    自身の参照フィールドの値で更新パターンを追加

サンプルプログラム

PHP
<?php
//------------------------------
// 設定値用モジュール
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue(""));
define("API_ROLE",$SPIRAL->getEnvValue("")); // ロールによるAPI権限が不要の場合
define("APP_ID",$SPIRAL->getEnvValue(""));
define("DB_ID",$SPIRAL->getEnvValue(""));

//------------------------------
// 設定値用モジュール
//------------------------------
$commonBase = CommonBase::getInstance();
// ステップのセット
// 登録ブロックの場合
$formComplete = $SPIRAL->getRegistrationForm("ブロックの識別子"); // 登録フォームブロックの識別名を登録
// 更新ブロックの場合
$formComplete = $SPIRAL->getUpdateForm("ブロックの識別子"); // 更新フォームブロックの識別名を登録


// 完了画面での処理
if($formComplete->isCompletedStep()){    
    $record = $SPIRAL->getRecordValue();
    $dataPATCH = array(
      "参照フィールドの識別名" => "参照フィールドに登録する値",
    );
    $appInsert = $commonBase->apiCurlAction("PATCH","/apps/".APP_ID."/dbs/".DB_ID."/records/".$record['item']['_id'],$dataPATCH);
    if(isset($appInsert['item'])){
      $SPIRAL->setTHValue("insert", true);
    }else{
      $SPIRAL->setTHValue("insert", "error");
      $SPIRAL->setTHValue("errorText", "登録に失敗しました。");
    //   $SPIRAL->setTHValue("errorText", print_r($appInsert,true));
    }
}


//------------------------------
// 共通用モジュール
//------------------------------

class CommonBase
{
	/**
	 * シングルトンインスタンス
	 * @var UserManager
	 */
	protected static $singleton;
    

	public function __construct()
	{
		if (self::$singleton) {
			throw new Exception('must be singleton');
		}
		self::$singleton = $this;
	}

	/**
	 * シングルトンインスタンスを返す
	 * @return UserManager
	 */
	public static function getInstance()
	{
		if (!self::$singleton) {
			return new CommonBase();
		} else {
			return self::$singleton;
		}
	}

    
	/**
	 * V2用 API送信ロジック
	 * @return Result
	 */
	function apiCurlAction($method, $addUrlPass, $data = null)
	{
        
		$header = array(
			"Authorization:Bearer " . API_KEY,
			"Content-Type:application/json",
			"X-Spiral-Api-Version: 1.1",
		);
		if(API_ROLE){
			$header = array_merge($header,array("X-Spiral-App-Role: ".API_ROLE));
		}

		// curl
		$curl = curl_init();
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
		curl_setopt($curl, CURLOPT_URL, API_URL . $addUrlPass);
		curl_setopt($curl, CURLOPT_HTTPHEADER, $header);

		if ($method == "POST") {
			curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "PATCH") {
			curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "DELETE") {
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "GET") {
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		$response = curl_exec($curl);
		if (curl_errno($curl)) echo curl_error($curl);
		curl_close($curl);

		return json_decode($response, true);
	}
}

利用方法

設置するPHPは、登録・更新フォームを設定するページセットしてください。
サンプルプログラムは、完了画面に遷移時に動作するプログラムとなります。
API_KEY ,API_ROLE ,APP_ID, DB_ID など複数ページで使用箇所は、PHP環境変数への設定を推奨しております。
基本の設定は下記になります。
API_KEY
6行目
アカウント管理で発行したAPIキーをセットしたPHP環境変数の変数名
API_ROLE
7行目
アプリロールの識別名をセットしたPHP環境変数の変数名
アプリロールによる権限設定をしない場合は未入力
APP_ID
8行目
更新するアプリのIDをセットしたPHP環境変数の変数名
DB_ID
9行目
更新するDBのIDをセットしたPHP環境変数の変数名

下記は、PHP環境変数を使った書き方になります。
環境変数を使用しない場合は、下記を使用せずに直接識別名もしくは IDを設定してください。
$SPIRAL->getEnvValue("")
次にどのフォームブロックかを判定する箇所を修正します。
16行目 - 19行目の箇所になります。
// 登録ブロックの場合
$formComplete = $SPIRAL->getRegistrationForm("ブロックの識別子"); // 登録フォームブロックの識別名を登録
// 更新ブロックの場合
$formComplete = $SPIRAL->getUpdateForm("ブロックの識別子"); // 更新フォームブロックの識別名を登録
使用しないブロックタイプの設定は、コメントアウト(*)してください。
* 文字の先頭に「//」をつけることでコメントアウトできます。
使用するブロックタイプの設定として、「ブロックの識別子」となっている箇所を、使用するブロックの識別子に変更します。

最後に、更新するフィールドと値を指定をします。
25行目 - 28行目の箇所になります。
$dataPATCH = array(
      "参照フィールドの識別名" => "参照フィールドに登録する値",
);
更新するフィールドは、 複数フィールド可能なので、更新が必要な分追加をお願いします。

こちらのサンプルプログラムは、 APIが失敗した場合や重複不可になった場合に、
参照フィールドが更新されていないゴミデータが生成される可能性がありますので、ご注意ください。

完了画面に以下のコードを設定することで、APIの使用での処理失敗時にユーザ側でエラーメッセージを表示することができます。

Thymeleaf
<th:block th:if="${cp.result.value['insert']} ne 'error'">
    <p style="text-align: center;">完了しました。</p>
</th:block>
<th:block th:if="${cp.result.value['insert']} eq 'error'">
    <p style="text-align: center;" th:text="${cp.result.value['errorText']}">text</p>
</th:block>
・注意点
完了メール配信は、更新トリガの非同期アクションで行いましょう。
フォームのメールアクションで完了メールを配信する場合、APIがエラーになった場合でもメールが送信されてしまします。
更新トリガの非同期アクションかつ経路を API に設定することで、API で参照フィールド更新成功した時のみメール配信が行えるようになります。

APIで更新する フィールド・データの例

参照フィールドを更新する際に、一緒に更新するべきフィールド や 参照フィールドを更新する際の値 の例をご紹介します。
参照フィールド①
認証エリア内にフォームを設置し、認証レコード値を参照フィールドに設定する場合
 * 認証レコード値の参照フィールドは下記の関数では指定できないので、ご注意ください。(ver.2.20時点)
$dataPATCH = array(
      "参照フィールドの識別名" => $SPIRAL->getAuthRecordByFieldId("_id"),
);
参照フィールド②
クエリパラメータを使用して、引き込んだデータのIDを参照フィールドに設定する場合
$param = explode(".", $SPIRAL->getParam("record"));
$dataPATCH = array(
      "参照フィールドの識別名" => $param[1],
);
テキスト(オリジナルキー)
任意の参照フィールドの更新が成功したレコードを重複不可したい場合
システムIDと参照フィールドをセットにした値で更新をおこないます
 * テキストのフィールド設定で、重複不可に設定する必要があります
 * 空データ(NULLのデータ)は、重複不可チェックの対象になりません。
$param = explode(".", $SPIRAL->getParam("record"));
$dataPATCH = array(
      "参照フィールドの識別名" => $param[1],
);

自身の参照フィールドの値で更新

認証エリア内に認証DBと同一DBのフォームを設置し、ログインユーザの参照フィールドの値で参照フィールドを更新する場合、
APIにて自身の参照フィールドの情報を取得する必要があります。
 * 認証レコード値の参照フィールドは下記の関数では指定できないので、ご注意ください。(ver.2.20時点)

自身の参照フィールドの値で更新する際は、下記を参考にしてください。
<?php
//------------------------------
// 設定値用モジュール
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue(""));
define("API_ROLE",$SPIRAL->getEnvValue("")); // ロールによるAPI権限が不要の場合
define("APP_ID",$SPIRAL->getEnvValue(""));
define("DB_ID",$SPIRAL->getEnvValue(""));
define("RELATION_ID",$SPIRAL->getEnvValue(""));

//------------------------------
// 設定値用モジュール
//------------------------------
$commonBase = CommonBase::getInstance();
// ステップのセット
// 登録ブロックの場合
$formComplete = $SPIRAL->getRegistrationForm("ブロックの識別子"); // 登録フォームブロックの識別名を登録
// 更新ブロックの場合
//$formComplete = $SPIRAL->getUpdateForm("ブロックの識別子"); // 更新フォームブロックの識別名を登録


// 完了画面での処理
if($formComplete->isCompletedStep()){    
    // 自身の情報を取得
    $userData = $commonBase->apiCurlAction("GET","/apps/".APP_ID."/dbs/".DB_ID."/records/".$SPIRAL->getAuthRecordByFieldId("_id"));
    // APIの実行が成功 かつ 参照フィールドの値が存在する場合
    if(isset($userData['item']) && isset($userData['item'][RELATION_ID]['value']['_id'])){
        $record = $SPIRAL->getRecordValue();
        $dataPATCH = array(
            RELATION_ID => $userData['item'][RELATION_ID]['value']['_id'],
        );
        $appInsert = $commonBase->apiCurlAction("PATCH","/apps/".APP_ID."/dbs/".DB_ID."/records/".$record['item']['_id'],$dataPATCH);
        if(isset($appInsert['item'])){
        	$SPIRAL->setTHValue("insert", true);
        }else{
			$SPIRAL->setTHValue("insert", "error");
			$SPIRAL->setTHValue("errorText", "登録に失敗しました。");
			// debug
			// $SPIRAL->setTHValue("errorText", print_r($appInsert,true));
        }
    }else{
        $SPIRAL->setTHValue("insert", "error");
        $SPIRAL->setTHValue("errorText", "登録に失敗しました。");
        // debug
        // $SPIRAL->setTHValue("errorText", print_r($userData,true));
    }
}


//------------------------------
// 共通用モジュール
//------------------------------

class CommonBase
{
	/**
	 * シングルトンインスタンス
	 * @var UserManager
	 */
	protected static $singleton;
    

	public function __construct()
	{
		if (self::$singleton) {
			throw new Exception('must be singleton');
		}
		self::$singleton = $this;
	}

	/**
	 * シングルトンインスタンスを返す
	 * @return UserManager
	 */
	public static function getInstance()
	{
		if (!self::$singleton) {
			return new CommonBase();
		} else {
			return self::$singleton;
		}
	}

    
	/**
	 * V2用 API送信ロジック
	 * @return Result
	 */
	function apiCurlAction($method, $addUrlPass, $data = null)
	{
        
		$header = array(
			"Authorization:Bearer " . API_KEY,
			"Content-Type:application/json",
			"X-Spiral-Api-Version: 1.1",
		);
		if(API_ROLE){
			$header = array_merge($header,array("X-Spiral-App-Role: ".API_ROLE));
		}

		// curl
		$curl = curl_init();
		curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
		curl_setopt($curl, CURLOPT_URL, API_URL . $addUrlPass);
		curl_setopt($curl, CURLOPT_HTTPHEADER, $header);

		if ($method == "POST") {
			curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "PATCH") {
			curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "DELETE") {
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		if ($method == "GET") {
			curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
		}
		$response = curl_exec($curl);
		if (curl_errno($curl)) echo curl_error($curl);
		curl_close($curl);

		return json_decode($response, true);
	}
}

APIにて取得する参照フィールドの識別名を設定する必要がありますが、
更新先は、取得元と同一カラムになるため、不要となります。

RELATION_ID
10行目
参照フィールドの識別名をセットしたPHP環境変数の変数名

最後に

ver.2.20 時点で、参照フィールドをサイト側から登録・更新できないための代替プログラムとなります。
SPIRAL ver.2 のアップデートによりサイト側で使用できるようになった場合、この記事は削除される可能性があります。ご了承ください。
設定後は動作確認を必ず行い、動作に問題がないか確認をしてください。
不具合やほかのやり方が知りたい等あれば、下記の「コンテンツに関しての要望はこちら」からご連絡ください。
コンテンツに関しての
要望はこちら