APIメソッドごとのサンプルコードまとめ　Express Email

この記事では Express Email のメソッドごとに、サンプルコードをまとめています。
SPIRAL ver.2 でAPIを使用する時の参考になれば幸いです。

APIメソッドごとのサンプルコードまとめ　Express Email

はじめに

この記事で紹介するサンプルコードでは、共通のcurl送信用モジュールを使用しています。
そのため、必ず下記のモジュールを記載するようにしてください。

※それぞれのメソッドのサンプルコードに「共通モジュール」の記載箇所が明記されていますので、そちらにこのモジュールを貼り付けてご使用ください。
※共通モジュールなので、APIメソッドを複数回実行する場合でも1回だけ記載すれば大丈夫です。
※APIメソッドを複数回実行する場合は、サンプルコードの「API実行」部分に適宜記述を追加してください。

共通モジュール

//------------------------------
// 共通モジュール
//------------------------------
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, $multiPart = null, $jsonDecode = null) {
        $header = array(
            "Authorization:Bearer ". API_KEY,
            "X-Spiral-Api-Version: 1.1",
        );
        if($multiPart) {
            $header = array_merge($header, array($multiPart));
        } else {
            $header = array_merge($header, array("Content-Type:application/json"));
        }
        if(APP_ROLE){
			$header = array_merge($header, array("X-Spiral-App-Role: ".APP_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") {
            if ($multiPart) {
                curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
            } else {
                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_POSTFIELDS, json_encode($data));
            curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
        }
        $response = curl_exec($curl);
        if (curl_errno($curl)) echo curl_error($curl);
        curl_close($curl);
        if($jsonDecode){
			return $response;
		}else{
            return json_decode($response, true);
		}
    }
}

設定値に関して

共通で使用する値に関しては、定数として初めに設定します。
具体的には下記のような値を設定してください。

API_URL	リクエスト先URLの固定部分です。固定値ですので特に変更する必要はありません。
API_KEY	発行したAPIキーを設定してださい。別途権限の付与が必要になります。
APP_ROLE	設定したアプリロールの識別名を入れてください。全権限の場合は値は空で大丈夫です。
DB_ID	レコード操作を行うDBのIDを設定してください。操作するDBが複数ある場合は「DB_ID_識別名」など適宜定数を追加してください。
APP_ID	レコード操作を行うDBがあるアプリのIDを設定してください。

設定値

define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

補足

define("API_KEY", $SPIRAL->getEnvValue("apikey"));

上記はAPIキーの記述を「PHP環境変数設定」を利用した場合のコードとなります。
このように定数を設定する時に、ver.2 機能の「PHP環境変数設定」を利用することで、
本番環境とテスト環境でキーが異なっていても、コードを書き換える必要がなく、保守性が高まります。
APIキーなど複数ページで使用するものは、環境変数設定をしておきましょう。

その他詳しくはサポートサイト「PHP環境変数」をご参照ください。

EXPRESSメール設定一覧取得メソッド

EXPRESSメール設定一覧取得を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$apiResponse = $commonBase->apiCurlAction("GET", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email");

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

補足

上記サンプルコードでは全件取得になっています。
クエリパラメータに検索条件を入れることで特定のメール設定のみ取得可能です。

// 検索例１）配信終了ステータスのEXPRESSメール設定のみ取得
$query = "?expressStatus=closed";

// 検索例２）件名が「サンプル」と部分一致するEXPRESSメール設定のみ取得
$query = "?subject=". urlencode("サンプル");

// リクエストするURL末尾に $query を追加
$apiResponse = $commonBase->apiCurlAction("GET", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email. $query");

上記検索例以外にも条件の設定が可能になっていますので、詳細はリファレンスをご確認ください。

EXPRESSメール設定作成メソッド

EXPRESSメール設定作成を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$emailData = array(
    "to"  => array("field" => "宛先メールアドレスのフィールドID"),
    "from" => array(
        "displayName" => "差出人名",
        "emailLocalPart" => "差出人メールアドレスのローカルパート",
        "emailFromDomainId" => "差出人メールドメインID"
    ),
    "subject" => array("content" => "メール件名"),
    "plainBody" => array("content" => "メール本文（プレーンテキスト）"),
    "timing" => "now or scheduled"
);
$apiResponse = $commonBase->apiCurlAction("POST", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/", $emailData);

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

補足

上記サンプルコードでは必須なもののみをリクエストに含めているため、
指定したDB全てのレコードに対して一斉配信を行うようになっています。
特定のレコードにのみ一斉配信したい場合は「to」以下に「where」を設定する必要があります。

「where」で簡易検索条件を指定した場合

$emailData = array(
    "to"  => array(
        "field" => "宛先メールアドレスのフィールドID",
        // 簡易検索条件でメールアドレスに値があるレコードにのみ配信するよう指定しています。
        "where" => array(
            "type" => "simple",
            "value" => array(
                "operator" => "or",
                "conditions" => array(
                    array("field" => "@宛先メールアドレスの識別名", "operator" => "is_not_null")
                )
            )
        )
    ),
    "from" => array(
        "displayName" => "差出人名",
        "emailLocalPart" => "差出人メールアドレスのローカルパート",
        "emailFromDomainId" => "差出人メールドメインID"
    ),
    "subject" => array("content" => "メール件名"),
    "plainBody" => array("content" => "メール本文（プレーンテキスト）"),
    "timing" => "now or scheduled"
);

「type」で「simple」を指定すると簡易検索条件を指定でき、
「advanced」とすると高度な検索条件を指定することが可能になります。
高度な検索条件を指定する場合は、サポートサイト「条件式や計算式の記法」をご参照ください。

メール文面の指定方法

$emailData = array(
    "to"  => array("field" => "宛先メールアドレスのフィールドID"),
    "from" => array(
        "displayName" => "差出人名",
        "emailLocalPart" => "差出人メールアドレスのローカルパート",
        "emailFromDomainId" => "差出人メールドメインID"
    ),
    "subject" => array("content" => "メール件名"),
    "plainBody" => array("content" => "メール本文（プレーンテキスト）"),
    "htmlBody" => array("content" => "<p>メール本文（プレーンテキスト）</p>"),
    "timing" => "now or scheduled"
);

サンプルコードでは「plainBody」にテキスト形式でメール文面を指定していますが、
「htmlBody」を指定するとHTML形式でメール文面を指定することができます。
このメソッドを実行する場合は少なくともどちらかでメール文面を指定する必要がありますのでご注意ください。

またメール文面を指定する際に、氏名などをレコードに登録されているデータで表示したい場合は「差し替えキーワード」を利用することが可能です。
記載する際のフォーマットなど詳細に関しては、サポートサイト「差し替えキーワード」をご参照ください。

配信タイミングの指定方法

$emailData = array(
    "to"  => array("field" => "宛先メールアドレスのフィールドID"),
    "from" => array(
        "displayName" => "差出人名",
        "emailLocalPart" => "差出人メールアドレスのローカルパート",
        "emailFromDomainId" => "差出人メールドメインID"
    ),
    "subject" => array("content" => "メール件名"),
    "plainBody" => array("content" => "メール本文（プレーンテキスト）"),
    // 予約配信を設定
    "timing" => "scheduled",
    "scheduleDate" => "2022-01-01T12:00:00Z",
    "status" => "ready"
);

「timing」に「now」を指定すると即時配信、「scheduled」を指定すると予約配信を設定できます。
予約配信を指定する場合は、合わせて「scheduleDate」で配信予約日時を指定する必要があります。

またサンプルコードでは「status」が未指定であるためデフォルトの「setting」になっており、
配信設定中の状態になりますが、「ready」とすることで設定完了状態に設定できます。
「ready」を指定して即時配信を設定すると、API実行後すぐに一斉配信が行われますのでご注意ください。

EXPRESSメール設定取得メソッド

EXPRESSメール設定取得を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$expressEmailId = "EXPRESSメールID";
$apiResponse = $commonBase->apiCurlAction("GET", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/". $expressEmailId);

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

EXPRESSメール設定更新メソッド

EXPRESSメール設定更新を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$expressEmailId = "EXPRESSメールID";
$emailData = array(
    "to"  => array("field" => "宛先メールアドレスのフィールドID"),
    "from" => array(
        "displayName" => "差出人表示名",
        "emailLocalPart" => "差出人メールアドレスのローカルパート",
        "emailFromDomainId" => "メール差出人ドメインID"
    ),
    "subject" => array("content" => "メール件名"),
    "plainBody" => array("content" => "メール本文（プレーンテキスト）"),
    "timing" => "now or scheduled"
);
$apiResponse = $commonBase->apiCurlAction("PATCH", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/". $expressEmailId, $emailData);

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

補足

EXPRESSメール設定作成メソッドと同様にリクエストを指定することができます。
作成メソッドとは異なり更新したい値のみリクエストに含めて実行することが可能です。

EXPRESSメール設定削除メソッド

EXPRESSメール設定削除を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$expressEmailId = "EXPRESSメールID";
$apiResponse = $commonBase->apiCurlAction("DELETE", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/". $expressEmailId);

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

補足

削除に成功した場合、レスポンスはありませんのでご注意ください。

テスト配信実行メソッド

テスト配信実行を実行したい場合には下記のサンプルコードを使用してみてください。

サンプルコード

<?php
//------------------------------
// 設定値
//------------------------------
define("API_URL", "https://api.spiral-platform.com/v1");
define("API_KEY", $SPIRAL->getEnvValue("apikey"));
define("APP_ROLE", "アプリロール識別名");
define("DB_ID", "DBID");
define("APP_ID", "アプリID");

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$expressEmailId = "EXPRESSメールID";
$destination = array(
    "to" => array("records" => array("送信先レコードID", "送信先レコードID", "送信先レコードID"))
);
$apiResponse = $commonBase->apiCurlAction("POST", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/". $expressEmailId. "/test", $destination);

//------------------------------
// 共通モジュール
//------------------------------
// ※こちらに「共通モジュール」を必ず記載してください。
?>

APIリファレンス

補足

テスト送信先のレコードIDは最大２０個まで指定することができます。
指定したレコードの中に存在しないレコードIDやメールアドレスがNULLのものなどが含まれているとエラーとなります。

ver.2 でPHPの実行結果を確認する方法

ver.2 では echo などの関数が使えないため、実行結果を確認するためには Thymeleaf を使用する必要があります。
はじめは分かりにくい部分ではありますので、初歩的な確認方法を以下で解説いたします。

1．ソース設定でフリーコンテンツブロックを作成して以下の Thymeleaf を記載してください。

<div>
    <div th:if="${cp.result.isSuccess}">
        <div th:text="${cp.result.value['API_RESPONSE']}"></div>
    </div>
    <div th:if="${!cp.result.isSuccess}">
        <div th:text="${cp.result.errorMessage}"></div>
    </div>
</div>

2．作成したブロックをページに追加してください。

3．ページの「PHP」タブにコードを記載し、コード内で実行結果を Thymeleaf に渡す記載をしてください。

例：特定のEXPRESSメール設定を取得するレスポンスを確認したい場合

//------------------------------
// API実行
//------------------------------
$commonBase = CommonBase::getInstance();

$expressEmailId = "EXPRESSメールID";
$apiResponse = $commonBase->apiCurlAction("GET", "/apps/". APP_ID. "/dbs/". DB_ID. "/express/email/". $expressEmailId);

// レスポンスを Thymeleaf に受け渡す
$SPIRAL->setTHValue("API_RESPONSE", $apiResponse);

上記ページを作成することで、ページURLを開くと実行結果を確認することができます。
ver.2 でPHPのデバッグをしたい場合などに活用してみてください。

開発情報・ナレッジ