Azure Video Analyzer のダイレクトメソッド

[アーティクル]
07/27/2022

または、サービスでのビデオアプリケーションの作成に関する記事のトピックを参照してください。

注意

Azure Video Analyzer プレビューサービスは廃止されます。2022 年 12 月 1 日までに、Video Analyzer からアプリケーションを移行することをお勧めします。

Azure Video Analyzer for Media は、この廃止の影響を受けません。これは Azure Video Indexer にブランドが変更されました。詳細については、こちらをクリックして確認してください。

操作が必要: ワークロードの中断を最小限に抑えるには、2022 年 12 月 1 日より前に、このガイドで説明されている推奨事項に従って、Video Analyzer からアプリケーションを移行してください。 2022 年 12 月 1 日以降、Azure Video Analyzer アカウントは機能しなくなります。 2022 年 5 月 2 日より、新しい Video Analyzer アカウントを作成することはできなくなります。

Azure Video Analyzer エッジモジュール avaedge では、IoT Hub から呼び出すことができるダイレクトメソッドがいくつか公開されています。ダイレクトメソッドは、デバイスとの要求/応答型通信を表し、すぐに要求の成功または失敗が確定する (ユーザーが指定したタイムアウト後) という点で HTTP 呼び出しに似ています。この方法は、デバイスが応答できるかどうかに応じて即座に実行するアクションが異なるシナリオで便利です。詳細については、「IoT Hub からのダイレクトメソッドの呼び出しについて」を参照してください。

このトピックでは、これらのメソッド、規則、およびメソッドのスキーマについて説明します。

規則

ダイレクトメソッドは、次の規則に基づいています。

ダイレクトメソッドには、MAJOR.MINOR 形式で指定されたバージョンがあります (次の例を参照)。この例では、@apiVersion の数字は "1" が MAJOR で "0" は MINOR です。
```
{
  "methodName": "pipelineTopologySet",
  "payload": {
      "@apiVersion": "1.1",
      "name": "{TopologyName}",
      "properties": {
          // Desired Topology properties
      }
  }
}
```
Video Analyzer モジュールの任意のバージョンでは、現在のバージョンまでのダイレクトメソッド呼び出しのすべてのマイナーバージョンがサポートされます。メジャーバージョン間のサポートは保証されません。
すべてのダイレクトメソッドは同期的です。
エラーの結果は、OData エラースキーマに基づいて行います。
名前は、次の制約に従う必要があります。
- 英数字とダッシュのみ。ただし、先頭と末尾にはダッシュを使用できません
- スペースは使用できません
- 最大 32 文字

ダイレクトメソッドからの応答の例

-----------------------  Request: livePipelineList  --------------------------------------------------

{
  "@apiVersion": "1.1"
}

---------------  Response: livePipelineList - Status: 200  ---------------

{
  "value": []
}

--------------------------------------------------------------------------

エラーコード

次の例に示すように、ダイレクトメソッドからエラー応答を受け取った場合、トップレベルのエラーコードが存在し、details の下に詳細な情報が表示されます。

{
  "status": 400,
  "payload": {
    "error": {
      "code": "BadRequest",
      "message": "The request is invalid",
      "details": [
        {
          "code": "ApiVersionNotSupported",
          "message": "The API version '1.4' is not supported. Supported version(s): 1.0, 1.1"
        }
      ]
    }
  }
}

トップレベルで使用されるエラーコードを次に示します。

Status	コード	Message
400	BadRequest	Request is not valid (要求は無効です)
400	InvalidResource	リソースが無効です
400	InvalidVersion	API のバージョンが無効です
402	ConnectivityRequired	エッジモジュールが適切に機能するには、クラウド接続が必要です。
404	NotFound	リソースが見つかりませんでした
409	Conflict	操作が競合しています
500	InternalServerError	内部サーバーエラー
503	ServerBusy	サーバービジー

詳細レベルで使用されるエラーコードの一部を次に示します。

Status	詳細コード	説明
400	PipelineValidationError	サイクルやパーティション分割などの一般的なパイプラインエラー。
400	ModuleValidationError	モジュール固有の検証エラー。
409	PipelineTopologyInUse	パイプライントポロジは、1 つ以上のライブパイプラインによって引き続き参照されます。
409	OperationNotAllowedInState	要求された操作は、現在の状態では実行できません。
409	ResourceValidationError	参照されたリソース (例: ビデオリソース) は、有効な状態ではありません。

サポートされているダイレクトメソッド

Video Analyzer エッジモジュールによって公開されるダイレクトメソッドを次に示します。ダイレクトメソッドのスキーマについては、こちらを参照してください。

pipelineTopologyList

このダイレクトメソッドは、作成されたパイプライントポロジの全一覧を示します。

Request

{
  "@apiVersion": "1.1"
}

Response

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-05-05T14:19:22.16Z",
        "lastModifiedAt": "2021-05-05T16:20:41.505Z"
      },
      
      // first pipeline topology payload
      
    },
      "systemData": {
        "createdAt": "2021-05-06T14:19:22.16Z",
        "lastModifiedAt": "2021-05-06T16:20:41.505Z"
      },
      
      // next pipeline topology payload
      
    }    
  ]
}

状態コード

条件	status code
エンティティが見つかりました	200
一般的なユーザーエラー	400 番台
エンティティが見つかりません	404
一般的なサーバーエラー	500 番台

pipelineTopologySet

そのようなトポロジが存在しない場合は、指定された名前を持つパイプライントポロジを作成するか、その名前を持つ既存のトポロジを更新します。

重要な点:

パイプライントポロジは、それを参照するライブパイプラインがない場合は自由に更新できます。
次の場合に限り、参照しているすべてのライブパイプラインを非アクティブ化すると、トポロジを自由に更新できます。
- 新しく追加されるパラメーターが既定値である
- 削除されるパラメーターがどのパイプラインによっても参照されていない
ライブパイプラインがアクティブな間は、一部のパイプライントポロジの更新のみが許可されます。

Request

  {
    "methodName": "pipelineTopologySet",
    "payload": {
        "@apiVersion": "1.1",
        "name": "{TopologyName}",
        "properties": {
            // Desired pipeline topology properties
        }
    }
  }

Response

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-05-11T18:16:46.491Z",
           "lastModifiedAt": "2021-05-11T18:16:46.491Z"
        },
        "name": "{TopologyName}",
        "properties": {
            // Complete pipeline topology
        }
    }
  }

状態コード

条件	status code	詳細エラーコード
既存のエンティティが更新されました	200	該当なし
新しいエンティティが作成されました	201	該当なし
一般的なユーザーエラー	400 番台
Pipeline validation Errors	400	PipelineValidationError
モジュール検証エラー	400	ModuleValidationError
一般的なサーバーエラー	500 番台

pipelineTopologyGet

指定した名前のパイプライントポロジが存在する場合は、それを取得します。

Request

  {
        "@apiVersion": "1.1",
        "name": "{TopologyName}"       
  }

Response

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-05-06T10:28:04.560Z",
          "lastModifiedAt": "2021-05-06T10:28:04.560Z"
        },
        "name": "{TopologyName}",
        // Complete pipeline topology
      }
    ]
  }
}

状態コード

条件	status code
Success	200
一般的なユーザーエラー	400 番台
一般的なサーバーエラー	500 番台

pipelineTopologyDelete

1 つのパイプライントポロジを削除します。

削除されるパイプライントポロジを参照するライブパイプラインは存在できないことに注意してください。このようなライブパイプラインがある場合は、TopologyInUse エラーが表示されます。

Request

  {
    "methodName": "pipelineTopologyDelete",
    "payload": {
        "@apiVersion": "1.1",
        "name": "{TopologyName}"
    }
  }

Response

{
    "status": 200,
    "payload": null
}

状態コード

条件	status code	詳細エラーコード
エンティティが削除されました	200	該当なし
エンティティが見つかりません	204	該当なし
一般的なユーザーエラー	400 番台
パイプライントポロジは、1 つ以上のパイプラインによって参照されます。	409	PipelineTopologyInUse
一般的なサーバーエラー	500 番台

livePipelineList

すべてのライブパイプラインを一覧表示します。

Request

  {
        "@apiVersion": "1.1"
  }

Response

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-05-05T14:19:22.16Z",
        "lastModifiedAt": "2021-05-05T16:20:41.505Z"
      },      
      // first live pipeline payload  
    },
      "systemData": {
        "createdAt": "2021-05-06T14:19:22.16Z",
        "lastModifiedAt": "2021-05-06T16:20:41.505Z"
      },
      // next live pipeline payload
    }    
  ]
}

状態コード

条件	status code
エンティティが見つかりました	200
一般的なユーザーエラー	400 番台
エンティティが見つかりません	404
一般的なサーバーエラー	500 番台

livePipelineSet

そのようなライブパイプラインが存在しない場合は、指定された名前でライブパイプラインを作成するか、その名前を持つ既存のライブパイプラインを更新します。

重要な点:

ライブパイプラインは、"非アクティブ化" 状態のときは自由に更新できます。その他の状態では、一部の更新のみが許可されます。
ライブパイプラインは、すべての更新時に再検証されます。

Request

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}",
        "properties": {
            // Desired live pipeline properties
        }
  }

Response

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-05-11T18:16:46.491Z",
           "lastModifiedAt": "2021-05-11T18:16:46.491Z"
        },
        "name": "{livePipelineName}",
        "properties": {
            // Complete live pipeline
        }
    }
  }

状態コード

条件	status code	詳細エラーコード
既存のエンティティが更新されました	200	該当なし
新しいエンティティが作成されました	201	該当なし
一般的なユーザーエラー	400 番台	該当なし
ライブパイプラインの検証エラー	400	PipelineValidationError
モジュール検証エラー	400	ModuleValidationError
リソース検証エラー	409	ResourceValidationError
一般的なサーバーエラー	500 番台	該当なし

livePipelineDelete

1 つのライブパイプラインを削除します。

重要な点:

削除できるのは非アクティブ化されたライブパイプラインのみです。

Request

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"
  }

Response

  {
    "status": 200,
    "payload": null
  }

状態コード

条件	status code	詳細エラーコード
ライブパイプラインが正常に削除されました	200	該当なし
ライブパイプラインが見つかりません	204	該当なし
一般的なユーザーエラー	400 番台
パイプラインは「非アクティブ化」状態ではありません	409	OperationNotAllowedInState
一般的なサーバーエラー	500 番台

livePipelineGet

これは livePipelineTopologyGet に似ています。指定した名前のライブパイプラインが存在する場合は、それを取得します。

Request

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"       
  }

Response

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-05-06T10:28:04.560Z",
          "lastModifiedAt": "2021-05-06T10:28:04.560Z"
        },
        "name": "{livePipelineName}",
        // Complete live pipeline
      }
    ]
  }
}

状態コード

条件	status code
Success	200
一般的なユーザーエラー	400 番台
一般的なサーバーエラー	500 番台

livePipelineActivate

ライブパイプラインをアクティブ化します。

重要な点

ライブパイプラインが「アクティブ化中」または「アクティブ化」状態の場合、メソッドにより返されます。
ライブパイプラインに対するリスト/セット操作により、現在の状態が返されます。
ライブパイプラインが (一時的な) 「非アクティブ化中の」状態ではない限り、このメソッドを呼び出すことができます。
べき等性:
- 既に「アクティブ化」状態になっているライブパイプラインでの livePipelineActivate 呼び出しは、ライブパイプラインが非アクティブ化された場合と同じように動作します。
- 「アクティブ」状態のパイプラインをアクティブ化すると、すぐに成功コードが返されます。

Request

  {
        "@apiVersion": "1.1",
        "name": "{livePipelineName}"
  }

Response

{
    "status": 200,
    "payload": null
}

状態コード

条件	status code	詳細エラーコード
パイプラインが正常にアクティブ化されました	200	該当なし
新しいエンティティが作成されました	201	該当なし
一般的なユーザーエラー	400 番台
モジュール検証エラー	400	ModuleValidationError
リソース検証エラー	409	ResourceValidationError
ライブパイプラインが非アクティブ化状態です	409	OperationNotAllowedInState
一般的なサーバーエラー	500 番台

livePipelineDeactivate

ライブパイプラインを非アクティブ化します。パイプラインを非アクティブ化すると、ビデオ処理が正常に非アクティブ化され、エッジに一時的に格納されたイベントとビデオがある場合は、すべてがクラウドに確実にコミットされます。

重要な点:

メソッドからは、パイプラインが非アクティブになったときにだけ戻ります
ライブパイプラインが (一時的な) 「アクティブ化中の」状態ではない限り、このメソッドを呼び出すことができます。
非アクティブ化が行われている間、パイプラインは「非アクティブ化中」状態とみなされます。
- ライブパイプラインに対するリスト/セット操作により、現在の状態が返されます。
- すべてのメディアがクラウドにアップロードされると、非アクティブ化が完了します (パイプラインにビデオシンクノードがある場合)。
べき等性:
- 既に「非アクティブ化中の」状態であるライブパイプラインでの livePipelineDeactivate 呼び出しは、ライブパイプラインが「アクティブ化」の状態であると同じように動作します。
- 「不アクティブ」状態のパイプラインをア非クティブ化すると、すぐに成功コードが返されます。

Request

  {
    "@apiVersion": "1.1",
    "name": "{livePipelineName}"
  }

Response

{
 "status": 200,
 "payload": null
}

条件	status code	詳細エラーコード
パイプラインが正常にアクティブ化されました	200	該当なし
新しいエンティティが作成されました	201	該当なし
一般的なユーザーエラー	400 番台
パイプラインがアクティブ化中の状態です	409	OperationNotAllowedInState
一般的なサーバーエラー	500 番台

remoteDeviceAdapterList

すべてのリモートデバイスアダプターを一覧表示します。 Video Analyzer エッジモジュールはビデオの透過的なゲートウェイとして機能し、IoT デバイスがファイアウォールの背後からクラウドにビデオを送信できるようになります。このような IoT デバイスごとに、リモートデバイスアダプターを作成する必要があります。その後、クラウドと IoT デバイス間の通信は、Video Analyzer エッジモジュールを介して行われます。

Request

  {
        "@apiVersion": "1.1"
  }

Response

{
  "status": 200,
  "value": [
    {
      "systemData": {
        "createdAt": "2021-10-05T14:19:22.16Z",
        "lastModifiedAt": "2021-10-05T16:20:41.505Z"
      },      
      // first remote device adapter payload
    },
      "systemData": {
        "createdAt": "2021-10-06T14:19:22.16Z",
        "lastModifiedAt": "2021-10-06T16:20:41.505Z"
      },
      // next remote device adapter  payload
    }    
  ]
}

状態コード

条件	status code
エンティティが見つかりました	200
一般的なユーザーエラー	400 番台
エンティティが見つかりません	404
一般的なサーバーエラー	500 番台

remoteDeviceAdapterSet

指定された名前のリモートデバイスアダプターが存在しない場合は、そのアダプターを作成します。または、その名前を持つ既存のアダプターを更新します。応答ペイロードで、および remoteDeviceAdapterList または remoteDeviceAdapterGet の呼び出しで、資格情報またはシークレットは省略されます。

Request

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}",
        "properties": {
            // Desired remote device adapter properties
        }
  }

Response

  {
    "status": 201,
    "payload": {
        "systemData": {
           "createdAt": "2021-10-11T18:16:46.491Z",
           "lastModifiedAt": "2021-10-11T18:16:46.491Z"
        },
        "name": "{remoteDeviceAdapterName}",
        "properties": {
            // Remote device adapter properties, except the credentials
        }
    }
  }

状態コード

条件	status code	詳細エラーコード
既存のエンティティが更新されました	200	該当なし
新しいエンティティが作成されました	201	該当なし
一般的なユーザーエラー	400 番台	該当なし
リモートデバイスアダプターの検証エラー	400	RemoteDeviceAdapterValidationError
モジュール検証エラー	400	ModuleValidationError
リソース検証エラー	409	ResourceValidationError
一般的なサーバーエラー	500 番台	該当なし

remoteDeviceAdapterGet

これは livePipelineTopologyGet に似ています。指定した名前のリモートデバイスアダプターが存在する場合は、そのアダプターを取得します (資格情報またはシークレットは省略されます)。

Request

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}"       
  }

Response

{
  "status": 200,
  "payload": {
    "value": [
      {
        "systemData": {
          "createdAt": "2021-10-06T10:28:04.560Z",
          "lastModifiedAt": "2021-10-06T10:28:04.560Z"
        },
        "name": "{remoteDeviceAdapterName}",
        // Remote device adapter properties, except the credentials
      }
    ]
  }
}

状態コード

条件	status code
Success	200
一般的なユーザーエラー	400 番台
一般的なサーバーエラー	500 番台

remoteDeviceAdapterDelete

1 つのリモートデバイスアダプターが存在する場合は、アダプターを削除します。

Request

  {
        "@apiVersion": "1.1",
        "name": "{remoteDeviceAdapterName}"
  }

Response

  {
    "status": 200,
    "payload": null
  }

状態コード

条件	status code	詳細エラーコード
リモートデバイスアダプターが正常に削除されました	200	該当なし
リモートデバイスアダプターが見つかりません	204	該当なし
一般的なユーザーエラー	400 番台
一般的なサーバーエラー	500 番台

onvifDeviceDiscover と onvifDeviceGet

これらの呼び出しの詳細については、ONVIF 対応デバイスの検出に関する記事をご覧ください。

次のステップ

モジュールツインの構成スキーマ

Azure Video Analyzer のダイレクト メソッド

規則

ダイレクト メソッドからの応答の例

エラー コード

サポートされているダイレクト メソッド

pipelineTopologyList

Request

Response

状態コード

pipelineTopologySet

Request

Response

状態コード

pipelineTopologyGet

Request

Response

状態コード

pipelineTopologyDelete

Request

Response

状態コード

livePipelineList

Request

Response

状態コード

livePipelineSet

Request

Response

状態コード

livePipelineDelete

Request

Response

状態コード

livePipelineGet

Request

Response

状態コード

livePipelineActivate

Request

Response

状態コード

livePipelineDeactivate

Request

Response

remoteDeviceAdapterList

Request

Response

状態コード

remoteDeviceAdapterSet

Request

Response

状態コード

remoteDeviceAdapterGet

Request

Response

状態コード

remoteDeviceAdapterDelete

Request

Response

状態コード

onvifDeviceDiscover と onvifDeviceGet

次のステップ

Azure Video Analyzer のダイレクトメソッド

ダイレクトメソッドからの応答の例

エラーコード

サポートされているダイレクトメソッド