目录

Function

This API is used to query the list of all beacons under a service account.

Scenario

This API is called when the list of all beacons under the developer service account by pages.

Prototype

Protocol

HTTPS POST

Direction

App server or app -> HUAWEI Nearby Service server

URL

https://{Domain name}/WiseCloudNearbyBeaconService/v1/queryBeaconList?projectId=[projectId]

Data Format

Content-type: application/json

For details about how to obtain the domain name and projectID, please refer to API Call Process.

Restrictions

You need to obtain the service account credential. For details, please refer to Service Account-based Authentication.

Input Parameters

Parameter

Mandatory(M)/Optional (O)

Type

Description

timeStamp

M

Long

Timestamp in the request header.

srcTranID

M

String

Transaction ID in the request header. The value contains a maximum of 24 characters.

projectId

O

String

Project ID for query. 

Authorization

M

String

Parameter in the request header, which is used for gateway authentication. For details about how to obtain the JSON Web Token (JWT) of the parameter , please refer to Service Account-based Authentication.

upOrDown

M

int

Mode in the request body. Mode of the query by pages. The options are as follows: 1: backward; 2: forward

pageSize

M

int

Number of beacons found on one page, which is in the request body and used for pagination query. The maximum value is 100.

sequence

M

Long

Beacon sequence number in the request body, which is automatically generated by the system when a device is registered.

If upOrDown is set to 1, this parameter indicates the sequence number of the last beacon on the previous page.

If upOrDown is set to 2, this parameter indicates the sequence number (reported by the app) of the first beacon on the previous page.

status

O

String

Parameter in the request body, which is used to match the beacon in a specified state and return the result. The value is a character string consisting of 0 and 1. From the rightmost bit to the leftmost bit, the first bit indicates whether to match a beacon in activated state, the second bit indicates whether to match a beacon in deactivated state, and the third bit indicates whether to match a beacon in disabled state. The value 0 indicates the match failure, and the value 1 indicates the match success. For example, 00000001 indicates that an activated beacon is matched, 000000100 indicates that a disabled beacon is matched, and 000000101 indicates that an activated or a disabled beacon is matched.

If this parameter is not passed, the value 00000011 is used by default, indicating that the activated or deactivated beacon is matched. The value contains a maximum of eight characters.

property

O

String

Beacon attribute in the request body in a key-value pair, which is used to match a beacon. The value contains a maximum of 64 characters.

Output Parameters

If the request is successful, status code 200 is returned with a response body containing the following parameters.

Parameter

Type

Description

moreBeacon

int

Indicates whether more beacons exist. The value 1 indicates that more beacons exist and can be queried again. The value 0 indicates that there are no more beacons.

beacons

Json object

Beacon structure list. For details, please refer to the following definition of the beacons structure.

beacons structure definition:

  1. {
  2. "sequence": 1578643043892,
  3. "beaconDesc": "beacon1 test",
  4. "beaconType": 1,
  5. "beaconId": "beac0025",
  6. "status": 2
  7. }

Parameter

Type

Description

beaconId

String

Beacon ID.

beaconType

int

Beacon type.

beaconDesc

String

Beacon description.

status

int

Beacon status. The options are as follows: 1: activated; 2: deactivated; 3: disabled

sequence

Long

Beacon sequence number.

If the request fails, a status code other than 200 is returned with the following response body:

(1) A non-service request fails due to an exception (for example, the gateway verification fails or the token expires).

Parameter

Type

Description

error

String

Error message that is not returned by the service.

(2) A service request fails.

Parameter

Type

Description

serviceError

object

Error message that is returned by the service.

The JSON structure of serviceError is as follows.

Parameter

Type

Description

code

int

Result code. For details, please refer to the following result code table.

status

String

Error status.

message

String

Error description.

Result Code

Result Code

Description

Suggestion

400000001

Incorrect parameter in the request header.

Verify the request header parameter.

400000002

Incorrect parameter in the request body.

Verify the request body parameter.

403000003

The service account is unavailable.

Verify that the service account is available on the console of HUAWEI Developer.

500000001

Internal service error.

Contact Huawei technical support.

Example

Use an expired Authorization parameter to call the API. An error response body is returned.

Request:

  1. POST /WiseCloudNearbyBeaconService/v1/queryBeaconList?projectId=id123 HTTP/1.1
  2. POST data: {"upOrDown":"1","pageSize":"12","sequence":"0","status":"00000101"}
  3. Host: Domain name.
  4. Cache-Control: no-cache
  5. Content-Type: application/json
  6. srcTranId: 201910181908046224775037
  7. timeStamp: 1579423538
  8. Accept: application/json
  9. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx

Response:

  1. HTTP/1.1 401 Unauthorized
  2. Content-type: application/json
  3. content-length: 27
  4. {"error":"session timeout"}

The request fails, and an error response body is returned, for example, an incorrect srcTranId parameter is passed.

Request:

  1. POST /WiseCloudNearbyBeaconService/v1/queryBeaconList?projectId=id123 HTTP/1.1
  2. POST data: {"upOrDown":"1","pageSize":"12","sequence":"0","status":"00000101"}
  3. Host: Domain name.
  4. Cache-Control: no-cache
  5. Content-Type: application/json
  6. srcTranId: 20191018190804622477503612345678912345678
  7. timeStamp: 1579423538
  8. Accept: application/json
  9. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx

Response:

  1. HTTP/1.1 400 Bad Request
  2. Content-type: application/json
  3. content-length: 150
  4. {"serviceError":{"code":400000001,"message":"srcTranID: size must be between 0 and 24, srcTranID: must match \"^\\d{1,24}$\"","status":"Bad Request"}}

The request is successful, and a success response body is returned.

Request:

  1. POST /WiseCloudNearbyBeaconService/v1/queryBeaconList?projectId=id123 HTTP/1.1
  2. POST data: {"upOrDown":"1","pageSize":"12","sequence":"0","status":"00000101"}
  3. Host: Domain name.
  4. Cache-Control: no-cache
  5. Content-Type: application/json
  6. srcTranId: 201910181908046224775036
  7. timeStamp: 1579423534
  8. Accept: application/json
  9. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx

Response:

  1. HTTP/1.1 200
  2. content-length: 130
  3. Content-Type: application/json;charset=UTF-8
  4. {"moreBeacon":1,"beacons":[{"sequence":1578643043892,"beaconDesc":"luoluo test","beaconType":1,"beaconId":"beac0025","status":2},{"sequence":1578643043892,"beaconDesc":"beacon2 test","beaconType":1,"beaconId":"beac0026","status":2}]}