Python、Node.js、PHPでバイオメトリック・コールバック受信機を構築する
コールバック受信機とは、指紋、顔、またはカードによるスキャンのたびに、それをお使いのシステム内のレコードに変換する小さなコードのことです。Cams Biometrics Gatewayは、検証済みの各スキャンをJSONリクエストとしてお客様のサーバーに送信し、サーバーは受信を確認する応答を返します。この受信機をゼロから作成する必要はありません。Camsは、Python、Node.js、PHP向けのAIコード生成プロンプトを提供しています。プロンプトをClaudeやChatGPTなどのAIアシスタントに貼り付けると、コールバック受信機、RESTfulクライアント、テスト用インターフェースを含む、そのまま動作する完全なファイルが得られます。このチュートリアルでは、受信機が果たすべき役割、使用する言語向けの生成方法、設定方法、そして本番稼働前のテスト方法について説明します。
01 · 6つの役割
コールバック受信機の役割
使用する言語にかかわらず、すべてのバイオメトリック・コールバック受信機は同じ6つの役割を果たします。これらは、生成されたコードを確認する際のチェック項目にもなります。
| 役割 | 内容 | 重要な理由 |
|---|---|---|
| 1. リクエストを受け付ける | 生のJSON本文を含むHTTP/HTTPSのPOSTを受信する | Gatewayが各イベントを配信する方法です |
| 2. トークンを検証する | AuthTokenを、想定されるコールバック用トークンと照合する | 第三者がお客様のURLに不正な勤怠データを送信することを防ぎます |
| 3. イベントの種類ごとに振り分ける | RealTime内にあるキーを確認し、それに応じて処理する | すべてのコールバックが打刻とは限りません。写真やユーザー情報の変更を通知するものもあります |
| 4. 重複を除外する | OperationIDを使用して、保存済みのイベントを無視する | 同じイベントが再送されても、レコードが二重に作成されることはありません |
| 5. 保存しログを記録する | 必要なフィールドを保存し、すべてのコールバックを記録する | HRMS、給与計算、ダッシュボードで使用されるレコードを作成します |
| 6. 完了を返信する | HTTP 200で {“status”:”done”} を返す | イベントが正常に受信されたことをGatewayに伝えます |
02 · データを理解する
受信するペイロード
最も一般的なコールバックは、スキャンのたびに送信される打刻ログです。このサンプルをsample.jsonとして保存してください。後で受信機のテストに使用します。
|
Callback API、受信機に送信されるPunchLogリクエスト {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
受信機は、コールバックを処理した後、HTTP 200とともに、以下の本文をそのまま返す必要があります。
|
Callback API、受信機が返す必要のある応答 { "status": "done" } (HTTP 200)
|
コールバックのイベント種類
すべてのコールバックはRealTimeオブジェクト内に届きます。受信機は、以下のキーのうちどれが存在するかを確認して処理を決定します。
| RealTime内のキー | 通知内容 |
|---|---|
| PunchLog | 勤怠スキャン:誰が、出勤か退勤か、いつ、どの方法で行ったか |
| UserUpdated | デバイス上でユーザーの詳細情報が更新された |
開発者が見落としやすい2つの点
| 項目 | 注意点 |
|---|---|
| 応答のキーは小文字です | 小文字のstatusに、値doneを設定して返してください。RESTful APIの応答にある先頭大文字のStatusフィールドをコピーしないでください |
| LogTimeの形式 | LogTimeは2020-09-17 07:48:22 GMT +0530のような形式です。デバイスのオフセットを含む実際のスキャン時刻です。オフセットを考慮して解析し、勤怠時刻として使用してください |
03 · コードはAIに作成させる
AIコード生成プロンプトで受信機を生成する
Camsは、対応するサーバー言語ごとに、そのまま使えるプロンプトファイルを公開しています。各プロンプトには、Cams Web API 3.0仕様の概要と、構築すべき内容に関する明確な指示が含まれています。プロンプトをAIアシスタントに貼り付けると、アシスタントがお使いの環境向けに、単一ファイルで完全な実装を生成します。
|
プロンプトファイルをダウンロードする 次のセクションで言語を選択し、.txt形式のプロンプトファイルをダウンロードしてください。 |
|
|
AIアシスタントに貼り付ける Claude、ChatGPT、Copilot、またはその他のAIコーディングツールを開き、プロンプトの内容全体を貼り付けてください。 |
|
|
そのまま動作する完全なファイルを入手する AIが単一のファイルを生成します。設定値を入力し、デプロイして実行してください。 |
| 生成される各ファイルの内容 | 機能 |
|---|---|
| コールバック受信機 | 生のPOST本文を読み取り、AuthTokenを検証し、イベントの種類ごとに振り分け、すべてのコールバックを記録し、打刻ログを保存し、勤怠写真を保存して、doneを返信します |
| RESTfulクライアント | 汎用のリクエスト関数と、AddUser、DeleteUser、ResendAllUser、UpdateAccessTimeなど、27種類のRESTful操作すべてのラッパー関数 |
| HTMLテストインターフェース | 設定項目、操作のドロップダウン、リクエストテンプレートが事前入力されたJSONエディター、応答ビューアー、最近のコールバック一覧を備えたブラウザーページ |
|
まずはホスティングされたドキュメントを確認してください 各プロンプトは、AIに対して、操作、JSONスキーマ、フィールド名、応答コードの正式な情報源として、Cams Web APIの完全なドキュメントを読み込むよう指示します。プロンプトの概要とホスティングされたドキュメントに相違がある場合は、ドキュメントが優先されます。 |
04 · 言語を選択する
Python、Node.js、PHP向けのプロンプト
各プロンプトは、それぞれの言語で依存関係を最小限に抑えた、慣用的なコードを生成するように調整されています。
|
|
|
プロンプトは、Minimal APIを使用したC# (.NET 8)、組み込みのHttpServerを使用し依存関係のないJava、net/httpと標準ライブラリのみを使用したGo、Sinatraを使用したSQLiteを備えたRuby向けにも提供されています。これらはすべて、Cams Web APIドキュメントのAIコード生成プロンプトのセクションで確認できます。プロンプトを入手してください。
05 · 設定する3つの値
生成されたファイルの設定
生成されたファイルの先頭には設定ブロックがあります。PHP版では以下のようになります。他の言語でも同じ3つの値を使用します。
|
設定ブロック、PHP版 $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| 設定項目 | 入力する内容 |
|---|---|
| base_url | Cams API MonitorアカウントのRESTfulエンドポイントURL |
| stgid | お使いのService Tag ID。 |
| auth_token | お使いのAuthTokenです。送信するRESTfulリクエストに含まれ、受信するコールバックリクエストのAuthTokenと照合されます。 |
|
トークンは共有するコードに含めないでください 簡単なテストであれば、設定ブロックに値を直接入力しても問題ありません。本番稼働の前には、トークンを環境変数またはシークレットマネージャーに移してください。そうすることで、バージョン管理や共有ファイルにトークンが残ることを防げます。 |
設定を行い、公開HTTPSアドレスにデプロイしたら、そのアドレスをCams GatewayのCallback URLとして設定してください。これ以降、検証済みのスキャンはすべてリアルタイムで受信機に届きます。
06 · デバイスを接続する前にテストする
受信機のテスト
コールバック受信機のテストに生体認証デバイスは必要ありません。一致するコールバックトークンを使用して、cURLでサンプルペイロードを自分で送信し、応答を確認してください。
|
ターミナル、テストコールバックを送信 # Save the sample payload as sample.json, then send it to your receiver:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Expected response (HTTP 200):
# {"status":"done"}
|
| テスト | 送信する内容 | 期待される結果 |
|---|---|---|
| 有効なイベント | AuthTokenをauth_tokenに設定したsample.json | HTTP 200とdoneが返され、打刻が保存される |
| 重複イベント | 同じリクエストを2回目に送信 | HTTP 200とdoneが返され、2件目のレコードは保存されない |
| 誤ったトークン | 別のAuthTokenを設定したsample.json | 拒否され、何も保存されない |
| 出勤イベント | Typeを CheckIn に変更したsample.json | 出勤として保存される |
| RESTful操作 | 組み込みのHTMLテストインターフェースを使用して操作を送信 | StatusとStatusCodeを含む応答が返される |
生成されたHTMLテストインターフェースを使用すると、RESTful側の動作を簡単に試せます。ファイルをブラウザーで開き、ドロップダウンから操作を選択し、事前入力されたJSONを必要に応じて調整して送信してください。同じページの最近のコールバック表示で、テスト用コールバックが受信されたことを確認できます。
07 · 本番前チェックリスト
本番稼働前の確認事項
AIが生成したコードは、迅速で信頼できる出発点になりますが、他のコードと同様に、実際の従業員データを扱う前にレビューする必要があります。
| 項目 | 完了の条件 |
|---|---|
| コードのレビュー | 開発者が生成されたファイルを読み、各セクションの役割を理解している |
| HTTPSのみ | 受信機は、有効な証明書を備えたHTTPSでのみアクセスできる |
| トークンの保護 | AuthTokenは環境変数またはシークレットマネージャーに保存されている |
| 重複の処理 | OperationIDが保存され、照合されることで、再送されたイベントが無視される |
| ストレージの適合性 | 小規模な環境ではJSONファイルストアで問題ありません。大規模な導入では本番用データベースへの移行が必要になる場合があります |
| テストインターフェースの保護 | 公開サーバーでは、HTMLテストページがパスワードで保護されているか、無効化されている |
| 写真の慎重な取り扱い | ディスクに保存された勤怠写真は、アクセス制御され、必要な期間のみ保持される |
| 監視体制 | エラーと通常と異なるコールバック量が記録され、お客様独自の監視システムで通知される |
|
業務ルールは別の場所に置いてください 受信機の役割は、受け付け、検証、振り分け、保存、そして受信応答を返すことです。誰が遅刻したかの判断、残業時間の計算、通知の送信は、HRMS、ERP、自動化ツールなど、保存されたイベントを読み取るシステムで行うべきです。役割を絞り込んだ受信機の方が、セキュリティを確保しやすく、保守も容易です。 |
よくある質問
|
自分でコードを書く必要はありますか? 通常は必要ありません。AIコード生成プロンプトは、そのまま動作する完全なファイルを生成します。設定値を3つ入力し、デプロイして、テストしてください。本番稼働前には、開発者がコードをレビューする必要があります。 |
|
どのAIアシスタントでプロンプトを使用できますか? Claude、ChatGPT、Copilotを含め、高性能なAIコーディングアシスタントであれば利用できます。アシスタントが仕様全体を把握できるよう、プロンプトの内容全体を一度に貼り付けてください。 |
|
RESTfulエンドポイントURLとService Tag IDはどこで確認できますか? どちらもCams API Monitorアカウントで確認できます。RESTfulリクエストは、エンドポイントURLに ?stgid= を付け、その後にService Tag IDを続けた形式で送信されます。 |
|
重複したイベントにdoneを返すのはなぜですか? イベントは正常に到着しているためです。すでに保存済みであっても同様です。doneを返すことで、Gatewayにイベントを再送する必要がないことを伝えられます。 |
|
一覧にない言語を使用できますか? はい、可能です。コールバック受信機に必要なのは、HTTPSのPOSTを受け付け、JSONを返すことだけです。プロンプトは作業を簡略化するためのものであり、同じAPIは、それができる任意の言語で利用できます。 |
まとめ:プロンプトから、半日でリアルタイム勤怠管理へ
バイオメトリック・コールバック受信機は小さなものですが、検証済みのすべてのスキャンを、HRMS、給与計算、ダッシュボード、自動化で使用できるリアルタイムデータに変換する重要な役割を担います。Cams AIコード生成プロンプトを使えば、ゼロから作り上げる必要はありません。Python、Node.js、PHP向けのプロンプトをダウンロードし、AIアシスタントに貼り付けて、3つの値を設定し、テストしてください。その後、レビューと保護を行い、リアルタイムの勤怠データの流れを開始してください。
Cams Biometrics Gatewayは、受信機に必要なイベントを配信します。そのCallback APIは、15を超えるブランドのデバイスから、検証済みのすべてのスキャンを一貫したJSON形式でリアルタイムに送信します。また、RESTful APIは、生成したクライアントから呼び出せる27種類の操作を提供します。すべての通信はHTTP/HTTPS上で行われ、認証トークンの検証と、任意のAES-256暗号化に対応しています。CamsBiometrics.comでプラットフォームの詳細をご覧いただき、すべてのAIコード生成プロンプトを含む完全なWeb APIドキュメントをお読みください: プロンプトを入手。