カスタムAPI SPIRAL ver.2 サポートサイト

カスタムAPI

機能概要

ユーザがJSON形式で通信できる独自のAPIを作成できる機能です。
APIごとに一意のURLを発行し、リクエストを行うことで、ユーザ自身がPHPでカスタマイズした処理を実行できます。
この機能により、外部サービスとのWebhook連携が可能になり、エンジニアの実装工数を短縮することにも役立ちます。

作成したURLに対しIPアドレス制限や認証エリアによるアクセス制限をかけることができます。
またCROS設定よりアクセスを許可するオリジンなどの設定もできます。

機能仕様

URLフォーマット

https://{アカウント識別名}-{サイト識別名}.spiral-site.com/_program/{custom_api_name}

※サイト管理から作成したページなど内部からカスタムAPIにアクセスする場合は相対パスをご利用ください。

/_program/{custom_api_name}

利用可能なメソッド

GET、POST、OPTIONS
※POSTの場合ヘッダーのContent-Typeにapplication/jsonの指定が必要です。

設定上限

カスタムAPIはサイトごとの作成数に上限があります。
詳しくは各種上限値をご参照ください。

プログラミング言語

カスタムAPIに設定する言語は「PHP」です。
使用可能なPHPバージョンについてはPHPバージョンについてをご参照ください。
設定できる文字数は300,000文字です。

独自関数

カスタムAPIで使用できる独自関数を用意しています。
使用方法はこちらをご参照ください。

実行時間を制限

PHP実行開始から30秒以内に処理が完了しない場合、以下のエラーを返します。

Execution timeout expired.

その他のレスポンスに関してはこちらをご参照ください。

PHPの一部機能を制限

一部の関数、PHPクラス、およびパラメータについて、使用を制限しています。
制限している関数等については以下のリンク先をご参照ください。
PHP7.4で使用できない関数・PHPクラス・パラメータ一覧
 PHP8.1で使用できない関数・PHPクラス・パラメータ一覧

カスタムAPIではサイト管理のPHP環境変数に保存した値やサイトのPHPモジュールを呼び出すことができますが、

他のカスタムAPIやアプリのPHPモジュールは呼び出すことが出来ません。

アクセス数の制限

カスタムAPIへのアクセスはページのアクセス制限と共有されます。
上限値については各種上限値をご参照ください。

その他の制限

カスタムAPIでレコード登録/更新/削除を実行した場合は、実行先DBの非同期アクション(PHP実行アクション)は発動しません。

セキュリティ

カスタムAPIに対して、IPアドレス制限や認証エリアによるアクセス制限をかけることができます。
またCROS設定よりアクセスを許可するオリジンなどの設定もできます。

・設置認証エリア

　設定した認証エリア内からカスタムAPIにアクセスすることができます。
　1つのカスタムAPIに設定できる認証エリアは1つまでです。
　認証エリアはカスタムAPIを作成する時に設定できます。作成後の変更はできません。
　認証エリアの削除時に設置認証エリアを設定していたカスタムAPIも削除されます。

・クリックログイン経由アクセス

　設置認証エリアを設定している場合に設定できます。
　許可する場合は、クリックログインを許可している認証ページからもカスタムAPIにアクセスすることができます。

・IPアドレス制限

　カスタムAPIに対して、特定のIPアドレスからしかアクセスできないように制限します。
　外部アクセス制御で設定するIPアドレス制限とは別の制限です。
　外部アクセス制御で「本番環境アクセス制限」の「IPアドレス制限」を設定する場合は、
　外部アクセス制御のIPアドレス制限とカスタムAPIのIPアドレス制限の両方で許可されたIPアドレスからのみ当該カスタムAPIにアクセスできます。

・CORS設定

　アクセスを許可するオリジンを設定できます。

　「設定しない」を選択した場合、異なるオリジンからのリクエストをブロックします。

　同じオリジンからのリクエスト、またはURLへ直接アクセスする場合はCORS設定は不要です。

　「設定する」を選択した場合、以下の設定が可能です。

Access-Control-Allow-Origin	カスタムAPIにアクセスできるオリジンを設定します。以下のいずれかを選択できます。・一部許可　改行区切りで複数のオリジンを指定することができます。　設定例）https://www.example.com 　　　　　http://example.net:8080 ・すべて許可　どのオリジンからでもこのカスタムAPIへアクセスすることができます。
Access-Control-Allow-Headers	クライアントが送信できるHTTPヘッダを設定します。以下のいずれかを選択できます。・システムデフォルト（Content-Typeのみ）・カスタマイズ (一部許可) 　改行区切りで複数のヘッダを指定することができます。　設定例）X-Requested-With 　　　　　X-Custom-Header ・カスタマイズ (すべて許可) ※カスタムAPIのPOSTリクエスト時にはサービス側で常にContent-Typeを含めます。また、Access-Control-Allow-Headersの指定有無に関わらずCORSの標準仕様により以下のヘッダについては常に許可されます。・Accept ・Accept-Language ・Content-Language ・Range
Access-Control-Allow-Credentials	資格情報を含んだリクエストを許可します。 Cookie、Authorizationヘッダ、TSLクライアント証明書などの資格情報を含んだリクエストが必要な場合は「許可する」に設定してください。「Access-Control-Allow-Origin」または「Access-Control-Allow-Headers」が「すべて許可」に設定されている場合は設定できません。以下のいずれかを選択できます。・許可する・許可しない

Access-Control-Allow-Origin

カスタムAPIにアクセスできるオリジンを設定します。

以下のいずれかを選択できます。

・一部許可

　改行区切りで複数のオリジンを指定することができます。

　設定例）https://www.example.com
　　　　　http://example.net:8080

・すべて許可

　どのオリジンからでもこのカスタムAPIへアクセスすることができます。

Access-Control-Allow-Headers

クライアントが送信できるHTTPヘッダを設定します。
以下のいずれかを選択できます。

・システムデフォルト（Content-Typeのみ）

・カスタマイズ (一部許可)

　改行区切りで複数のヘッダを指定することができます。

　設定例）X-Requested-With
　　　　　X-Custom-Header

・カスタマイズ (すべて許可)

※カスタムAPIのPOSTリクエスト時にはサービス側で常にContent-Typeを含めます。
また、Access-Control-Allow-Headersの指定有無に関わらずCORSの標準仕様により以下のヘッダについては常に許可されます。
・Accept
・Accept-Language
・Content-Language
・Range

Access-Control-Allow-Credentials

資格情報を含んだリクエストを許可します。

Cookie、Authorizationヘッダ、TSLクライアント証明書などの資格情報を含んだリクエストが必要な場合は「許可する」に設定してください。

「Access-Control-Allow-Origin」または「Access-Control-Allow-Headers」が「すべて許可」に設定されている場合は設定できません。

以下のいずれかを選択できます。
・許可する

・許可しない

通知メール

カスタムAPIの実行失敗時にメールアドレス宛に通知メールを配信できます。
通知に必要なユーザの権限や設定方法は通知メール設定をご確認ください。

独自関数

以下はカスタムAPIの独自の関数です。
カスタムAPIのPHPプログラム内でのみ使用できます。

関数	説明
getCustomApiRequestBody()	リクエスト本文の連想配列を返します
getCustomApiQueryParameters()	クエリパラメータの連想配列を返します
setCustomApiResponse($param)	設定した内容に基づいて使用するJsonオブジェクトとして応答します

使用例

<?php
// Get the request body
$requestBody = $SPIRAL->getCustomApiRequestBody();

// Get query parameters
$queryParams = $SPIRAL->getCustomApiQueryParameters();

// Process the request and prepare response
$responseData = [];
$responseData['requestData'] = $requestBody;
$responseData['queryParams'] = $queryParams;
$SPIRAL->setCustomApiResponse($responseData);
?>

レスポンス例

成功

statuscode	Response body	説明
200	{ "status": "success", "data": { "id": 1, "name": "test" } }	レスポンスにはsetCustomApiResponse()関数を使用して設定されたデータが含まれる

カスタムAPIのエラー

statuscode	Response body	説明
200	{ "status": "failed", "errorMessage": "forbidden" }	IP/ドメインが許可されていない ※ページへのIPアドレス制限、サイトの本番環境アクセス制限などによるIP制限の場合は403エラー
200	{ "status": "failed", "errorMessage": "unauthorized" }	クリックログイン経由アクセスが許可されていない
200	{ "status": "failed", "errorMessage": "invalid json" }	リクエスト本文がJSON形式ではない
200	{ "status": "failed", "errorMessage": "undefined variable: test on line 2" }	PHP コードの実行に失敗した
200	{ "status": "failed", "errorMessage": "execution timeout expired" }	PHPタイムアウト（30秒）

その他のエラー

statuscode	Response body	説明
400	{ "status" : 400, "message" : "content-type not allowed" }	content-type に application/json 以外が含まれている
404	{ "status" : 404, "message" : "domain not exist" }	ドメインが存在しない
405	{ "status" : 405, "message" : "method not allowed" }	許可していないメソッドを指定した
429	{ "status" : 429, "message" : "too many request" }	リクエスト回数の上限に達した

UI：新規作成

サイト管理の左メニューから「カスタムAPI」を選択、「＋」ボタンをクリックします。

表示された新規作成モーダルに必要事項を入力し、「作成」ボタンをクリックします。

※認証エリアはカスタムAPI作成時のみ設定可能です。作成後の変更はできません。

カスタムAPI一覧に追加されます。

UI：詳細/変更/削除

カスタムAPI一覧から詳細を確認したい識別名または「︙」をクリックします。

こちらから変更/削除も行えます。

カスタムAPIのURL

詳細画面の上部より確認できます。

・テスト環境

・本番環境

※本番環境へリリース後に確認できます。

PHP

PHPソースコードやPHPバージョンを確認/変更できます。

セキュリティ

セキュリティに関する設定を確認/変更できます。

基本設定

表示名、識別名、説明などの確認/変更ができます。

変更/削除後の内容を本番環境に適用させる場合はリリースしてください。
リリースの詳細はこちらをご参照ください。

テスト環境でのテスト方法

テスト環境でのテスト方法について、以下の例をご紹介します。

例１．ブラウザからカスタムAPIのURLにアクセスする

　　　管理画面のログインセッションがある状態でカスタムAPIのURLをクリックします。

例２．外部アクセス制御を使用してJavaScriptやPHPからカスタムAPIにリクエストする

　　　例ではBasic認証アクセスを設定し、指定した環境内からカスタムAPIを実行します。

例１．ブラウザからカスタムAPIのURLにアクセスする

１．カスタムAPIを設定します。

２．PHPソースコードに以下を設定します。

<?php
$responseData = [];
$responseData['id'] = 1;
$responseData['name'] = "test";
$SPIRAL->setCustomApiResponse($responseData);
?>

３．管理画面へログインし、ログインセッションがある状態でカスタムAPIのURLをクリックします。
４．レスポンスが返ってきます。

{
"status": "success",
"data": {
"id": 1,
"name": "test"
}
}

例２．外部アクセス制御を使用してJavaScriptやPHPからカスタムAPIにリクエストする

１．カスタムAPIを設定します。
　　※異なるオリジンからリクエストする場合、CROS設定でOriginとHeadersを一部許可または全て許可に設定します。

２．外部アクセス制御よりBasic認証アクセスを設定します。
３．外部サーバよりカスタムAPIをリクエストヘッダーに設定しリクエストします。

JavascriptでカスタムAPIをリクエストする方法の例

※テスト環境の場合ヘッダーのAuthorizationに認証情報の指定が必要です。

<script>

// Setup username and password
const username = 'User1111';
const password = 'User123!@#';

// encoded username and password using javascript function btoa()
const token = btoa(`${username}:${password}`);

const xhr = new XMLHttpRequest();

// Read api request on loading page
xhr.onload = function() {
if(xhr.readyState === 4) {
if(xhr.status === 200) {
const data = JSON.parse(xhr.responseText);
alert('Success');
} else {
alert('Error loading data. Please check your credentials.');
}
}
};

// Specify method GET and URL of custom api
xhr.open('GET', 'カスタムAPIURL', true);

// Include header 'Authorization' and value token
xhr.setRequestHeader('Authorization', `Basic ${token}`);
xhr.send();
</script>

４．リクエスト後のレスポンスを確認します。

　　3の例ではJavascriptを設定したページでアラートのメッセージ「Success」が表示されます。
　　ブラウザの開発者ツール等を使用し、リクエストヘッダーからbasic認証が正しく設定できているか確認できます。