Custom Command

Act 管理

Custom Command

Custom Command は、Actcast API を経由して、デバイス上の Act に対して任意のコマンドを発行し、実行結果を取得できる機能です。 Actcast API へのリクエストは、デバイス上の Actcast Agent を経由してアプリケーションの handler に届きます。

ActcastOS 3.80.0 以降、または 4.32.0 以降で利用できます。

利用する API

Actcast API の利用方法全般は Actcast API を参照してください。 Custom Command では、主に以下の API を利用します。

いずれの API も、Authorization: token <API トークン> ヘッダによる認証が必要です。

利用の流れ

Act アプリケーションで custom command handler を実装し、CommandServer に登録します。
Actcast API の Custom Command を発行する API を呼び出し、対象デバイスに payload を送信します。
API レスポンスで返される id を保持します。
Act 側で handler が呼び出され、処理結果の文字列を返します。
Actcast API の Custom Command の実行結果を取得する API を、手順 3 の id を使って呼び出し、status と data を取得します。

API と handler の対応関係

Custom Command の利用時に扱う主な値の対応関係は以下のとおりです。

API / サンプルコード上の値	対応先	説明
`POST /jobs/custom_command` のリクエストボディ	`request['payload']`	任意の payload 文字列をリクエストボディとして送信すると、そのまま handler に渡されます。
`POST /jobs/custom_command` のレスポンスボディ `id`	`request['id']`	コマンド発行ごとに新たな ID を受取り、実行結果を取得する際に使用します
handler の戻り値	`GET /custom_command/{id}` のレスポンスボディ `data`	handler が返した文字列が、`status: finished` のときの `data` として取得されます。
`GET /custom_command/{id}` のレスポンスボディ `status`	なし	実行状態を表す値です。handler から直接返すものではなく、Actcast 側が付与します。

Actcast Agent からアプリケーションの handler には、以下のような JSON のデータが渡されます。

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "payload": "ping"
}

Actcast Agent とアプリケーションの間の通信仕様の詳細は、アプリケーション - Actcast エージェント間通信についてを参照してください。

Custom Command 利用例

ここでは curl で Custom Command の API からコマンドを発行して、その結果を取得する例を示します。

1. Custom Command を発行する

<your_api_token>、<group_id>、<device_id> はそれぞれご自身の API トークン、グループ ID、デバイス ID に置き換えてください。

API_TOKEN="<your_api_token>"
GROUP_ID="<group_id>"
DEVICE_ID="<device_id>"
PAYLOAD='ping'

curl -sS \
  -H "Authorization: token ${API_TOKEN}" \
  -H "Content-Type: text/plain" \
  --data-raw "${PAYLOAD}" \
  -X POST "https://api.actcast.io/v0/groups/${GROUP_ID}/devices/${DEVICE_ID}/jobs/custom_command"

レスポンス例:

{"id":"550e8400-e29b-41d4-a716-446655440000"}

レスポンスの id を控えて、次の結果取得 API で使用してください。リクエストボディが payload そのものです。たとえば PAYLOAD='ping' を送ると、handler では request['payload'] == 'ping' として受け取ります。

2. 実行結果を取得する

発行時に取得した id を COMMAND_ID に設定して、結果を取得します。

COMMAND_ID="550e8400-e29b-41d4-a716-446655440000"

curl -sS \
  -H "Authorization: token ${API_TOKEN}" \
  "https://api.actcast.io/v0/groups/${GROUP_ID}/devices/${DEVICE_ID}/custom_command/${COMMAND_ID}"

レスポンス例:

{
  "status": "finished",
  "data": "ping"
}

status が processing の場合は、まだ結果が利用可能になっていません。同じ API を一定間隔で再度呼び出して確認してください。

ここで返る data は、handler が返した文字列です。たとえば handler が request['payload'] をそのまま返す実装であれば、payload に ping を送ったとき data は ping になります。

status には以下の値が返ります。

processing: 処理中です。
finished: 正常に完了しました。data に handler の戻り値が入ります。
lost: 発行から 5 分経過しても結果が得られませんでした。
app_error: handler 内でエラーが発生しました。
command_server_error: CommandServer 側でエラーが発生しました。

結果は発行から 14 日間取得できます。14 日以降は結果取得 API の HTTP ステータスが 404 になります。

アプリケーションの開発方法

Custom Command に対応した Actcast アプリケーションを開発するには、 actfw-core のバージョン 2.17.0 以降の CommandServer を使用する必要があります。

アプリケーション内に、Custom Command を処理する handler を用意して、CommandServer のコンストラクタに指定してください。 handler は、リクエストの文字列を解釈して任意の処理を実行後、結果の文字列をレスポンスとして返します。

リクエストの payload、およびレスポンスは 64KiB 以下としてください。

handler は、同一のリクエストで複数回呼び出されることがあります。複数回の実行が許容できない場合には、リクエストに含まれる UUID を handler で保存して、実行が必要か判定してください。

handler は、他の handler 呼び出しの終了を待たずに、並列で同時に呼び出されることがあります。 handler 内で同時に実行できない処理がある場合には、ロックなどを用いて、他に同時に実行されていないことを確認してください。

以下は、id と payload を含む文字列を返す handler の例です。

import actfw_core
from actfw_core.command_server import CustomCommandRequest

def custom_command_handler(request: CustomCommandRequest) -> str:
    custom_command_id = request['id']
    payload = request['payload']
    message = f"Payload received: {payload} (id: {custom_command_id})"
    return message

def main():
    app = actfw_core.application.Application()
    command_server = actfw_core.CommandServer(custom_command_handler=custom_command_handler)
    app.register_task(command_server)
    app.run()

if __name__ == "__main__":
    main()

注意事項

Custom Command に対応していない (古いバージョンの actfw-core を使用している) Act を実行しているデバイスには、Custom Command のリクエストを送信しないでください。リクエストを送信した場合、CommandServer が終了してしまい、Act を再起動するまでの間は TakePhoto 機能に応答しなくなる可能性があります。これを回避する必要がある場合は、Custom Command に対応したバージョン 2.17.0 以降の actfw-core を使用して、アプリケーションの更新を行ってください。

最終更新日 2026/06/22