カメラの向きを変える（PTZ）

ONVIF に対応したカメラの首振り・ズームを操作します。カメラに ONVIF の接続情報を設定しておく必要があります（→ カメラの設定）。

`action`	動き	使う項目
`relative`	今の位置から指定した量だけ動かす	`pan`・`tilt`・`zoom`（-1〜1）
`absolute`	指定した位置へ動かす	`pan`・`tilt`（-1〜1）、`zoom`（0〜1）
`preset`	カメラに登録したプリセットへ動かす	`presetToken`
`stop`	動きを止める	なし

カメラが動き始めた時点で返ります。映像は数秒遅れて届くので、動いた結果を画像で確かめるときは少し待ってから撮ってください。スコープは data:write が要ります。

POST/devices/{id}/ptz

Authorization

AuthorizationBearer token · headerrequired

組織設定の「API・MCP」タブで発行した API トークン（tcn_ で始まる）。

Path parameters

idstringrequired

デバイス ID（<エッジPC の Thing 名>__<UUID>）

Request body

requiredapplication/json

actionstringrequired

動かし方（上の表）

Allowed:relativeabsolutestoppreset

pannumber

左右

min -1 · max 1

tiltnumber

上下

min -1 · max 1

zoomnumber

ズーム

min -1 · max 1

presetTokenstring

preset のときに必須

min length 1

Responses

200

成功

okbooleanrequired

400

入力の検証エラー、または対象の種類が合わない

errorstringrequired

人が読めるエラーメッセージ

401

トークンが無い、または無効

errorstringrequired

人が読めるエラーメッセージ

403

スコープが足りない、または操作が許可されていない

errorstringrequired

人が読めるエラーメッセージ

404

対象が無い（他の組織のものを含む）

errorstringrequired

人が読めるエラーメッセージ

502

エッジPC まで届かなかった、またはエッジPC が失敗を返した

errorstringrequired

人が読めるエラーメッセージ

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

idpath*デバイス ID（`<エッジPC の Thing 名>__<UUID>`）

Bodyapplication/json

actionstring*動かし方（上の表）pannumber左右tiltnumber上下zoomnumberズームpresetTokenstring`preset` のときに必須

Request

curl -X POST 'https://api.thingsconnect.app/api/v1/devices/string/ptz' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "relative",
  "pan": 0.1
}'

const response = await fetch("https://api.thingsconnect.app/api/v1/devices/string/ptz", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"action\": \"relative\",\n  \"pan\": 0.1\n}"
});

import requests

response = requests.post(
    "https://api.thingsconnect.app/api/v1/devices/string/ptz",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"action\": \"relative\",\n  \"pan\": 0.1\n}",
)

Response

{
  "ok": true
}

{
  "error": "string"
}

{
  "error": "Unauthorized"
}

{
  "error": "data スコープが必要です"
}

{
  "error": "string"
}

{
  "error": "string"
}