Help Center> IoT Device Access> SDK Reference> Old SDKs> Application Java SDK API Reference> Command Delivery> Calling a Device Service
View PDF

Calling a Device Service

Typical Scenario

The device's product model defines commands that the platform can deliver to a device. When an application needs to configure or modify the service properties of a device, the application can call this API to deliver commands to the device.

The platform does not cache commands but delivers commands directly. When a device is offline, the commands fail to be delivered. The formats of the delivered command need to be defined by the applications and devices. The platform encapsulates and transparently transmits the commands over this API.

This API applies to devices that use MQTT, for example, devices integrated with the AgentLite SDK.

API Function

This API is used by applications to deliver commands to MQTT devices or used to deliver commands to devices that belong to the current application.

API Description

1
 
InvokeDeviceServiceOutDTO invokeDeviceService(String deviceId, String serviceId, CommandDTO2 commandDTO, String appId, String accessToken) throws NorthApiException

Parameter Description

Parameter

Mandatory or Optional

Type

Location

Description

deviceId

Mandatory

String(1-64)

path

Identifies a device.

serviceId

Mandatory

String(1-64)

path

Uniquely identifies a service.

commandDTO

Mandatory

CommandDTO2 structure

body

For details, see CommandDTO2 structure.

appId

Mandatory

String

query

If the device belongs to the current application, set this parameter to null. Otherwise, set this parameter to the ID of the authorized application.

accessToken

Mandatory

String

header

If the Periodically Refreshing a Token API is called, set this parameter to null. Otherwise, set this parameter to the accessToken obtained by the Authentication API.

CommandDTO2 structure

Parameter

Mandatory or Optional

Type

Location

Description

header

Mandatory

CommandNA2CloudHeader

body

For details, see CommandNA2CloudHeader structure.

body

Optional

Object

body

Indicates the message body. The content of the JsonObject is a list of key-value pairs. Every key is the paraName of a command defined in the product model.

CommandNA2CloudHeader structure

Parameter

Mandatory or Optional

Type

Location

Description

requestId

Optional

String(0-128)

body

Identifies a command. The value of this parameter must be unique.

mode

Mandatory

Enum

body

Indicates whether an ACK message is required.

  • NOACK: No ACK message is required.
  • ACK: An ACK message is required.
  • Other values: invalid

from

Optional

String(128)

body

Indicates the address of the message sender.

  • Request initiated by an application: /users/{userId}
  • Request initiated by an application: /{serviceName}
  • Request initiated by the platform: /cloud/{serviceName}

toType

Optional

Enum

body

Indicates the type of the message recipient. The value options are CLOUD and GATEWAY.

to

Optional

String(128)

body

Indicates the address of the message recipient.

method

Mandatory

String(1-32)

body

Indicates the command name. For example, a DISCOVERY command is used to discover indirectly connected devices, and a REMOVE command is used to delete indirectly connected devices.

callbackURL

Optional

String(1024)

body

Indicates the callback URL.

Response Parameters

InvokeDeviceServiceOutDTO structure

Parameter

Type

Description

status

String(128)

Indicates the command status.

  • sent: The command has been sent.
  • delivered: The command has been delivered. This value is returned when toType is set to CLOUD.
  • failed: The command fails to be delivered. This value is returned when toType is set to CLOUD.

timestamp

String(128)

Indicates the timestamp used for sending a command. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z.

requestId

String(128)

Identifies a device command.

  • When toType is set to GATEWAY, if requestId is carried in a request, the response carries the same requestId as the request; if requestId is not carried in a request, the platform allocates a sequence number for the response.
  • When toType is set to CLOUD, the value of this parameter is null.

Error Codes

HTTP Status Code

Error Code

Error Description

Remarks

200

100203

The application does not exist.

The application does not exist.

Recommended handling:

  • Check whether appId carried in the HTTP request header is correct.
  • Check whether appId in the request path (URL) is correct.

200

100217

The application has not been authorized.

The application has not been authorized.

Recommended handling: In scenarios where applications are not authorized, ensure that request parameter appId is null.

200

100418

The device data does not exist.

The device data does not exist.

Recommended handling:

  • If deviceId carried in the request is incorrect, check whether deviceId belongs to appId or whether deviceId is incorrect.
  • Check whether appId carried in the header contains deviceId.
  • If the URL contains the optional parameter appId, check whether the value of appId is correct.

200

100428

The device is not online.

The device is not online.

Recommended handling: Check whether the connection between the device and the gateway is normal.

200

100432

The device command is muted.

The device command is muted.

Recommended handling: Check whether the command carried in the API request parameter method is correct.

400

100022

An input parameter is invalid.

An input parameter is invalid.

Recommended handling: Check whether parameters carried in the API call request are valid.

400

102203

Invalid command name.

The command name is invalid.

Recommended handling: Check whether the command carried in the API request parameter method is correct.

403

100450

The gateway is not online.

The gateway is offline.

Recommended handling: Check whether the connection between the gateway and the IoT platform is normal.

403

1010009

The application calls the API at a frequency that exceeds the flow control threshold.

The application calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default).

Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency.

403

1010005

Invalid access token or application ID.

The access token is invalid.

Recommended handling: Check whether accessToken carried in the API request is correct.

404

100444

The service type does not exist.

The service type does not exist.

Recommended handling: Check whether the service type carried in the API request parameter toType is correct.

500

100001

Internal server error.

An internal server error occurs.

Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.

500

100023

The data in the database is abnormal.

The database is abnormal.

Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.

500

50252

Internal server error.

An internal server error occurs.

Recommended handling: An internal error occurs on the IoT platform. Contact IoT platform maintenance personnel.

503

100501

Congestion occurs, and the current network is under flow control.

Congestion occurs. The current network is under flow control.
Parent topic: Command Delivery