This document introduces you how to operate some functions of device management through API. Please be familiar with the relevant information before reading this documentCore conceptsAnd confirm that you have completed the steps of creating a manufacturer and a product on the console of Dujia's AIOT voice platform. Please refer toquick get start。
2. Interface overview
At present, Dujia's AIOT voice platform provides the following device management interfaces. Note that "ak" and "sk" in the table below are the parameters corresponding to fc and pk in the device management API, not Baidu Cloud Authentication's Access Key (AK) and Secret Access Key (SK).
Interface type
describe
Batch (single) equipment import
Dynamically import device ak and sk information, and call voice service after importing device information
Delete device (single)
Delete a single device according to ak information, and the consumed device management quota will not be returned after the device is deleted
Disable device (single)
It is prohibited for a single device to call the cloud voice service, which is used to manage the devices with abnormal calls, to avoid unprovoked consumption of voice service quota
Enable device (single)
Restore the disabled device. After the device is enabled, the cloud service can be called normally
Get device information (single)
Return the details of a single device. See the specific interface for details
Get device information (list)
Return the information of all devices under the same product, see the specific interface for details
3. General Description
API calls follow the HTTPS protocol. Currently, only BJ Region is supported. The specific domain name is smarthome.baidubce.com.The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.
3.1 Real name authentication
Users who use the SHC API need real name authentication. Those who do not pass the real name authentication can go toBaidu Intelligent Cloud Official Website ConsoleAuthenticate in real name authentication under security authentication in.Baidu Cloud provides two authentication methods: personal authentication and enterprise authentication. You can choose one according to the actual situation.
3.2 API certification mechanism
Access Key and request signature mechanisms are used for security authentication of all APIs.The Access Key consists of the Access Key ID and the Secret Access Key, both of which are strings.For each HTTP request, generate an authentication string using the algorithm described below.The submitted authentication string is placed in the Authorization header field.The server verifies the correctness of the authentication string according to the generation algorithm.The format of the authentication string isbce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}。
Version is a positive integer.
Timestamp is the UTC time when the signature is generated.
ExpirationPeriodInSeconds indicates the validity period of the signature.
SignedHeaders is the list of header fields involved in the signature algorithm.The header names are separated by semicolons (;), such as host;x-bce-date。The list is arranged lexicographically.(This API signature only uses host and x-bce-date headers)
Signature is the hexadecimal representation of 256 bit signatures, which consists of 64 lowercase letters.
When Baidu Cloud receives the user's request, the system will use the same SK and the same authentication mechanism to generate the authentication string and compare it with the authentication string contained in the user's request.If the authentication string is the same, the system thinks that the user has the specified operation authority and executes the related operations;If the authentication string is different, the system will ignore the operation and return an error code.
The data exchange format is JSON, and all request/response body contents are encoded in UTF-8.
The request parameters include the following 4 types:
Parameter type
explain
URI
Usually used to indicate the operation entity, such as POST/v {version}/instance/{instanceId}
Query parameter
The request parameter carried in the URL is usually used to indicate the action to be performed on the entity
HEADER
Incoming through the HTTP header, such as x-bce-date
RequestBody
Request data body organized by JSON format
3.5 Response structure description
The response value is divided into two forms:
Response content
explain
HTTP STATUS CODE
For example, 200400403404
ResponseBody
Response data body organized in JSON format
3.6 API version number
parameter
type
Parameter position
describe
Must
version
String
URI parameter
API version number, the current value is 1
must
3.7 Date and time specification
There are many ways to express date and time.For the sake of uniformity, unless it is established by convention or has corresponding specifications, all places that need date and time expression shall adopt Beijing TimeISO 8601, and make the following constraints:
The date is always usedYYYY-MM-DDMode, such as2014-06-01Represents June 1, 2014.
Indicate that the time shall be adoptedhh:mm:ssMode, such as23:00:10It means 23:0:10 Beijing time.
Where the combined representation of date and time is involved, add a space between them, for example2014-06-01 23:00:10It means 23:0:10 Beijing time on June 1, 2014.
3.8 Normalized string
Generally, a string can contain any Unicode character.This flexibility can cause many problems in programming.Therefore, the concept of "canonical string" is introduced.A specification string only contains percent encoded characters and URI (Uniform Resource Identifier) unreserved characters.RFC 3986 stipulates that URI non reserved characters include the following characters: letters (A-Z, a-z), numbers (0-9), hyphens (-), periods (.), underscores (_), wavy lines (~).
The way to convert any string to a standard string is:
Converts a string to a UTF-8 encoded byte stream.
Keep all URI non reserved characters unchanged.
For the remaining bytes, do the Percent Encoding specified in RFC 3986, that is, a% followed by two hexadecimal letters representing the value of the byte.All letters shall be capitalized.
Example:Original string:This is an example for testing,Corresponding specification string:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95。
3.9 Product coding requirements of Dujia AIOT voice platform
Parsable content. All request/response body content is currently encoded in UTF-8, and more encoding types will be supported later.
UrlEncode the following when requesting:
Objectname,The resource needs to ignore "/" when doing UrlEncode.
Value of Querystring.
X-bce-copy-source (ignoring "/").
Custom Meta: Meta Values only support visible ASCII characters. If other characters are needed, UrlEncode is recommended.
3.10 Dujia AIOT voice platform service domain name
region
Service Endpoint
agreement
Beijing
smarthome.baidubce.com
HTTPS
3.11 Public Request Header and Public Response Header
Public request header
Header field
explain
Must
Authorization
Include Access Key and request signature.Please refer toAuthentication
must
Content-Type
application/json; charset=utf-8
must
x-bce-date
The time when the request is created indicates the date in YYYY-MM-DD mode. For example, 2014-06-01 indicates June 1, 2014.If the user uses the standard Date field, the header field can be left blank.When both exist, x-bce-date shall prevail.
must
Public response header
Header field
explain
Content-Type
application/json; charset=utf-8
x-bce-request-id
The requestId of the corresponding request
3.12 Error code
Error code format
When an error occurs when the user accesses the API, it will return the corresponding error code and error information to the user, so that the problem can be located and handled properly.When an error occurs in the request, the response body returns the detailed error information in the following format:
Parameter name
type
explain
code
String
Indicates the specific error type.
message
String
Detailed description of the error.
requestId
String
The requestId that caused the error.
For example:
{ "code":"IllegalRequestUrl", "message":"The requested url belongs to domain which is not under acceleration","requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7" }
Public error code
Error code
Error message
HTTP status code
describe
AccessDenied
Access denied.
403 Forbidden
No permission to access the corresponding resource.
InappropriateJSON
The JSON you provided was well-formed and valid, but not appropriate for this operation.
400 Bad Request
The JSON format in the request is correct, but the semantics do not meet the requirements.For example, a required item is missing or the value type does not match.For compatibility reasons, all unrecognized items should be ignored directly and this error should not be returned.
InternalError
We encountered an internal error. Please try again.
500Internal Server Error
All other undefined errors.It should not be used when there are other types of errors (including general and service customized) that have clear corresponding.
InvalidAccessKeyId
The Access Key ID you provided does not exist in our records.
403 Forbidden
Access Key ID does not exist.
InvalidHTTPAuthHeader
The HTTP authorization header is invalid. Consult the service documentation for details.
400 Bad Request
The format of the Authorization header field is incorrect.
InvalidHTTPRequest
There was an error in the body of your HTTP request.
400 Bad Request
The HTTP body format is incorrect.For example, the specified Encoding is not met.
InvalidURI
Could not parse the specified URI.
400 Bad Request
The URI format is incorrect.For example, the keywords of some service definitions do not match.For problems such as ID mismatch, more specific error codes should be defined, such as NoSuchKey.
MalformedJSON
The JSON you provided was not well-formed.
400 Bad Request
The JSON format is illegal.
InvalidVersion
The API version specified was invalid.
404 Not Found
The version number of the URI is illegal.
OptInRequired
A subscription for the service is required.
403 Forbidden
The corresponding service is not activated.
PreconditionFailed
The specified If-Match header doesn't match the ETag header.
412 Precondition Failed
See ETag for details.
RequestExpired
Request has expired. Timestamp date is XXX.
400 Bad Request
The request timed out.XXX should be changed to the value of x-bce-date.If there is only Date in the request, you need to convert Date to datetime.
IdempotentParameterMismatch
The request uses the same client token as a previous, but non-identical request.
403 Forbidden
The API parameters corresponding to clientToken are different.
SignatureDoesNotMatch
The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details.
400 Bad Request
The signature attached in the Authorization header field is inconsistent with the server verification.
Description of customized error code of Dujia AIOT voice platform
Error code
Error message
describe
zero
OK
normal
one
Missing fc Parameter
Missing fc parameter
two
Missing pk Parameter
Missing pk parameter
three
FC Not Found
Fc does not exist
four
PK Not Found
Pk does not exist
five
CSV Format Error or Missing ak/sk Parameter.
Csv format error or missing ak/sk parameter
six
Import Device Batch Error: Max Batch Size is 1000.
Maximum number of imported devices per time 1000
seven
AK Duplicated.
Duplicate ak exists under pk
eight
Read File Error.
Failed to read the csv file
nine
Empty File Error.
The csv file is empty
ten
Insufficient Quota Error.
Insufficient equipment management quota
eleven
Device Not Found.
Device does not exist
twelve
Generate TTS Url Error.
Failed to synthesize audio file
4. Device management API
4.1 Batch (single) import equipment
essential information
Path:/v1/manage/device
Method:POST
Request Parameters
Body
name
type
Must
Default
remarks
Other information
fc
string
must
pk
string
must
devices
string []
must
Item type:string
├─
must
CSV string: ak, sk
Return Data
name
type
Default
remarks
Other information
code
number
See SHC custom code description
message
string
Return to Example
{ "code":0, "message":""}
4.2 Deleting a device (single)
essential information
Path:/v1/manage/device/:fc/:pk/:ak
Method:DELETE
Path parameter
Parameter name
Example
remarks
fc
jagu79
pk
u2wdh3wm
ak
one hundred billion six hundred and ninety-one thousand nine hundred and thirty
Return Data
name
type
Default
remarks
Other information
result
string
Return to Example
{ "result":"OK"}
4.3 Disabled device (single)
essential information
Path:/v1/manage/device/:fc/:pk/:ak/disable
Method:PUT
Path parameter
Parameter name
Example
remarks
fc
jagu79
pk
u2wdh3wm
ak
one hundred billion six hundred and ninety-one thousand nine hundred and thirty
Return Data
name
type
Must
Default
remarks
Other information
result
string
Not required
Return to Example
{ "result": "OK"}
4.4 Enable equipment (single)
essential information
Path:/v1/manage/device/:fc/:pk/:ak/enable
Method:PUT
Path parameter
Parameter name
Example
remarks
fc
jagu79
pk
u2wdh3wm
ak
one hundred billion six hundred and ninety-one thousand nine hundred and thirty