Managing capabilities of a device group

Transmits actions to a device group.

Request format

POST https://api.iot.yandex.net/v1.0/groups/{group_id}/actions

group_id

The ID of the user's device group

Request headers

Header	Description	Required
Authorization	The authorization token of the OAuth application.	Yes

Request body format

{
    "actions": [
        {
            "type": "devices.capabilities.{capability}",
            "state": {}
        }
    ]
}

Parameter	Type	Description	Required
actions	Array of objects	An array of actions for a device group.	Yes

actions array

Parameter	Type	Description	Required
capability1	CapabilityObject	Capability and command to change it.	No
capability2	CapabilityObject	Capability and command to change it.	No

CapabilityObject type

Parameter	Type	Description	Required
type	String	The type of the capability.	Yes
state	CapabilityStateObject	The target state of the capability. Corresponds to the value of the `state` field from the description of the command for managing the device capability.	Yes

Response format

Response successful

Response with error

Note

Devices in a group might react differently to the transmitted action, that's why the response returns the action result for each device in the group.

HTTP/1.1 200 OK

{
  "status": "ok",
  "request_id": String,
  "devices": [{
      "id": String,
      "capabilities": [{
        "type": String,
        "state": {
          "instance": String,
          "action_result": {
            "status": String
          }
        }
      }]
    },
    {
      "id": String,
      "capabilities": [{
        "type": String,
        "state": {
          "instance": String,
          "action_result": {
            "status": String
          }
        }
      }]
    }
  ]
}

Parameter	Type	Description	Required
request_id	String	Request ID. Must be logged for the purpose of incident investigation.	Yes
status	String	Status of processing the request. Acceptable values: `ok`.	Yes
devices	Array of DeviceActionsResultObjects	Results of performing actions on devices.	Yes

devices array

Parameter	Type	Description	Required
deviceActionsResult1	DeviceActionResultObject	The result of performing actions on the device.	No
deviceActionsResult2	DeviceActionResultObject	The result of performing actions on the device.	No

DeviceActionsResultObject type

Parameter	Type	Description	Required
id	String	Device ID	Yes
capabilities	CapabilityActionResultObject	Results of actions.	Yes

CapabilityActionResultObject type

Parameter	Type	Description	Required
type	String	The type of the capability.	Yes
state	StateResultObject	The state of the capability.	Yes

StateResultObject type

Parameter	Type	Description	Required
instance	String	The function of the capability.	Yes
action_result	ActionResultObject	The result of the action.	Yes

ActionResultObject type

Parameter	Type	Description	Required
status	String	Status of the device state change. Acceptable values: `DONE`: device state changed. `ERROR`: an error occurred when changing the device state.	Yes
error_code	String	An error code from the list of possible errors.	No
error_message	String	Extended human-readable description of a possible error.	No

HTTP/1.1 404 Not Found

{
    "request_id": String,
    "status": "error",
    "message": String
}

Parameter	Type	Description	Required
request_id	String	Request ID. Must be logged for the purpose of incident investigation.	Yes
status	String	Status of processing the request. Acceptable values: `error`.	Yes
message	String	Error message.	No

Error codes

Example

Request

Response successful

Response with error

curl --request POST 'https://api.iot.yandex.net/v1.0/groups/light-group-id-1/actions' \
--header 'Authorization: Bearer YOUR_OAUTH_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "actions": [
        {
            "type": "devices.capabilities.on_off",
            "state": {
                "instance": "on",
                "value": true
            }
        }
    ]
}'

HTTP/1.1 200 OK

{
  "status": "ok",
  "request_id": "35e9d24a-40f3-409d-b654-2cf4d87fe593",
  "devices": [{
      "id": "lamp-id-1",
      "capabilities": [{
        "type": "devices.capabilities.on_off",
        "state": {
          "instance": "on",
          "action_result": {
            "status": "DONE"
          }
        }
      }]
    },
    {
      "id": "lamp-id-2",
      "capabilities": [{
        "type": "devices.capabilities.on_off",
        "state": {
          "instance": "on",
          "action_result": {
            "status": "DONE"
          }
        }
      }]
    },
    {
      "id": "lamp-id-3",
      "capabilities": [{
        "type": "devices.capabilities.on_off",
        "state": {
          "instance": "on",
          "action_result": {
            "status": "DONE"
          }
        }
      }]
    }
  ]
}

HTTP/1.1 404 Not Found

{
    "request_id": "667b3e0f-47a8-4136-9211-b4ff59062315",
    "status": "error",
    "message": "Группа устройств не найдена"
}

List of "key": value pairs separated by commas. The list is enclosed in curly brackets {}.

{
  "name": "John",
  "surname": "Smith"
}

An array of elements separated by a comma. As array items, you can use standard JSON elements: a string, number, true, false, object, or array. Arrays are enclosed in square brackets []:

"cities": ["Moscow", "Tokyo", "New York"]

Was the article helpful?

Getting information about the status of a device group

Managing scenario launch