パブリック API: I/Oポート | Arculesナレッジベース

概要

I/OポートのAPIは、接続されたデバイスの入出力ポートの状態を管理および監視するためのアクセスを提供します。このAPIを使用すると、開発者は複数のI/Oポートの現在の状態を照会し、必要に応じてその状態を更新することができます。これは、ビデオ監視やモニタリングシステムにおける接続デバイスやセンサーの運用状態を管理するシナリオで役立ちます。

主な使用例：

複数のI/Oポートの状態をリアルタイムで照会する
接続されたデバイスでアクションをトリガーするために特定のI/Oポートの状態を変更する

前提条件：

この記事で取り上げるAPI機能に関連するデバイス（I/Oネットワークリレーを含む）は、まずArculesゲートウェイアプライアンスに登録されている必要があります。これらのデバイスはオンラインであり、アクティブなインターネット接続を持っている必要があります。

ユーザーは、Arculesウェブポータルで以下の役割を割り当てられている必要があります：

APIユーザーの権限（役割）：APIを通じてI/Oおよびオーディオ機能を使用できるようにする
I/Oリレー担当者の権限（役割）：APIのI/O機能を使用できるようにする

APIエンドポイント

エンドポイント1：I/Oポートの状態を照会

HTTPメソッド：GET
URL：https://msapi.arcules.com/v1/ioports?portIds={portId1},{portId2}
認証：OAuth 2.0　Bearer Token
レート制限：1分間に 500回のリクエスト
対応フォーマット：JSON

リクエストパラメーター

パラメーター	タイプ	説明	必須
portIds	string	状態を確認したいポートIDを、カンマで区切ります。	必須

サンプルリクエスト

GET /v1/ioports?portIds=72af2eb5-e0c6-44b7-a122-e34b89e8880b,2945cd45-3197-4b5c-a01f-7c6ae2cd132b
Host: msapi.arcules.com
Authorization: Bearer {token}

サンプルレスポンス

{
  "2945cd45-3197-4b5c-a01f-7c6ae2cd132b": {
    "state": "low",
    "lastUpdated": 1726183188281
  },
  "72af2eb5-e0c6-44b7-a122-e34b89e8880b": {
    "state": "low",
    "lastUpdated": 1726183188281
  }
}

エンドポイント 2: I/O ポートの状態を更新する

HTTP Method: PATCH

URL: https://msapi.arcules.com/v1/ioport/{portId}

Authentication: OAuth 2.0 Bearer Token

Rate Limit: 500 requests per minute

Supported Formats: JSON

リクエストパラメーター

パラメーター	タイプ	説明	必須
portId	string	更新するI/Oポートの一意のIDです。	必須

サンプルリクエスト

PATCH /v1/ioport/ad545e36-1179-4013-a901-af5550e6e113
Host: msapi.arcules.com
Authorization: Bearer {token}
Content-Length: 20
{
  "state": "pulse",
  "duration": 500
}

サンプルレスポンス

204 No Content

エラーハンドリング

エラーコード	メッセージ	説明
200	OK	リクエストは正常に完了しました。
204	No Content	リクエストは正常に完了しましたが、このリクエストに送信するコンテンツはありません。
400	Bad Request	リクエストが無効であるか、処理できませんでした。
401	Unauthorized	JWTが不足しているか、無効です。
403	Forbidden	APIユーザーに必要な権限がありません。
404	Not Found	リクエストされたリソースが見つかりませんでした。
429	Too Many Requests	APIのリクエスト制限を超えました。
5xx	Server Error	サーバーがリクエストの処理中に問題が発生しました。

追加リソース

FAQ

Q: 認証方法は？

A: リクエストヘッダーにOAuth 2.0 Bearer Token を使用してください。

詳細は認証ガイドを参照してください。

Q: portIdの値はどうやって取得しますか？

A: /v1/devices エンドポイントのレスポンスから portId の値を取得できます。

Q: I/Oポートの過去の状態を取得できますか？

A: いいえ、I/OポートのAPIはポートの現在の状態のみを提供します。

過去のデータが必要な場合は、独自のログ機構を実装するか、追加のサービスを使用する必要

があります。

Q: ポートの状態はどのくらいの頻度で更新されますか？

A: ポートの状態はリアルタイムで更新されますが、lastUpdated は最新の更新のタイムスタンプ（エポックからのミリ秒）を示します。

Q: I/Oポートに設定できる状態は何ですか？

A: I/Oポートには以下の状態を設定できます：

high: 出力ポートがアクティブ状態に設定されます
low: 出力ポートが非アクティブ状態に設定されます
pulse: ポートに一時的なパルスが適用されます
この状態を使用する場合、パルスの持続時間を秒単位で指定する必要があります

Q: 変更内容が成功したかどうかはどうやってわかりますか？

A: 変更内容が成功すると、APIは 204 No Contentレスポンスを返し、エラーなしで状態が

更新されたことを示します。問題があった場合は、追加の詳細を含むエラーコードが返さ

れます。

Q: パルス状態に持続時間を含めないとどうなりますか？

A: 持続時間を指定せずにパルス状態を設定すると、リクエストは失敗し、

持続時間パラメータが欠落していることを示す 400 Bad Requestレスポンスが返されます。

Q: パルスを送信した後にI/Oポートの状態を元に戻すことはできますか？

A: パルス状態は指定された持続時間が経過すると自動的に以前の状態に戻ります。

リセットするための追加の操作は必要ありません。