テスト環境のカスタムAPIに外部から接続テストを行うサンプル

ver.2.35でリリースされたカスタムAPI機能を利用して開発を行う際、
Basic認証を利用する事で外部環境からでもテスト環境に接続を行い、デバッグすることが可能です。
本記事では、Basic認証を利用したデバッグ方法を解説します。
※特定IPアドレス制限を利用する場合はBasic認証の設定は不要です。

注意点

・接続時の認証情報は厳重に管理してください。
・テスト時のレスポンスの取り扱いには十分注意し、本番リリース時の情報漏洩に気を付けましょう。

全体像

今回のサンプルでは、入力値をinputTextとして送信し、valueが「hoge」であるかを判定するシンプルな検証をしています。
以下の３つの主要なパートで構成されています。

・検証用:POSTMAN POSTリクエストが簡単に行えるソフトを使用し、手軽にリクエスト/レスポンスを検証します。
・検証用:curl ターミナルやコマンドプロンプトからcurlコマンドを実行してリクエスト/レスポンスを検証します。
・検証用:JavaScript JavaScriptを利用して、ブラウザからリクエストを送信し、レスポンスを検証します。

カスタムAPI設定

サイトの管理画面などでカスタムAPIの設定を行い、以下のPHPコードを利用することで、入力値の検証用APIを構築できます。
必要に応じて、認証処理やデータベース連携などの機能を追加し、セキュアかつ柔軟なシステムに仕上げてください。
本記事では機能は割愛しますが、入力値の検証とエラーハンドリングを行う例を示します。

カスタムAPIコード例

【PHP】

<?php
// カスタムAPI用のPHPコード例

// リクエスト本文（JSON）を連想配列として取得
$requestBody = $SPIRAL->getCustomApiRequestBody();

// 入力値は「inputText」というキーで送信される前提です
if (!isset($requestBody['inputText'])) {
    $SPIRAL->setCustomApiResponse([
        'status' => 'failed',
        'errorMessage' => 'inputTextパラメータが存在しないか形式が不正です'
    ]);
    return;
}

$inputText = $requestBody['inputText'];

// 検証対象の値（例として "hoge" を使用）
$checkValue = "hoge";

// ここでは、入力値と定義値の一致を検証します。
// 実際には、データベース照合や外部APIとの連携も可能です。
if ($inputText === $checkValue) {
    $SPIRAL->setCustomApiResponse([
        'status' => 'success',
        'inputText' => $inputText
    ]);
} else {
    $SPIRAL->setCustomApiResponse([
        'status' => 'failed',
        'errorMessage' => '照合エラー'
    ]);
}
?>

検証用フロントエンドコード例

外部環境からの接続想定として、POSTMAN、curl、JavaScriptの例を紹介します。
【フロント：POSTMAN】

① 新規リクエストの作成
Postmanを起動し、「New Request」をクリック。リクエスト名やコレクションを設定します。
② リクエストの設定
HTTPメソッドを「POST」に設定し、URL欄に
https://{アカウント識別名}-{サイト識別名}-test.spiral-site.com/_program/{custom_api_name}
を入力します。
③ Authorizationの設定
「Authorization」タブを選択し、Type のドロップダウンから Basic Auth を選びます。
Username と Passwordに認証情報を入力してください。
④ Headersの設定
「Headers」タブで、Content-Type: application/json を追加します。
※ Basic認証情報は自動で Authorization ヘッダーに付与されます。
※ すでに追加されている場合は別途追加は不要です。重複しないようにしてください。
⑤ Bodyの設定
「Body」タブをクリックし、「raw」を選択。右側のドロップダウンから JSON (application/json) を選び、以下のJSONデータを入力します。
```
{
  "inputText": "hoge"
}
                        
```
⑥ リクエストの送信
設定内容を確認後、「Send」ボタンをクリックし、APIからのレスポンスを確認します。

【フロント：curl】

curl -X POST -u Username:Password \
     -H "Content-Type: application/json" \
     -d '{"inputText": "hoge"}' \
     https://{アカウント識別名}-{サイト識別名}-test.spiral-site.com/_program/{custom_api_name}

Username:Password には、Basic認証のユーザー名とパスワードを入力してください。

【フロント：JavaScript】

document.addEventListener('DOMContentLoaded', function() {
    fetch('https://{アカウント識別名}-{サイト識別名}-test.spiral-site.com/_program/{custom_api_name}', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Basic ' + btoa('Username:Password') //直接記載するとパスワードが漏洩するのでinput値等から取得するようにしてからお使い下さい。
        },
        body: JSON.stringify({ inputText: 'hoge' })
    })
    .then(response => {
        if (!response.ok) {
            throw new Error('HTTP error! Status: ' + response.status);
        }
        return response.json();
    })
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));
});

外部ページからJavaScriptで実行する場合、
Access-Control-Allow-OriginとAccess-Control-Allow-Headersの設定項目についてアクセス元となる外部ページの情報を設定する必要があります。
Access-Control-Allow-Originは、アクセス元のURLを指定します。
Access-Control-Allow-Headersは、リクエストヘッダーにBasic認証の認証情報が必要ですのでAuthorizationを指定してください。
詳しいカスタムAPIの設定については、こちらを参照してください。

Username:Password には、Basic認証のユーザー名とパスワードをinput等閲覧者に入力して頂いた内容を反映するように修正してください。

最後に

上記のコード例を元に、シンプルな入力値検証システムをテストできます。
実運用では、セキュリティ対策やエラーハンドリング、データベース連携などの機能を追加することで、より堅牢なシステムへと発展させることが可能です。
本記事が、カスタムAPIや非同期通信の理解にお役に立てば幸いです。

不具合やご質問がある場合は、下記の「コンテンツに関しての要望はこちら」からご連絡ください。

開発情報・ナレッジ

注意点

全体像

カスタムAPI設定

カスタムAPIコード例

検証用フロントエンドコード例

最後に

関連記事