直接方法Direct methods

IoT Edge 上的实时视频分析公开了可以从 IoT 中心调用的多种直接方法。Live Video Analytics on IoT Edge exposes several direct methods that can be invoked from IoT Hub. 直接方法表示与设备进行的请求-答复式交互,类似于会立即成功或失败(在用户指定的超时时间后)的 HTTP 调用。Direct methods represent a request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a user-specified timeout). 此方法用于即时操作过程不同的情况,即时操作的不同取决于设备能否响应。This approach is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond. 有关详细信息,请参阅了解直接方法并从 IoT 中心进行调用For more information, see Understand and invoke direct methods from IoT Hub.

本主题介绍这些方法和约定。This topic describes these methods and conventions.

约定Conventions

直接方法基于以下约定:The direct methods are based on the following conventions:

  1. 直接方法具有以 MAJOR.MINOR 格式指定的版本(如以下示例所示):Direct methods have a version specified in MAJOR.MINOR format (as shown in the following example):

    {
        "methodName": "GraphTopologySet",
        "payload": {
            // API version matches matches module MAJOR.MINOR version
            "@apiVersion": "1.0"
            //payload here…
        }
    }
    
  2. IoT Edge 模块上实时视频分析的给定版本支持直至其当前版本的所有直接方法。A given version of Live Video Analytics on IoT Edge module will support all the direct methods up-to its current version. 例如,模块版本 1.3 将支持版本 1.3、1.2、1.1 和 1.0 版本的直接方法。For example, module version 1.3 will support direct methods with versions 1.3, 1.2, 1.1, and 1.0 versions.

  3. 所有直接方法都是同步的。All direct methods are synchronous.

  4. 错误结果遵循 OData 错误架构。Error results follow OData error schema.

  5. 名称应遵守以下约束:Names should observe the following constraints:

    • 仅限字母数字字符和短划线,不能以短划线开头和结尾Only alphanumeric characters and dashes as long as it doesn't start and end with a dash
    • 不含空格No spaces
    • 最多 32个字符Max of 32 characters

示例Example

{
  "status": 400,
  "payload": {
    "error": {
      "code": "BadRequest",
      "message": "Graph instance is not found."
    }
  }
}

顶层错误代码Top-level error codes

状态Status 代码Code MessageMessage
400400 BadRequestBadRequest 请求无效Request is not valid
400400 InvalidResourceInvalidResource 资源无效。Resource is not valid
400400 InvalidVersionInvalidVersion API 版本无效API version is not valid
402402 ConnectivityRequiredConnectivityRequired Edge 模块需要云连接才能正常工作。Edge module requires cloud connectivity to properly function.
404404 NotFoundNotFound 未找到资源Resource was not found
409409 ConflictConflict 操作冲突Operation conflict
500500 InternalServerErrorInternalServerError 内部服务器错误Internal server error
503503 ServerBusyServerBusy 服务器繁忙Server busy

详细错误代码Detailed error codes

添加了详细的验证错误(如图形模块验证)作为错误详细信息:Detailed validations error, such as graph module validations, are added as error details:

{
  "status": 400,
  "payload": {
    "error": {
      "code": "InvalidResource",
      "message": "The resource format is invalid.",
      "details": [
        {
          "code": "RtspEndpointUrlInvalidScheme",
          "target": "$.Properties.Sources[0]",
          "message": "Uri scheme 'http' is not valid for an RTSP source endpoint. Valid values are: rtsp"
        },
        {
          "code": "PropertyValueInvalidPattern",
          "target": "$.Properties.Sinks[0].AssetNamePattern",
          "message": "The value must match the regular expression '^[^<>%&:\\\\\\/?*+.']{1,260}$'"
        }
      ]
    }
  }
}
}
状态Status 详细代码Detailed code 说明Description
400400 GraphValidationErrorGraphValidationError 常规图形错误,如循环或分区等。General graph errors such as cycles or partitioning, etc.
400400 ModuleValidationErrorModuleValidationError 模块特定的验证错误。Module specific validation errors.
409409 GraphTopologyInUseGraphTopologyInUse 一个或多个图形实例仍在引用图形拓扑。Graph topology is still referenced by one or more graph instances.
409409 OperationNotAllowedInStateOperationNotAllowedInState 无法在当前状态下执行请求的操作。Requested operation cannot be performed in the current state.
409409 ResourceValidationErrorResourceValidationError 引用的资源(示例:资产)处于无效状态。Referenced resource (example: asset) is not in a valid state.

详细信息Details

GraphTopologyGetGraphTopologyGet

此直接方法检索单个图形拓扑。This direct method retrieves a single graph topology.

请求Request

{
    "methodName": "GraphTopologyGet",
    "payload": {
        "@apiVersion": "1.0",
        "name": "CaptureAndRecord"
    }
}

响应Response

{
    "status": 200,
    "payload": {
        "name": "CaptureAndRecord",
        "properties": {
            // Complete graph topology
        }
    }
}

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已找到实体Entity found 200200 空值N/A
一般用户错误General user errors 400 range400 range
找不到实体Entity not found 404404
一般服务器错误General server errors 500 range500 range

GraphTopologySetGraphTopologySet

如果不存在具有给定名称或更新的拓扑,并且不存在同名的现有拓扑,则创建一个拓扑。Creates a single topology if there is no existing one with the given name or updates and existing one with the same name.

关键方面:Key aspects:

  • 如果没有图形引用拓扑,则可以自由更新拓扑。Topology can be freely updated is there are no graph referencing it.

  • 如果停用所有引用关系图,只要满足以下情况,就可以自由更新拓扑:Topology can be freely updated if all referencing graphs are deactivated as long as:

    • 新添加的参数具有默认值Newly added parameters have default values
    • 任何图形均未引用已删除的参数Removed parameters are not referenced by any graph
  • 如果存在活动图,则不允许拓扑更新Topology updates are not allowed if there are active graphs

请求Request

{
    "methodName": "GraphTopologySet",
    "payload": {
        "@apiVersion": "1.0",
        "name": "CaptureAndRecord",
        "properties": {
            // Desired graph topology properties
        }
    }
}

响应Response

{
    "status": 201,
    "payload": {
        "name": " CaptureAndRecord ",
        "properties": {
            // Complete graph topology
        }
    }
}

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已更新现有实体Existing entity updated 200200 空值N/A
已创建新的实体New entity created 201201 空值N/A
一般用户错误General user errors 400 range400 range
图形验证错误Graph Validation Errors 400400 GraphValidationErrorGraphValidationError
模块验证错误Module Validation Errors 400400 ModuleValidationErrorModuleValidationError
一般服务器错误General server errors 500 range500 range

GraphTopologyDeleteGraphTopologyDelete

删除单个图形拓扑。Deletes a single graph topology.

请求Request

{
    "methodName": "GraphTopologyDelete",
    "payload": {
        "@apiVersion": "1.0",
        "name": "CaptureAndRecord"
    }
}

响应Response

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

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已删除实体Entity deleted 200200 空值N/A
找不到实体Entity not found 204204 空值N/A
一般用户错误General user errors 400 range400 range
一个或多个图形实例正在引用图形拓扑Graph topology is being referenced by one or more graph instances 409409 GraphTopologyInUseGraphTopologyInUse
一般服务器错误General server errors 500 range500 range

GraphTopologyListGraphTopologyList

检索所有符合筛选条件的图形拓扑的列表。Retrieves a list of all the graph topologies that matches the filter criteria.

请求Request

{
    "methodName": "GraphTopologyList",
    "payload": {
        // Required
        "@apiVersion": "1.0",
        
        // Optional
        "@continuationToken": "xxxxx",    
        "@query": "$orderby=name asc"
    }
}

响应Response

{
    "status": 200,
    "payload": {
        "@continuationToken": "xxxx",
        "value": [
            {
                "name": "Capture & Record",
                // ...
            },
            {
                "name": "Capture, Analyze & Record",
                // ...
            }
        ]
    }
}

筛选器支持Filter support

操作Operation 字段Field(s) 运算符Operators
$orderby$orderby namename ascasc

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
SuccessSuccess 200200 空值N/A
一般用户错误General user errors 400 range400 range
一般服务器错误General server errors 500 range500 range

GraphInstanceGetGraphInstanceGet

检索单个图形实例:Retrieves a single Graph Instance:

请求Request

{
    "methodName": "GraphInstanceGet",
    "payload": {
        "@apiVersion": "1.0",
        "name": "Camera001"
    }
}

响应Response

{
    "status": 200,
    "payload": {
        "name": "Camera001",
        "properties": {
            // Complete graph instance
        }
    }
}

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已找到实体Entity found 200200 空值N/A
一般用户错误General user errors 400 range400 range
找不到实体Entity not found 404404
一般服务器错误General server errors 500 range500 range

GraphInstanceSetGraphInstanceSet

如果不存在具有给定名称或更新的图形实例,并且不存在同名的现有图形实例,则创建单个图形实例。Creates a single Graph Instance if there is no existing one with the given name or updates and existing one with the same name.

关键方面:Key aspects:

  • 图形实例处于“已停用”状态时可以自由更新。Graph Instance can be freely updated while in "Deactivated" state.

    • 每次更新时都会重新验证图形。Graph is revalidated on every updated.
  • 图形不处于“非活动”状态时,图形实例更新受到部分限制。Graph instance updates are partially restricted while the graph is not in the “Inactive” state.

  • 不允许对活动图形更新图形实例。Graph instance updates are not allowed on active graphs.

请求Request

{
"methodName": "GraphInstanceSet",
    "payload": {
        "@apiVersion": "1.0",
        "name": "Camera001",
        "properties": {
            // Desired graph instance properties
        }
    }
}

响应Response

{
    "status": 201,
    "payload": {
        "name": " Camera001",
        "properties": {
            // Complete graph instance
        }   
    }
}

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已更新现有实体Existing entity updated 200200 空值N/A
已创建新的实体New entity created 201201 空值N/A
一般用户错误General user errors 400 range400 range
图形验证错误Graph Validation Errors 400400 GraphValidationErrorGraphValidationError
模块验证错误Module Validation Errors 400400 ModuleValidationErrorModuleValidationError
资源验证错误Resource validation errors 409409 ResourceValidationErrorResourceValidationError
一般服务器错误General server errors 500 range500 range

GraphInstanceDeleteGraphInstanceDelete

删除单个图形实例。Deletes a single graph instance.

关键方面:Key aspects:

  • 只能删除已停用的图形。Only deactivated graphs can be deleted.

请求Request

{
    "methodName": "GraphInstanceDelete",
    "payload": {
        "@apiVersion": "1.0",
        "name": "Camera001"
    }
}

响应Response

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

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已成功删除图形Graph deleted successfully 200200 空值N/A
找不到图形Graph not found 204204 空值N/A
一般用户错误General user errors 400 range400 range
图形不处于“已停止”状态Graph is not in the "Stopped" state 409409 OperationNotAllowedInStateOperationNotAllowedInState
一般服务器错误General server errors 500 range500 range

GraphInstanceListGraphInstanceList

这类似于 GraphTopologyList。This is similar to GraphTopologyList. 它可以用来枚举图形实例。It enables use to enumerate the graph instances. 检索所有符合筛选条件的图形实例的列表。Retrieves a list of all the graphs instances that matches the filter criteria.

请求Request

{
    "methodName": "GraphInstanceList",
    "payload": {
        // Required
        "@apiVersion": "1.0",
        
        // Optional
        "@continuationToken": "xxxxx",    
        "@query": "$orderby=name asc"
    }
}

响应Response

{
    "status": 200,
    "payload": {
        "@continuationToken": "xxxx",
        "value": [
            {
                "name": "Capture & Record",
                // ...
            },
            {
                "name": "Capture, Analyze & Record",
                // ...
            }
        ]
    }
}

筛选器支持Filter support

操作Operation 字段Field(s) 运算符Operators
$orderby$orderby namename ascasc

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
SuccessSuccess 200200 空值N/A
一般用户错误General user errors 400 range400 range
一般服务器错误General server errors 500 range500 range

GraphInstanceActivateGraphInstanceActivate

激活单个图形实例。Activates a single graph instance.

关键方面Key aspects

  • 方法仅在激活图形后返回Method only returns when graph is activated

  • 图形在激活时处于“正在激活”状态。Graph assumes the "Activating" state while being activated.

    • 对图形进行 List/Get 操作将返回处于正确状态的图形。A List/Get operation on the graph would return the graph on the proper state.
  • 幂等性:Idempotency:

    • 在“正在激活”状态下启动图形的行为与停用图形的行为相同(即:调用块直到图形被激活)Starting a graph on "Activating" state behaves the same way as if the graph was deactivated (that is: call blocks until graph is activated)
    • 在“活动”状态下激活图形会立即成功返回。Activating a graph on "Active" state returns successfully immediately.

请求Request

{
    "methodName": "GraphInstanceActivate",
    "payload": {
        "@apiVersion": "1.0",
        "name": "Camera001"
    }
}

响应Response

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

状态代码Status codes

条件Condition 状态代码Status code 详细错误代码Detailed error code
已成功激活图形Graph activated successfully 200200 空值N/A
已创建新的实体New entity created 201201 空值N/A
一般用户错误General user errors 400 range400 range
模块验证错误Module validation errors 400400 ModuleValidationErrorModuleValidationError
资源验证错误Resource validation errors 409409 ResourceValidationErrorResourceValidationError
图形处于“正在停用”状态Graph is in deactivating state 409409 OperationNotAllowedInStateOperationNotAllowedInState
一般服务器错误General server errors 500 range500 range

GraphInstanceDeactivateGraphInstanceDeactivate

停用单个图形实例。Deactivates a single graph instance. 停用图形可以适当地停用媒体处理,并确保在适当的情况下将临时存储在边缘上的所有事件和媒体都提交到云中。Deactivating a graph gracefully deactivates the media processing and ensures that all events and media transiently stored on edge is committed to cloud, whenever applicable.

关键方面:Key aspects:

  • 方法仅在停用图形后返回Method only returns when graph is deactivated

  • 图形在停用时处于“正在停用”状态。Graph assumes the "Deactivating" state while being deactivated.

    • 对图形进行 List/Get 操作将返回处于正确状态的图形。A List/Get operation on the graph would return the graph on the proper state.
    • 停止仅在所有媒体都已上传到云后完成。Stop only completes when all media has been uploaded to the cloud.
  • 幂等性:Idempotency:

    • 在“正在停用”状态下停用图形的行为与停用图形的行为相同(即:调用块直到图形被停用)Deactivating a graph on "Deactivating" state behaves the same way as if the graph was deactivated (that is: call blocks until graph is deactivated)
    • 在“非活动”状态下停用图形会立即成功返回。Deactivating a graph on "Inactive" state returns successfully immediately.

请求Request

{
    "methodName": "GraphInstanceDeactivate",
    // A high response timeout is recommended here since there might be data movement    // being executed as part of this operation
    "responseTimeoutInSeconds": 300,
    "payload": {
        "@apiVersion": "1.0",
        "name": "Camera001"
    }
}

响应Response

{
    "status": 200,
    "payload": null
}
条件Condition 状态代码Status code 详细错误代码Detailed error code
已成功激活图形Graph activated successfully 200200 空值N/A
已创建新的实体New entity created 201201 空值N/A
一般用户错误General user errors 400 range400 range
图形处于“正在激活”状态Graph is in activating state 409409 OperationNotAllowedInStateOperationNotAllowedInState
一般服务器错误General server errors 500 range500 range

后续步骤Next steps

模块孪生配置架构Module Twin configuration schema