目录

Function

This API is used to configure an attachment for a beacon.

Scenario

This API is called after a beacon is created.

Prototype

Protocol

HTTPS POST

Direction

App server or app -> HUAWEI Nearby Service server

URL

https://{Domain name}/WiseCloudNearbyBeaconService/v1/updateAttachment/{beaconId}?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.

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.

projectId

O

String

Project ID for query.

beaconId

M

String

Beacon ID in the URL.

attachment

M

object

Attachment information in the request body. For details, please refer to the following table.

Attachment structure

Parameter

Type

Mandatory(M)/Optional(O)

Description

attachmentId

Long

O

Attachment ID. This parameter must be left empty when an attachment is configured.

namespace

String

M

Namespace of a project. The value contains a maximum of 32 characters.

type

String

M

Message type, which is customized and contains a maximum of 16 characters.

value

String

M

Attachment content, which must be encoded using Base64. The value contains a maximum of 4096 characters. The maximum length after decoding is 2048 bytes.

Output Parameters

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

Parameter

Type

Description

attachment

object

For details, please refer to the following definition of the Attachment structure.

Attachment structure definition

Parameter

Type

Description

attachmentId

String

Attachment ID, which is generated by the Nearby Service server and contains 36 characters.

namespace

String

Namespace, which is set to the original value of the input parameter.

type

String

Type, which is set to the original value of the input parameter.

value

String

Original value of the input parameter.

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.

400000007

Invalid beacon ID.

Verify the beacon ID.

400000009

The beacon is not activated.

Activate the beacon.

400009001

The attachmentId parameter is not left empty.

Ensure that the attachmentId parameter in the request body is left empty.

400009002

The value parameter is set to an invalid Base64-encoded character string.

Ensure that the value parameter in the request body is set to a valid Base64-encoded character string.

400009003

The attachment content is too long.

Ensure that the value parameter in the request body does not exceed the maximum (2048 bytes) after decoding.

400009004

The number of configured attachments has reached the maximum.

Delete unnecessary attachments.

403000003

The service account is unavailable.

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

403000004

You have no permission to perform operations on the beacon using the current account.

Verify that you have permission to perform operations the beacon using the service account.

403000005

You have no permission to perform operations on the namespace using the current account.

Switch to an account that has the permission.

404000006

The beacon does not exist.

Check whether the beacon exists. If not, register it.

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/updateAttachment/a1bc3331?projectId=id123 HTTP/1.1
  2. POST data: {"attachment":{"namespace":"dev9105385871708434","type":"myType","value":"SGVsbG8gSE1TIQ=="}}
  3. Host: Domain name.
  4. Content-Type: application/json
  5. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx
  6. srcTranID: 202001141709412953357215
  7. timeStamp: 922337203685477580
  8. Accept: application/json

Response:

  1. HTTP/1.1 401
  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 invalid beaconId parameter is passed.

Request:

  1. POST /WiseCloudNearbyBeaconService/v1/updateAttachment/aibc3331?projectId=id123 HTTP/1.1
  2. POST data: {"attachment":{"namespace":"dev9105385871708434","type":"myType","value":"SGVsbG8gSE1TIQ=="}}
  3. Host: Domain name.
  4. Content-Type: application/json
  5. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx
  6. srcTranID: 202001141709412953357215
  7. timeStamp: 922337203685477580
  8. Accept: application/json

Response:

  1. HTTP/1.1 400
  2. Content-Type: application/json
  3. Content-Length: 84
  4. {"serviceError":{"code":400000007,"message":"BeaconId ID aibc3331 is invalid.","status":"Bad Request"}}

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

Request:

  1. POST /WiseCloudNearbyBeaconService/v1/updateAttachment/a1bc3331?projectId=id123 HTTP/1.1
  2. POST data: {"attachment":{"namespace":"dev9105385871708434","type":"myType","value":"SGVsbG8gSE1TIQ=="}}
  3. Host: Domain name.
  4. Content-Type: application/json
  5. Authorization: Bearer eyJraWQiOiIx---xxx.eyJhdWQiOiJodHR---xxx.QRodgXa2xeXSt4Gp---xxx
  6. srcTranID: 202001141709412953357215
  7. timeStamp: 922337203685477580
  8. Accept: application/json

Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. Content-Length: 143
  4. {"attachment":{"namespace":"dev9105385871708434","attachmentId":"202001141654556730274476060148700160","type":" myType","value":"SGVsbG8gSE1TIQ=="}}