API管理

注意事項

コードスタイルブロックの例は異なる URL を含むことができます。リセラー URL（例：cloud.camstreamer.com）に従って変更する必要があります。

APIトークンの作成と使用

認可

APIサーバーとのすべての通信は、アクセストークンを介して認証されなければならない。有効なトークンは、各APIコールのヘッダーに挿入する必要があります。 トークンは、ポータルでフルアカウントにアクセスできるユーザーによって作成できます。

アカウントにフルアカウントアクセス権限があることを確認してください。
- アカウントが制限されている場合、APIメニューは表示されません。
- この場合、管理者にアカウントのフルアクセス権を提供してもらうよう依頼してください。
右上にあるユーザーのアイコンを押し、 APIオプションを選択します。
APIトークンの作成ボタンを押すと、新しいアクセストークンとアクセス権が追加されます。
各APIコールのヘッダーにトークンを使用します。

認証ヘッダー

"Authorization : Bearer TOKEN”

認証例

curl -X POST -H 'Authorization: Bearer TOKEN' -H "Content-Type: application/json" --data-binary '{"query":"{cameraList{name}}"}' https://system2.netrex.cz/api/graphql.php

GraphQL API概要

ポータルではAPIへのアクセスに GraphQL を使用しておりますが、これはより広く普及しているRESTモデルの代替手段です。サーバーはクエリ文字列を解釈し、要求された形式でデータを返します。API内のデータについて包括的かつ明確な説明を提供することで、クライアントアプリケーションは必要なデータを正確に要求できるようになります。

GraphQLは2種類の操作を使用します。クエリー操作はデータの読み込みに使用されます。変異はデータを変更するために使用されます。個々のクエリー操作と変異操作は、POSTエンドポイントリクエストで送信されます。ポータル・アドレスの後に“api/graphql.php“を追加します。

エンドポイントは、実行される操作に関係なく一定のままです。

ヒント

GraphQLについてはこちらの記事をご覧ください。RESTからGraphQLへの移行についてはこちらの記事をご覧ください。

APIの使用

GraphQL APIで利用可能なすべてのタイプ、クエリー、ミューテーションの詳細なドキュメントは、APIエクスプローラーで利用可能です。これを開くには、ポータルアドレスの後に「api/explorer/index.html」を追加するだけです。クイックスタートのための最も重要な情報は、API統合のための最も一般的なシナリオの章に記載されています。

注意事項

パブリックAPIは、ユーザーインターフェースでサポートされているすべてのアクションをサポートしているわけではありません。サポートされていないアクションに興味がある場合は、サポートまでお問い合わせください。

APIエクスプローラ

クエリをテストするには、ユーザーアカウントを認証し、クエリを対話形式でテストできるAPI Explorerの使用をお勧めします。APIエクスプローラでは、接続されたアカウントのデータに対して特定のクエリや変異を提案、検証、実行することができます。また、エクスプローラーを使用して、すべてのクラウドAPIクエリ、変異、およびデータタイプの構造化されたドキュメントを表示および閲覧することもできます。ドキュメントは右上のDocsをクリックして開くことができます。

開いたら、クラウドアカウントにログインする必要があります。右上のログインボタンを押します。エクスプローラーボタンを押すと、すべてのクエリーとミューテーションのツリーリストが表示され、クエリーの作成が簡単になります。

警告

エクスプローラーAPIを使用すると、アカウントのデータを照会および編集ができます。重要なデータを削除したり変更したりしないように注意してください。

APIトークンの作成

APIトークンは、システム・アプリケーション・インターフェースおよびポータルに接続されているカメラのアプリケーション・インターフェースへのクライアント・アクセスを認証するために使用されます。

右上にある、ログインしているユーザー名のボタン（）を押してください。
APIタブを開きます。
Create API Tokenボタンを押します。
任意のトークン名を入力してください。
希望するトークンの有効期限を選択します。
保存ボタンで確定します。

注意事項

トークンをカメラAPIの認証に使用するには、Configurationパーミッションを有効にする必要があります。

OAuth2 API認証

認証トークンを取得するには2つの方法があります。最初の方法は、ユーザー・インターフェースでトークンを作成する方法です。この方法は最もシンプルで、ほとんどのAPIアプリケーションで推奨されています。Oauth2プロトコルを使用してトークンを取得することもできます。以下に、OAuth2を使用して認証トークンを取得する手順を説明します。

ヒント

OAuth2を実装するには、利用可能なライブラリのいずれかを使用することをお勧めします。OAuth2についての詳細情報と概要は下記を参照してください。

クライアント・アプリケーションの作成

まず、新しいOAuth2アプリケーションを作成します。OAuth2アプリケーションは、任意のオーナーまたはゲストアカウントを使用してAPIへの承認を可能にします。アカウントにログインすると、クライアントアプリケーションの管理インターフェイスを利用できます。

右上のユーザーアイコンを押し、 APIを選択します。
OAuth2アプリケーションを開きます。

OAuth2アプリケーションは、アプリケーション・インターフェースへのアクセス要求するリクエスト元を定義します。このアプリケーションは、あらゆるシステムアカウントの認証に使用できます。

注意事項

フルアクセスアカウントのみがアプリケーションを作成できます。

アプリケーションを作成する際には、以下の情報を入力する必要があります：

名前 – “My application “など、任意の名前を入力してください。
説明 – 任意の説明を入力します。
リダイレクトURLのリスト – 認証後にユーザーがリダイレクトされるURLを入力します。

ヒント

連携ごとに新しいクライアント・アプリケーションを作成することをお勧めします。

OAuth2アプリケーションが作成されると、アプリが生成されます：

client_id – 一意のアプリケーション識別子、
client_secret – アプリケーションキー、

これは OAuth2 が認証コード “AUTHORIZATION_CODE” を取得する際に使用します。

認証コードの取得

注意事項

コードスタイルブロックの例は異なる URL を含むことができます。別のリセラーの下にアカウントを持っている場合、リセラーの URL に従って変更する必要があります（例：cloud.camstreamer.com）。

さらにアクセストークンと交換できる認証コードを取得するには、エンドポイントhttps://system2.netrex.cz/oauth2/auth　を使用使用します。

POST:
https://system2.netrex.cz/oauth2/auth/?response_type=code&client_id=CLIENT_ID&redirect_uri=CALLBACK_URL&scope=read,write

リクエストパラメーター

パラメータ	説明
client_id	クライアント・アプリケーションを識別する。
範囲	コンマで区切られた必要な権利のリスト。設定可能な権限は、 – read、 – write、 – liveview、 – audiotransmit、 – liveview_ptz、 – liveview_light、 – liveview_audioclip、 – recordings、 – recordings_delete、 – events。
redirect_url	認証コードを送信する URLです。これは、クライアント・アプリケーション定義で許可されているURLと同じでなければなりません。
state	認証コードと共にそのまま redirect_url に返されるオプションのセキュリティパラメータです。

まず、ポータルのログイン画面にリダイレクトされます。アカウントにログインすると、クライアントアプリケーションへのアクセスを許可するかどうかを尋ねるダイアログが表示されます。ダイアログを確認/拒否すると、redirect_url がリダイレクトされ、認証コードを示す “code” パラメータ、またはエラーの理由を示す “error” パラメータが GET パラメータに追加されます（ユーザがアクセス要求を拒否した場合は “access_denied”）。リクエストに “state “パラメータが指定されていた場合、それもリダイレクトに追加されます。

アクセストークンの取得

アクセストークンを取得するために、エンドポイントhttps://system2.netrex.cz/oauth2/token、場合によってはリフレッシュトークンも使用されます。

POST:
https://system2.netrex.cz/oauth2/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=CALLBACK_URL

パラメータ	説明
client_id	クライアント・アプリケーションを識別する。
client_secret	クライアント・アプリケーションのシークレット・キー。このキーを使用して、APIへの永続的なアクセス（アクセストークンとリフレッシュ・トークン）を取得できます。このパラメータがない場合は、一時的なアクセスのみが許可されます（つまり、アクセストークンのみ）。client_secretパラメータは、漏洩の危険性がある場合には使用できないことに注意してください。例えば、JavaScriptアプリケーションでは使用できません。
redirect_url	クライアント・アプリケーション定義に記載されているリダイレクトURLの1つ。このステップでは、追加のセキュリティ機能としてのみ動作し、それ以上のリダイレクトは発生しません。
grant_type	認証方法を指定するパラメータです。以下のオプションが利用可能です。 –auth_code。これは、前のステップの認証コードとアクセストークンの交換です。 –refresh_token。これは、次の期間の新しいアクセストークンの更新または交換です。

JSON 形式で可能な回答：

{"access_token":"ACCESS_TOKEN","expires_in":3600,"refresh_token":"1234"} – APIへのアクセス制限時間なし。アクセストークンが期限切れになると、トークンを更新することで新しいトークンを取得できます。このタイプのアクセスでは、クエリに client_secret を使用する必要があります。
{"access_token":"ACCESS_TOKEN","expires_in":3600} – APIへの1回限りのアクセスは、アクセストークンの有効期限が切れるとキャンセルされます。
{"error":"Error message"} – 無効なリクエストまたはシステムエラーです。

取得したACCESS_TOKENは、各Graph API呼び出しのヘッダー（「Authorization: Bearer TOKEN」）に挿入できます。

アクセストークンのキャンセル

アクセストークンは、ユーザーインターフェースまたはAPIを使用していつでもキャンセルできます。アクセスのキャンセルにはエンドポイント https://system2.netrex.cz/oauth2/revoke を使用します。

POST:
https://system2.netrex.cz/oauth2/revoke?access_token=ACCESS_TOKEN

パラメータ	説明
アクセストークン	削除する既存のトークン。

JSON形式で回答する：

{"success":true,”message”:”Info message”} – 指定されたアクセストークンは（リフレッシュトークンも含めて）取り消されます。

OAuth2のユーザー権限

システムは、閲覧が制限される可能性のあるフルアクセス・ユーザーとパーシャルアクセス・ユーザーを区別します。Oauth2 認証を使用する場合、API を通じて取得されるデータはユーザーのアクセス権に対応します。可視性を完全に確保したい場合は、OAuth2認証時にフルアクセス権を持つアカウントを使用するか、静的APIトークンを生成してください。

API連携の一般的なシナリオ

注意事項

APIエクスプローラーを使って、以下の例を簡単にテストすることができます。APIの認可情報を取得するには、ここをクリックしてください。

オブジェクトの構成

ユーザー、カメラ、電気入力、ダッシュボード、フォルダなどのオブジェクトは、ツリー構造のノードです。この構造により下記が可能となります：

複数のオブジェクトから集約されたメトリクスを取得します。
オブジェクトグループのユーザー権限を管理します。
ユーザーインターフェースをより分かりやすくするために、オブジェクトをグループに整理します。

フォルダオブジェクトは無限の没入を可能にします。電気入力のようないくつかのオブジェクトは、常にカメラオブジェクトの下に配置されます。

例

ユーザーが閲覧権限を持つ全アイテムの一覧。OAuth2 認証では、すべてのアイテムを見ることができないゲストユーザーにもトークンが発行される可能性があることに注意しましょう。

query {
 nodeList {
  parent_node_id
  node_id
  type
  name
 }
}

回答

{
 "data": {
  "nodeList": [
   {
    "parent_node_id": null,
    "node_id": 138170,
    "type": "folder",
    "name": "rootfolder"
   },
   {
    "parent_node_id": 138170,
    "node_id": 138170,
    "type": "folder",
    "name": "San Diego"
   },
…
  ]
 }
}

オブジェクト “camera “だけを取得したい場合は、オプションのパラメータ・タイプを使用します。利用可能なすべてのタイプは、API Explorerで生成されたドキュメントで確認できます。

query {
 nodeList(type:camera) {
  parent_node_id
  type
  name
  node_id
 }
}

回答

{
 "data": {
  "nodeList": [
   {
    "parent_node_id": 138170,
    "type": "camera",
    "name": "ACCC8EE8A9CA",
    "node_id": 140094
   }
  ]
 }
}

カメラパラメータの取得

カメラ・タイプは、録画のダウンロードやライブ・ストリームの取得に使用する最も包括的なタイプです。カメラ・タイプのクエリはカメラに関する多くのパラメータを返します。

例

カメラの種類をクエリすると、シリアル番号（serial_number）、接続状態（is_connected）、カメラの IP アドレス（source_ip）の情報が取得できます。必須パラメータである node_id は前の cameraList または nodeList のクエリを使用して見つけることができます。

query {
 camera(node_id:140094){
  name
  serial_number
  is_connected
  connection{
   source_ip
  }
 }
}

回答

{
 "data": {
  "camera": {
   "name": "ACCC8EE8A9CA",
   "serial_number": "ACCC8EE8A9CA",
   "is_connected": true,
   "connection": {
    "source_ip": "211.21.111.111"
   }
  }
 }
}

KPIメトリクスへのアクセス

KPI指標を得るために使用できるいくつかのタイプがあります：

統計データ

1つのオブジェクト（カメラ）に対して1つの値を返す。1台のカメラから1つの数値を取得する場合に使用します。例：カウントしているカメラ１から算出される入場者数。

利用可能なメトリクス：

peopleCount – 訪問者数。
peopleCountIn – 訪問者数（エントリーのみ）。
peopleCountOut – 訪問者数（出力のみ）。
transactionValueIn – プラスの支払トランザクションの値（100倍）。
transactionCountIn – 正の支払いトランザクション数。
transactionValueOut – 負の支払トランザクションの値（100倍）。
transactionCountOut – 負の支払トランザクションの数。

統計データメトリック

フォルダー内の 1 つのオブジェクトまたは複数のオブジェクトに対する単一の値を返します。フォルダオブジェクトへのクエリは、フォルダ内のすべてのオブジェクトの集計値を返します。複数のカメラから集約された単一の値を取得する場合に使用します。例えば全店舗のカメラがフォルダ “San Diego” にある1つの店舗からの訪問者数。

利用可能なメトリクス：

peopleCountAverage – 訪問者数。
peopleCountIn – 訪問者数（受信のみ）。
peopleCountOut – 訪問者数（発信のみ）。
peopleCountPassBy – 店舗の前を通過した来客数。
transactionCountPositive – 正のトランザクション数。
transactionCountNegative – 負のトランザクションの数。
transactionAmountPositive – 正の取引の値。
transactionAmountNegative – 負の取引の値。
conversionCount – コンバージョン数; (正のトランザクション数 / 訪問者数) * 100.
conversionAmount（コンバージョンアマウント） – 訪問者1人あたりの支出。
transactionAmountAverage – 取引の平均値（正の取引のみ）。

統計データメトリック（粒度別）

単一のクエリで複数の値（データ系列）を返します。利用可能なメトリクスおよび集計方法は、上記の statisticDataMetric と同じです。これを使用して、1 つのクエリで複数の値を取得します。このクエリのパラメータは粒度です。粒度は、返されるデータ・ポイントの数を定義します。

粒度：

本部 – 15分
H – 時
H4 – 4時間
H8 – 8時間
H12 – 12時間
日
W – 週
M – 月

システム内のすべてのメトリクスは15分間隔で保存されます。クエリが 15 分間隔に一致しない場合、APIは最寄りの間隔を使用して結果を計算します。パラメータ “from “と “to “はUnix Timestamp形式です。テスト目的には、Unix Timestamp Converterを使用できます。

例 1 – 単一の値の取得

フォルダへのクエリは、フォルダ内のすべてのカメラの集計された peopleCountAverage を返します。

query {
 statisticDataMetric(from:1589186000, to:1589186780, type:peopleCountAverage,node_id:140094)
}

回答

{
 "data": {
  "statisticDataMetric": 57
 }
}

例2 – 複数の値を取得する（時系列）

フォルダへのクエリは、15分単位で集計されたpeopleCountAverageを返します。

{
 statisticDataMetricByGranularity(from: 1589186000, to: 1589186780, type: peopleCountAverage, node_id: 63575, granularity: HQ) {
  from
  to
  value
 }
}

回答

{
 "data": {
  "statisticDataMetricByGranularity": [
   {
    "from": 1589185800,
    "to": 1589186700,
    "value": 20
   },
   {
    "from": 1589186700,
    "to": 1589187600,
    "value": 12
   }
   …
  ]
 }
}

カメラからのライブ配信を視聴する

カメラの種類を照会して、ライブ・配信にアクセスするための URLを確認します。ポータルは動画配信用にいくつかのプロトコルをサポートしています。プロトコルはカメラのアクセス方法によって異なります：

ローカルネットワーク内でのアクセス：
- rtsp – 暗号化されていないプレーンなRTSP。
公共インターネット経由でのアクセス：
- rtsp – 暗号化されていないプレーンなRTSP。
- rtsph – HTTP経由の暗号化されていないRTSP。
- rtsphs – HTTPS上で暗号化されたRTSP。
- rtspws – 非暗号化 RTSP over WebSocket。
- rtspwss – RTSP over WebSocket Secure。

ライブ配信へのアクセスの安全性

ストリーミング URL に対する API クエリは、30 秒間有効な RTSP リンクを生成します。30秒が経過するか、プレーヤーを切断すると、プレーヤーに接続できなくなり、アプリケーションは新しいRTSPリンクを要求する必要があります。

プレーヤー

システムからライブ動画を再生するには、GitLabリポジトリで利用可能なウェブプレーヤーを使用することをお勧めします。このプレイヤーはWebSocket SecureとRTSPプロトコルの組み合わせを使用しており、インターネット上のあらゆる場所で動画を再生するのに適しています。

例

この例では、リモートプレーヤー用の動画配信を取得する方法を示しています。ほとんどのカメラでは、異なるプロファイル（解像度とキャプチャ）の配信が可能です。streamProfileタイプをクエリして、利用可能なプロファイルを調べます。

query {
 camera(node_id:140094){
  stream_profiles{
   stream_profile_id
   width
   height
  }
 }
}

回答

{
 "data": {
  "camera": {
   "stream_profiles": [
    {
     "stream_profile_id": 120846,
     "width": 800,
     "height": 450
    },
    {
     "stream_profile_id": 120850,
     "width": 1920,
     "height": 1080
    }
   ]
  }
 }
}

次のクエリーは、現在生成されているRTSPストリームのRTSPとURLを取得します。

query {
 camera(node_id:140094){
  live_view(stream_profile_id:120850){
   remote{
    rtsp{
     url
    }
   }
  }
 }
}

回答

{
 "data": {
  "camera": {
   "live_view": {
    "remote": {
     "rtsp": {
      "url": "rtsp://nvhs10.survilla.net:2554/nvhs10~1600421245~9469bb1a2b831031456ef9c4abc182573d7a86a9f305f54df18621a9484d6134"
     }
    }
   }
  }
 }
}

複数の動画チャンネルに対応しているカメラもあります。例えば、複数の光学系を持つカメラや180°カメラのバーチャルビューなどです。チャンネルは、live_view タイプのオプションのパラメータ video_channel_node_id で選択できます（stream_profile_id：120850、video_channel_node_id：1000）。各カメラの動画チャンネルのリストはカメラの種類で確認できます。

カメラから常時接続可能なRTSPカメラリンクを取得する

クラウドにホストされているカメラの常時有効なRTSPリンクを取得するには、このガイドに従ってください。RTSPリンクを生成し設定する手順を順を追って説明し、ストリーミングや他システムとの連携に確実に使用できるようにします。

1.クラウドの右上にあるDEVICE_ACCESS_TOKENを作成します。

トークンは少なくとも “Configuration” 権限が有効になっている必要があります。

2. カメラ設定 > 基本設定に行き、”カメラインターフェース”ボタンをクリックします。

3. カメラのドメインは常に同じであり、左側にあるそれぞれのカメラのシリアル番号だけが違うことを確認します。

RTSPリンクを構成する

APIキーを作成し、ドメイン情報を取得するとRTSPリンクが構成出来ます。

rtsp://CAMERA_SN.DOMIAN_NAME:443/axis-media/media.amp?DEVICE_ACCESS_TOKEN=API_TOKEN

どこで作成できるか

CAMERA_SN カメラのシリアル番号です。例. b8a44f7b97cc
DOMAIN_NAME カメラに接続すつためのドメイン名です。例. us1.device-connect.net, jp.device-connect.net, device-connect.net
API_TOKEN クラウドで作成されたAPIトークンです。例. eh010egbhWE5BBGls2jkGvTf_system2

例：

rtsp://b8a44f7b97cc.us1.device-connect.net:443/axis-media/media.amp?DEVICE_ACCESS_TOKEN=eh010egbhWE5BBGls2jkGvTf_system2

VAPIX パラメータ

VAPIX parameters 経由で動画の画質に効果を反映させることが出来ます。全リストはいかに記載されています。 Axis documentation).

例：

rtsp://b8a44f7b97cc.us1.device-connect.net:443/axis-media/media.amp?resolution=1280x720&color=0&DEVICE_ACCESS_TOKEN=eh010egbhWE5BBGls2jkGvTf_system2

FFmpeg経由で配信を視聴する

ストリームをテストするには、FFmpeg dをダウンロードして展開済みであることを確認し (例： C:\ffmpeg\bin内), 以下の手順に従ってください：

Command Prompt を開きます（ Win + Rを押して、 cmdと入力し、Enterキーを押します).
FFmpegフォルダに移動してください：
DOS
cd C:\ffmpeg\bin
次のコマンドを実行してください（RTSPリンクを置き換えてください）：
ffplay -nostats -loglevel trace -rtsp_transport https "rtsp://b8a44f7b97cc.device-connect.net:443/axis-media/media.amp?DEVICE_ACCESS_TOKEN=eh010egbhWE5BBGls2jkGvTf_system2"

VLC経由でHTTPS経由のRTSPストリームを配信する

一部のネットワーク環境では標準のRTSPがブロックされるか、セキュアなトンネリングが要求されるため、以下の方法ではFFmpegをセキュアなブリッジとして使用し、動画配信を VLC Media Playerに供給します。

前提条件

FFmpegがインストールされました: FFmpeg がダウンロードされて展開されていることを確認してください。 (例： C:\ffmpeg\bin.内)。

FFmpeg ブリッジの開始

作成したカメラリンクを使って、FFmpeg ブリッジを作成してVLCで動画を再生することが出来ます。

Command Prompt を開きます（ Win + Rを押して、 cmdと入力し、Enterキーを押します).
FFmpegフォルダに移動してください：
DOS
cd C:\ffmpeg\bin
下記コマンドを実行してください:
DOS
ffmpeg -rtsp_transport https -i "rtsp://b8a44f7b97cc.us1.device-connect.net:443/axis-media/media.amp?DEVICE_ACCESS_TOKEN=eh01OegbhHWE5BBGls2jkGvTf_system2" -c copy -f mpegts -listen 1 http://127.0.0.1:8080

注意事項

端末は接続を待機します—これは正常な動作です。このウィンドウを閉じないでください。

VLCで配信を開きます

VLC Media Playerを立ち上げます。
メニューに行き: メディア -> ネットワークストリームを開きます… (または Ctrl+Nを押します)。
下記のローカルアドレスを入力します: http://127.0.0.1:8080
再生をクリックします。

注意事項

シングル接続: -listen 1 パラメータは、VLCでストリームを閉じるとFFmpegプロセスが自動的に停止することを示します。
もう一度見るには、ターミナルでコマンドを再実行してください。

ウィンドウを開いたままにしておく: 動画を視聴中はコマンドプロンプトウィンドウを開いたままにしておく必要があります。

録画の視聴とダウンロード

録画の視聴／ダウンロードのプロセスは、3つのステップに分かれています：

録画の有無を確認し、recording_idを取得します。
必要な解像度での録画の準備。
録画をダウンロードするためのURLを取得します。

以下の例は、全体のプロセスを示しています。

例

Recording_idは一意のレコード識別子です。これは、次のクエリを使用して可用性をチェックするときに作成されます。また、次のステップで使用する使用可能な録画サイズについても尋ねます。利用可能なサイズのうち最も大きいものがデフォルトの録画解像度に相当し、準備に最も時間がかかります。from “と “to “パラメーターは、必要な録画期間を定義します。

query{
 camera(node_id:62303){
  recordings(from:1589190089, to:1589190689){
   recording_id
   duration
   download_url
   outputs{
    height
   }
  }
 }
}

回答

{
 "data": {
  "camera": {
   "recordings": [
    {
     "recording_id": "xRMElmAkh3",
     "duration": 598,
     "download_url": null,
     "outputs": [
      {
       "height": 480
      },
      {
       "height": 720
      },
      {
       "height": 800
      }
     ]
    }
   ]
  }
 }
}

答えが空のフィールドを含む場合、ユーザー・インターフェースで、指定されたカメラが録画中か、選択された間隔で録画中であったかどうかを確認します。このパラメータは前のステップのrecording_idとheightです。

mutation{
 recordingPrepare(recording_id:"xRMElmAkh3", height:720)
}

回答

{
 "data": {
  "recordingPrepare": true
 }
}

真の値は、録画準備が正常に開始されたことを示します。準備の状態は、recording_idをパラメータとする録画のタイプをクエリすることで取得されます。

query{
 recording(recording_id:"6RjiHGzqCE"){
  progress
  download_url
 }
}

回答

{
 "data": {
  "recording": {
   "progress": 100,
   "download_url": "https://cloud.camstreamer.com/api/download.php?auth_key=2YwmG01NAeNYz4m1bZfwIKLOaoHeCfxH"
  }
 }
}

回答ではprogress：100″となっています。アップロードの準備が完了し、download_url にダウンロード URL が含まれています。録画がまだ準備中の場合、download_urlは値 “null “を含み、progressはパーセントで処理状況を表します。
未使用の録画IDは1時間で期限切れとなります。録画のダウンロード URL の有効期限は 24 時間です。録画がダウンロードされた場合、ダウンロードURLの有効期限は6時間後です。

外部IDを使用した要素のペアリング

NodeList タイプのクエリを実行すると、ユーザー・インタフェースで入力された外部 ID をツリー構造内のすべてのアイテムに対して表示できます。外部 ID は、サードパーティ・サービスに統合するためにアイテムを一意に識別するために使用されます。外部 ID は、API セクションで作成できます。

例

次のクエリーは、対応する外部IDを含むノードのリストを返します。

query{
 nodeList {
  name
  external_id
 }
}

回答

{
 "data": {
  "nodeList": [
   {
    "name": "Folder",
    "external_id": "001"
   },
   {
    "name": "ACCC8EE8A9CA",
    "external_id": "camera1"
   }
  ]
 }
}

カメラアクセスとVAPIXカメラインターフェース

クラウドに接続されたカメラには、リモートアクセスを可能にする固有のURLが割り当てられます。このURLには常にカメラのシリアル番号と地域別のdevice-connect.netドメインが含まれます。

リージョンによって、URLは次のいずれかの形式になります:

https://SerialNumber.device-connect.net/ – EMEA 地域向け
https://SerialNumber.jp.device-connect.net/ – APAC 地域向け
https://SerialNumber.us1.device-connect.net/ – America 地域向け

カメラがどのサーバーに紐づいていているか分からない場合は、Camera Cloud経由でカメラのウェブインターフェースにアクセスして確認できます。
カメラ設定 > 基本設定 > カメラインターフェース に行き、ブラウザのURLに表示されているカメラのアドレスを確認してください。

このようなアクセスは、VAPIXインターフェースを介したカメラのプログラマティック制御に特に適しています。VAPIXは、カメラを制御しそのパラメータを変更できるアプリケーションインターフェースです。
To authorize access to the camera and its VAPIX API, an API token with the Configuration permission (DEVICE_ACCESS_TOKEN) must be generated. The exact procedure for generating the token is described in the referenced article.

カメラAPIへのリクエスト例

URLとDEVICE_ACCESS_TOKENからカメラのVAPIXインターフェースに要求できます：

https://serialnumber.device-connect.net/axis-cgi/param.cgi?action=update&ImageSource.I0.Sensor.Brightness=89&root.ImageSource.I0.Sensor.ColorLevel=91&DEVICE_ACCESS_TOKEN=NvA7fxxxxxtYVQ

下記の通りです：

serialnumberはカメラのシリアル番号、
/axis-cgi/param.cgiはVAPIXインターフェースの標準URLです、
action=update&ImageSource.I0.Sensor.Brightness=89&root.ImageSource.I0.Sensor.ColorLevel=91はVAPIXリクエストです。この場合、画像の明るさと彩度を変更します、
DEVICE_ACCESS_TOKEN=NvA7fxxxxxtYVQは、クエリの最後のパラメータとして記載されているワンタイム・アクセストークンです。

CamStreamerアプリのAPI呼び出し例

カメラで使用可能なストリームのリストに対するクエリ：

https://accc8ed8cbf0.device-connect.net/local/camstreamer/stream/list.cgi?DEVICE_ACCESS_TOKEN=D8PxS7HyQZepEwM4

カメラで特定のストリームを開始するためのクエリ：

https://accc8ed8cbf6.device-connect.net/local/camstreamer/stream/set.cgi?stream_id=36559&enabled=1&DEVICE_ACCESS_TOKEN=D8PxS7HyQZepEwM4

エラーの答えと制限

APIリミット

1アカウントに対するAPIクエリの制限：

1クエリー/秒、
10,000クエリー/日。

メトリクス（訪問者数など）をクエリする場合、予想されるクエリサイズは次のようになります：

最長1年、
5 メトリクス（例えば、ブランチ、カメラ、または異なるメトリクス）。

上記で指定されたサイズ以上のクエリーについては、1秒あたりの最大クエリー数を個別に評価する必要があります。

警告

APIは、お客様のライセンスで利用可能なリクエストに制限されます。

エラー応答

{
 "errors": [
  {
   "message": "Invalid or empty access token.",
   "category": "authError"
  }
 ]
}

アクセストークンがありません：認証トークンが正しい形式でヘッダーに挿入されていることを確認してください。

{
 "errors": [
  {
   "message": "Access token expired.",
   "category": "expired"
  }
 ]
}

有効期限が切れたアクセストークン：システムのAPIセクションで、トークンが有効であることを確認してください。OAuth2トークンの場合は、トークンのリフレッシュをリクエストしてください。

{
 "errors":[
  {
   "message":"Request to an unknown or unavailable platform.",
   "category":"client"
  }
 ]
}

無効なアクセストークンです：認証トークンが正しい形式でヘッダーに挿入されていることを確認してください。トークンはヘッダーに挿入されていますが、有効ではありません。

外部ID設定

外部IDは、サードパーティのサービスと連携するために、要素を一意に識別するために使用されます。外部 ID は、システムに入力された後、API を通して照会されるときに、各エレメントの一意な識別子として使用されます。外部 ID は、本機を制御するためのショートカットを設定するためにも使用されます。

外部IDの追加

右上にあるユーザー名のボタン（）を押してください。
APIタブを開きます。
外部IDアプリケーションインターフェースを選択します。
Add identifierボタンを押します。
項目テキストボックスをクリックすると、項目ツリーウィンドウが開きます。
- 外部IDを割り当てるフォルダまたは項目を選択します。
外部識別子を入力します。
保存ボタンで確定します。

外部IDの編集

対応する外部 ID の横にあるボタンを押します。
必要なパラメータを編集します。
保存ボタンで確定します

外部IDの削除

削除したい外部IDの横にあるボタンを押します。

APIで外部IDをリクエストする

ポーリングに関する情報と例については、Common API Integration Scenariosを参照してください。