ver.1サポートサイト


スパイラルAPIの使い方

最終更新日:2023年10月31日

スパイラルAPIとは

スパイラルは登録データから一覧表・単票や集計表、グラフを作成、表示するWebパーツ機能を備えています。

スパイラルAPIでは、各Webパーツ機能で設定したロジックを適用してデータを取得でき、データの利用側で制御せずにCMSやSNS、スマートフォンで表示することが可能です。

また、認証に関しても、SPIRALの認証機構「マイエリア」の設定を利用することが出来ます。

 

 

スパイラルAPIを利用することで、SPIRALに設定済みのWebコンポーネントやDBにアクセスして情報の出し入れや、メール配信操作、マイエリアによる認証処理などを利用することが出来ます。
例えば、SPIRALへ外部システムからアクセスすることが可能になり、会員や顧客の大切な個人情報を安全なSPIRALのDBに預け、管理しやすくなります。

また、APIを通して、SPIRALで設定したWebコンテンツを外部システムに出力したり、外部システムからメール配信操作を実行したりといった機能を活用し、柔軟なアプリケーション構築が可能になります。

1.スパイラルAPI共通仕様

通信方式

HTTPS（メソッド：POST）

データフォーマット

リクエスト、レスポンスともにJSON形式

文字コード

UTF-8

認証

すべてのAPI（locator/apiserverメソッドは除く）のリクエストについて、APIトークンおよびAPIトークンシークレットを用いた認証

（内部呼出しの場合、スパイラル内部で認証処理を行うため、APIトークンとAPIトークンシークレットをプログラム上に記述する必要はありません）

URL

ご利用のアカウントによってAPIをリクエストするURLが異なります。リクエスト先URLはAPIトークン画面でご確認いただけます。

（内部呼出しの場合、スパイラル内部でリクエスト先を指定するため、URLをプログラム上に記述する必要はありません）

 

locator（ロケータ）について

スパイラルのアカウントによって、APIリクエスト先のURLは異なる場合があります。
URLは、操作画面で確認できるほか、locator（ロケータ）APIを利用して取得することも可能です。アプリセンター経由で他アカウントへアプリを渡すことを想定しているなどの場合は、APIリクエスト先URLを直接プログラムに記述する代わりに、ロケータAPIでURLを取得することをおすすめします。

locator（ロケータ）について詳しくは、下記をご参照ください。

 

関連ページ

・APIリファレンス（ロケータ）

・サンプルプログラム（API）＞ロケータ（PHP）- file_get_contents()を使う

・サンプルプログラム（API） ＞ロケータ（PHP）- cURLライブラリを使う

2.リクエスト数と実行時間の制限

リクエスト数の制限

APIリクエスト数は標準設定で1分間あたり10リクエストまで可能です。

 

初回リクエストから1分間あたりのリクエスト数でカウントします。
APIリクエスト数の制限は、操作画面から変更いただけます（オプション）。

変更方法は、APIリクエスト上限をご参照ください。 また、オプション価格についてはオプションページをご参照ください。

なお、locator（ロケータ）API実行リクエストは、600回/分のリクエストにふくまれません。

実行時間の制限

1リクエストあたりの実行時間は10秒の制限があります。

レスポンスを受け取るまでに10秒以上の時間がかかると、処理が中断してエラーとなります。

実行時間の制限は変更できません。

※「logs/deliver」メソッドの場合は、5秒の制限です。

3.APIの外部呼出しとは

外部呼出しとは、スパイラル内からPHPプログラムを使ってAPIを実行する内部呼出しに対して、スパイラル外のシステムからAPIを呼び出す場合に利用することを指します。
以下の特徴があります。

 

・HTTPS通信のできる任意のプログラミング言語で利用可能。

・APIトークン、APIシークレットから算出するパスキー、リクエストの署名の3つの機構でAPI呼び出しの安全性を確保。

 

APIトークンとAPIトークンシークレット

外部環境や他のスパイラルアカウントなどから外部呼出しでAPIリクエストを実行する場合は、あらかじめSPIRALの管理画面上でトークンを発行する必要があります。

トークンとトークンシークレットの組み合わせは複数発行することが出来ます。

トークン発行方法については、APIトークンをご参照ください。
また、APIタイプ別に利用制限をかけることも可能ですので、必要に応じて使い分けるようにして下さい。

 

APIトークン

APIトークンは、APIを利用する際に必要なユーザを特定するための文字列で、 通信のパラメータとして必ず送信する必要があります。

 

APIトークンシークレット

APIトークンのシークレットは、リクエスト時、通信データのメッセージ認証コード（HMAC）を生成するために使用し、暗号で例えると公開鍵の役割を果たします。

 

※パラメータは、利用するAPI機能により異なります。 詳細はAPIリファレンスを参照してください。

4.APIのリクエスト方法（外部呼出しの場合）

リクエスト時のHTTPヘッダに、Content-Typeと、利用したいAPIメソッドをX-SPIRAL-APIへ指定します。

Content-Type: application/json;charset=UTF-8
X-SPIRAL-API: area/login/request

リクエストのボディには各メソッドに応じたパラメータをJSONデータとしてPOSTするようにします。

なお、JSONデータにはAPIトークン・パスキー・APIトークンシークレットを用いた署名の3つのパラメータを必ず含める必要があります。

上記の例では、 area/login 部分がAPIメソッドに相当しており、マイエリア機能（area）のログインメソッド（login）をリクエストしています。

{
'spiral_api_token': '0123456......abcdef',
'passkey': '1256342400',
'signature': '987abc......def012',
(略)
}
パラメータ 説明 文字種長
spiral_api_token SPIRALの管理画面で発行したAPIトークン 半角英数字
passkey APIリクエスト時刻のエポック秒 int
signature spiral_api_tokenとpasskeyを&でつなげた文字列をAPIトークンシークレットを用いて
hmac-sha1によりハッシュ化して生成された署名。署名の有効期間は、passkeyに指定されたエポック秒から15分間となります。		 半角英数字

APIメソッドに合わせてJSONフォーマットでAPIをリクエストすることで、レスポンスがJSONデータで返ってきます。

以下に実際のリクエスト・レスポンスの例を示します。

 

リクエスト
POST /api/service/ HTTP/1.1 X-SPIRAL-API: area/login/request Content-Type: application/json; charset=UTF-8   {'spiral_api_token':'00000000aaaaaaaaaabbbbbbbbbbccccccccccdddddddddddeee','passkey':'1366375090','signature':'0000ffc6e281f9e128538e1d05b947405421b99c','my_area_title':'my_area01','id':'suzuki.taro','password':'hogehoge'}
レスポンス
200 OK Date:  Fri, 19 Apr 2013 12:38:26 GMT Server:  Apache X-SPIRAL-API:  area/login/response Keep-Alive:  timeout=15, max=100 Connection:  Keep-Alive Transfer-Encoding:  chunked Content-Type:  application/json;charset=UTF-8   {"message":"OK","jsessionid":"000000009B838604C8A49DE200000000","code":"0","url":"https://beta.smp.ne.jp/area/servlet/area.MyPageBundle;jsessionid=000000009B838604C8A49DE200000000?MyPageID=999efb02_qh7milh7m2l0000"}

具体的なリクエスト方法については、サンプルプログラムをご参照ください。

 

ファイル型などバイナリデータを含む場合

通常のAPIのリクエストでは、上記のようなシングルパートのリクエスト方法で問題なく動作します。

ただし、data/insertやcustom_module/uploadなどのメソッドで、リクエストにファイル型などのバイナリデータを含むAPIメソッドを実行する際には、以下のようにマルチパート形式のフォーマットを使ってAPIをリクエストする必要があります。

 

・マルチパート形式を必ず利用

　※アカウント内にて内部呼出しでAPIを実行する際は、シングルパート形式でリクエストします。

・改行コードはCRLF

・ファイル型フィールドのタイトルはJSONでの指定は不要

 

HTTPヘッダ

Content-Type: multipart/form-data; boundary="xxxxxxxxxx_MULTIPART_BOUNDARY"
X-SPIRAL-API: 機能名/メソッド名/request

HTTPボディマルチパートのそれぞれのデータの境界を示すために必要となる任意のboundary文字列（この例では xxxxxxxxxx_MULTIPART_BOUNDARY）を決めて、上記のようにヘッダに指定します。





--xxxxxxxxxx_MULTIPART_BOUNDARY
Content-Type: application/json;charset="UTF-8"
Content-Disposition: form-data; name="json"
{
'spiral_api_token': '0123456......abcdef',
・・・
}
--xxxxxxxxxx_MULTIPART_BOUNDARY
Content-Type: application/octet-stream;
Content-Disposition: form-data; name="file01"; filename="ファイル01.png"
（ファイルのバイナリデータ）
--xxxxxxxxxx_MULTIPART_BOUNDARY--




1行目や8行目のように各パートの先頭行に–に続けてboundary文字列を指定します。


2行目〜7行目がJSONパート（そのうちの4〜7行目がJSONデータ）で、9行目〜11行目がファイルパートになります。


10行目では、nameにフィールドタイトルを、filenameにファイル名をそれぞれ指定しています。


 


関連ページ


・サンプルプログラム


・サンプルプログラム（API）＞マルチパート形式（PHP）


5.APIの内部呼出しとは


内部呼出しとは、スパイラル外のシステムからAPIを呼び出す外部呼出しに対して、スパイラル内からPHPプログラムを使ってAPIを実行することを指します。

以下の特徴があります。


 


・スパイラルのフォーム、マイページ、カスタムプログラム等からAPIを呼び出す場合に利用できます。


・アカウント内APIを使って簡単にDB操作やメール配信を行うことができます。


・APIコミュニケータを使って各種APIを呼び出すことができます。


 




 


スパイラル内部からであっても、外部呼出しと同じ方法でAPIリクエストを送信することも可能ですが、アカウント内APIを利用することにより、APIトークンおよびAPIシークレットを記述することなく簡易にAPIを実行できます。

なお、スパイラル内部でPHPを利用する際には、マニュアルを参照ください。


6.APIのリクエスト方法（内部呼出しの場合）


アカウント内API


スパイラルの同じアカウント内にて内部呼出しでAPIを利用するには、スパイラル操作画面からアカウント内APIの設定を「ON」にしてください。

アカウント内APIを「ON」にすると、アカウント内のPHPに対応したページであればAPIトークンやAPIトークンシークレットを使用せずにAPIを使用できます。

アカウント内APIを使用せず、APIトークンやAPIトークンシークレットを指定してスパイラルアカウント内からAPIをリクエストすることもできますが、通常はアカウント内APIを利用することを推奨します。


ただし、アカウント内APIはマルチパート形式での送信に対応しておりません。


ファイル型フィールドにファイルを登録する場合など、マルチパート形式での送信が必要な、リクエストにバイナリデータを含むAPIメソッドを実行する際には、外部呼出しと同じ方法でAPIリクエストを送信してください。


 


具体的なリクエスト方法については、サンプルプログラムとスパイラルPHPをご参照ください。


関連ページ


サンプルプログラム


7.APIタイプ


スパイラルAPIでは複数のタイプのAPIメソッドが提供されています。

認証が必要なハイレベルAPIとより自由度の高いローレベルAPIに大きく分けることが出来ます。

オープンAPIも含めて、それぞれのタイプごとにAPIの特徴があります。


ハイレベルAPI


SPIRALのWebコンポーネントをプロキシー（代理人）を使って操作し、ブラウザへのHTMLでの出力の代わりに、JSONとして出力する仕組みです。


各Webコンポーネントが配置されているマイエリアにログインし、認証後のセッションIDを使って、各コンポーネントにアクセスします。

マイエリア設定が必須です。また、一覧表・単票などを使用する場合は操作画面であらかじめ設定を行います。

検索できるフィールドや取得するフィールドなど、データのアクセス範囲を操作画面側で制限することができます。


マイエリア認証、一覧表、集計表のAPIがあります。


ローレベルAPI


SPIRAL Webコンポーネントの裏側の機能（DB、メール配信機能等）を直接操作します。


セッションIDは不要です。


外部呼出しの場合または内部呼出しでアカウント内APIがOFFの場合は、APIトークンおよびシークレットで、アカウント内のデータにアクセスします。




内部呼出しでアカウント内APIがONの場合は、APIトークンおよびシークレットを使用せずにアクセスできます。


クライアントプログラムだけでDB操作や配信操作ができるため、柔軟性および開発生産性に優れています。

その分、APIトークンとシークレットの厳格な管理が望まれます。


DB、DBフィルター、エクスプレス２配信、サンクス配信、カスタムプログラム等のAPIがあります。


オープンAPI


スパイラル内に設置したカスタムプログラムを、APIトークンのみで外部から実行できるよう設定できます。

JavaScriptなどで比較的簡単に実行できますが、パラメータに個人情報など重要な情報を付与しないようにします。

オープンAPIの設定方法はカスタムプログラムでのPHP利用の「オープンAPIとして利用する」と、オープンAPIのリファレンスをご覧ください。


 







ハイレベル
ローレベル
オープン




仕組み
プロキシー型
直接型
カスタムプログラム経由




セッション
マイエリア認証のセッションIDが必要
無し。ステートレス
無し。ステートレス




認証
APIトークン + シークレット

+ マイエリアログインID

+ マイエリアパスワード		
APIトークン + シークレット
APIトークン （カスタムプログラム次第）




データ

アクセス範囲		
マイエリア認証により許可された範囲
データベース操作、データベース内の全データ

配信操作、配信ログ		
カスタムプログラムで制御




処理設定・

制御方法		
マイエリア（必須）+ 一覧表・単票や集計表 + クライアントプログラム
クライアントプログラム
カスタムプログラム




利用用途
第三者に配布されるフロントエンド（スマホ等）との連携
サーバーサイド等の自社プログラムとの連携
JavaScript等から

GETパラメータによる簡易な連携（特に一般公開できる情報）		






8.APIメソッド


スパイラルAPIには様々なメソッドが用意されています。

それぞれのAPIの詳細に関しては、APIリファレンスを参照して下さい。


9.エラーコード・演算子など


APIのエラーコード、演算子やパラメータ指定の仕様については、下記をご参照ください。


 


・エラーコード


・比較演算子


・抽出ルール条件式


・DB作成仕様


・一覧表の検索オプション値


・DB作成時のトリガー設定


 


レスポンスのcodeプロパティについて


APIレスポンスのcodeプロパティが0の場合は正常終了ですが、0以外の場合は何らかのエラーが発生しています。


各々のエラー詳細については、エラーコード表を参照してください。


 


正常終了時の応答サンプル（JSON）




{
"message": "OK",
"count": "2",
"data": [
["suzuki@example.com", "テキストエリア"],
["yamada@example.com", "テキストエリア２"]
],
"code": "0",
"header": ["メールアドレス", "テキストエリア"]
}




エラー終了時の応答サンプル（JSON）




{
"message": "Requested data not found",
"code": "203"
}




エラー判定を行うサンプルコード（PHP）




<?php
/ / ・・・中略・・・
$response = curl_multi_getcontent($curl);
curl_close($curl);
$result = json_decode($response, true);
($result["code"] == 0) or die("API呼び出しでエラー発生\n");
/ / ・・・中略・・・
?>




10.APIの利用例


例1. CMSとスパイラルを連携して会員サイト構築


 




 


スパイラルとCMSをAPIで連携して会員サイトを構築。

スパイラルを利用して、会員登録、登録情報の変更、会員ページへのログインなど、会員管理の仕組みを自由に設計・構築できます。会員情報はスパイラルで安全に管理し、コンテンツ管理はCMSを利用することで、会員認証やメール配信を組み込んだ会員サイトを構築することができます。


 


例2. CMSとスパイラルを連携して複雑な業務アプリケーションを構築


 




 


スパイラルとCMSをAPIで連携して、CMSだけでは構築が難しかった複雑な業務アプリケーションを自由に構築。

例えば、顧客管理システムの場合、スパイラルAPIによるDB操作、配信操作を組み込むことで、システムへのログイン、顧客情報や対応履歴の登録・更新・削除、顧客へのメール配信などを実装した独自のシステムを構築できます。


さらに、顧客管理システムからスパイラルの安全なDBから顧客情報を取得し、メーラーのインターフェースのような操作感覚でメールを送れるようにするなど、クライアントの運用に合わせたUIを開発することも可能です。


 


例3. 成約につなげる行動ターゲティングメール


 




 


自動車販売店では、試乗目的で来店したお客様にメールマガジンの会員登録を促し、新型車の情報やキャンペーン情報を配信していることがあります。


メールマガジンの目的は見込客を成約客に育てることですが、メールから誘導したページの閲覧状況など、アクセス解析データを取得していても、データの分析や充分なフォローにはなかなか手が回りません。


スパイラルのオープンAPI、カスタムプログラムを使えば、一般的なアクセス解析データを取得するだけでなく、メールマガジン会員が閲覧したWebページに合わせてターゲティングメールを送ったり、購入確度の高いお客様が良く閲覧するページを閲覧した場合、営業へ電話アプローチを促す通知メールを送ったりすることができます。


簡単なルールを定め、カスタムプログラムで実装するだけで、成約につなげる施策を実施できます。