Skip to content

Latest commit

 

History

History
329 lines (239 loc) · 12.1 KB

API Reference.md

File metadata and controls

329 lines (239 loc) · 12.1 KB

API Reference

1. SDK Initialization and Configuration

  • NewClientWithHost(Host string, transport *http.Transport) *Client: Creates a client instance for calling interfaces.

    Host: Host domain name of the platform-side service.

    transport: HTTP connection pool configuration. Default parameters are:

    transport := &http.Transport{
	MaxIdleConns:        5,               
	MaxIdleConnsPerHost: 2,               
	IdleConnTimeout:     30 * time.Second, 
	TLSHandshakeTimeout: 10 * time.Second, 
}

  • Client: Centralized platform-side basic service interface calling methods.

  • (c *Client) SetHost (Host string): Sets the host of the platform-side service.

  • (c *Client) SetLogPath (path string) error: Sets the log output path path and returns an error. Default is: ./sdk.log.

  • (c *Client) SetRequestId (requestId string) *Client: Manually sets the request ID for the current request. It is automatically generated by default.

  • (c *Client) SetTransport(transport *http.Transport): Sets the HTTP connection pool configuration after initialization.

2. Main Operation Structures and Methods

2.1 Obtain Box_Reg_Key

  • (c *Client) ObtainBoxRegKey(input *ObtainBoxRegKeyRequest) ( *ObtainBoxRegKeyResponse, error)

    Function method for obtaining an box_reg_key.

  • ObtainBoxRegKeyRequest

    type ObtainBoxRegKeyRequest struct {
	BoxUUID    string   `json:"boxUUID"` 	   //UUID of the device
	ServiceIds []string `json:"serviceIds"`    //Platform id: Space Platform (serviceId=10001)）
	Sign       string   `json:"sign,optional"` //Signature, required when using the public key to verify 												//the identity of the device
}

  • ObtainBoxRegKeyResponse

    type ObtainBoxRegKeyResponse struct {
	BoxUUID      string         `json:"boxUUID"`      //UUID of the device
	TokenResults []tokenResults `json:"tokenResults"` //The access token for the device
}

  • tokenResults

    type tokenResults struct {
	ServiceId string    `json:"serviceId"` //Platform ID
	BoxRegKey string    `json:"boxRegKey"` //The access token of the device
	ExpiresAt time.Time `json:"expiresAt"` //Token validity time
}

2.2 Register Device

  • (c *Client) RegisterDevice() (*RegisterDeviceResponse, error)

    Function method for registering a device.

  • RegisterDeviceResponse

    type RegisterDeviceResponse struct {
	BoxUUID       string        `json:"boxUUID"`       //The UUID of the device	
	NetWorkClient netWorkClient `json:"networkClient"` //Assign network client information to it
}

  • netWorkClient

    type netWorkClient struct {
	ClientId  string `json:"clientId"`  //The client ID of the network	
	SecretKey string `json:"secretKey"` //Access key
}

2.3 Delete Device

  • (c *Client) DeleteDevice() error

    Function method for deleting a device.

2.4 Register User

  • (c *Client) RegisterUser(input *RegisterUserRequest) (*RegisterUserResponse, error)

    Function method for registering a user.

  • RegisterUserRequest

    type RegisterUserRequest struct {
	UserID     string `json:"userId"`     //User ID
	Subdomain  string `json:"subdomain"`  //The subdomain name specified by the user
	UserType   string `json:"userType"`	  //User type (administrator, member), value: user_admin、												  //user_member
	ClientUUID string `json:"clientUUID"` //The UUID of the client
}

  • RegisterUserResponse

    type RegisterUserResponse struct {
	BoxUUID    string `json:"boxUUID"`    //The UUID of the device
	UserID     string `json:"userId"`     //The ID of the user
	UserDomain string `json:"userDomain"` //The user domain name assigned to the user, which can be used 										   //for subsequent device access
	UserType   string `json:"userType"`   //User type (administrator, member)
	ClientUUID string `json:"clientUUID"` //The UUID of the client
}

2.5 Generate User Domain Name

  • (c *Client) GenerateUserDomain(input *GenerateUserDomainRequest) (*GenerateUserDomainResponse, error)

    Function method for generating user domain name.

  • GenerateUserDomainRequest

    type GenerateUserDomainRequest struct {
	EffectiveTime string `json:"effectiveTime"` //Validity period, in seconds, up to 7 days
}

  • GenerateUserDomainResponse

    type GenerateUserDomainResponse struct {
	BoxUUID   string `json:"boxUUID"`   //The UUID of the device
	Subdomain string `json:"subdomain"` //The specified subdomain name of the user
	ExpiresAt string `json:"expiresAt"` //Validity
}

2.6 Modify User Domain Name

  • (c *Client) ModifyUserDomain(input *ModifyUserDomainRequest) (*ModifyUserDomainResponse, error)

    Function method for modifying a user domain name.

  • ModifyUserDomainRequest

    type ModifyUserDomainRequest struct {
	UserId    string `json:"-"`         //User ID
	Subdomain string `json:"subdomain"` //The new subdomain name specified by the user
}

  • ModifyUserDomainResponse

    type ModifyUserDomainResponse struct {
   Success    bool     `json:"success"`			     //Whether successful or not
   BoxUUID    string   `json:"boxUUID,omitempty"`    //The UUID of the device, returned when success is  													  //true
   UserId     string   `json:"userId,omitempty"`     //The ID of the user. Returned when success is true
   Subdomain  string   `json:"subdomain,omitempty"`  //The new subdomain name specified by the user.                                                          //Returns when success is true
   Code       int      `json:"code,omitempty"`       //Error code, returned when success is false 	
   Error      string   `json:"error,omitempty"`      //Error message, returned when success is false
   Recommends []string `json:"recommends,omitempty"` //Recommended subdomains, returned when success is 													 //false
}

2.7 Delete User

  • DeleteUser(userId string) error

    Function method for deleting a specified user. Receives a userID parameter.

2.8 Register Client

  • (c *Client) RegisterClient(input *RegisterClientRequest) (*RegisterClientResponse, error)

    Function method for registering a client.

  • RegisterClientRequest

    type RegisterClientRequest struct {
	UserId     string `json:"-"`		  //User ID
	ClientUUID string `json:"clientUUID"` //The UUID of the client
	ClientType string `json:"clientType"` //Client type (binding, scanning authorization), value: 												  //client_bind、client_auth
}

  • RegisterClientResponse

    type RegisterClientResponse struct {
	BoxUUID    string `json:"boxUUID"`    //The UUID of the device
	UserId     string `json:"userId"`     //The ID of the user
	ClientUUID string `json:"clientUUID"` //The UUID of the client
	ClientType string `json:"clientType"` //Client type (binding, scanning authorization)
}

2.9 Delete Client

  • (c *Client) DeleteClient(input *DeleteClientRequest) error

    Function method for deleting a client.

  • DeleteClientRequest

    type DeleteClientRequest struct {
	UserId     string //User ID
	ClientUUID string //UUID of the client
}

2.10 Space Platform Migration

  • (c *Client) SpacePlatformMigration(input *SpacePlatformMigrationRequest) (*SpacePlatformMigrationResponse, error)

    Function method for migrating to a new space platform.

  • SpacePlatformMigrationRequest

    type SpacePlatformMigrationRequest struct {
	NetworkClientId string              `json:"networkClientId"` //The client ID of the network
	UserInfos       []UserMigrationInfo `json:"userInfos"`       //User list
}

  • UserMigrationInfo

    type UserMigrationInfo struct {
   UserId      string       `json:"userId"`      //User ID
   UserDomain  string       `json:"userDomain"`  //User domain name
   UserType    string       `json:"userType"`    //User type (administrator, member)
   ClientInfos []ClientInfo `json:"clientInfos"` //Client List
}

  • ClientInfo

    type ClientInfo struct {
   ClientUUID string `json:"clientUUID"` //The UUID of the client
   ClientType string `json:"clientType"` //Client type (binding, scanning authorization), value: 												 //client_bind、client_auth
}

  • SpacePlatformMigrationResponsed

    type SpacePlatformMigrationResponse struct {
   BoxUUID       string              `json:"boxUUID"`       //The UUID of the device
   NetworkClient netWorkClient       `json:"netWorkClient"` //Network client information assigned to the 															 //device
   UserInfos     []UserMigrationInfo `json:"userInfos"`     //User list
}

2.11 Space Platform Migration Out

  • (c *Client) SpacePlatformMigrationOut (input *SpacePlatformMigrationOutRequest) (*SpacePlatformMigrationOutResponse, error)

    Function method for migrating out from the space platform.

  • SpacePlatformMigrationOutRequest

    type SpacePlatformMigrationOutRequest struct {
   UserDomainRouteInfos []UserDomainRouteInfo `json:"userDomainRouteInfos"` //User domain name mapping 																				//relationship
}

  • UserDomainRouteInfo

    type UserDomainRouteInfo struct {
   UserId             string `json:"userId"`             //User ID
   UserDomainRedirect string `json:"userDomainRedirect"` //Redirected user domain name
}

  • SpacePlatformMigrationOutResponse

    type SpacePlatformMigrationOutResponse struct {
   BoxUUID              string                `json:"boxUUID"`              //The UUID of the device
   UserDomainRouteInfos []UserDomainRouteInfo `json:"userDomainRouteInfos"` //User domain name mapping 																				//relationship
}

3. Constants

  • ApiVersion：API version
  • AoSpaceDomain：Ao.Space domain

4. Error Code

Status Code Error Code Error Message Description
400 SSP-2012 input parameter: {0} error Request parameter error
400 SSP-2017 subdomain does not exist The subdomain name does not exist
400 SSP-2018 Subdomain already exists Subdomain already exists
400 SSP-2019 Subdomain already used Subdomain already used
400 SSP-2020 reach subdomain upper limit The number of subdomains has reached the upper limit
400 SSP-2021 device uuid has already registered Device uuid has already registered
400 SSP-2022 device uuid had not registered Device uuid not registered
400 SSP-2023 user id has already registered User id has already registered
400 SSP-2024 user id has not registered User id is not registered
400 SSP-2025 client uuid has already registered Client uuid has already registered
400 SSP-2026 client uuid has not registered Client uuid is not registered
400 SSP-2028 network client does not exist Network client does not exist
400 SSP-2049 network server does not exist Network server does not exist
400 SSP-2050 Subdomain is not in use Subdomain is not in use
400 SSP-2051 subdomain is reserved The subdomain name is illegal
400 SSP-2060 migration in acquire lock error Migration in acquire lock failed
400 SSP-2061 migration out acquire lock error The migration out operation failed to acquire the lock