Instance Query

Description

This API is optional for yearly/monthly/one-time products, but it is mandatory for pay-per-use specifications and packages.
When a customer queries the instance information of a purchased pay-per-use product, you need to return the usage in real time.
If a customer queries a pay-per-use package, you need to return the package usage through this API.

The following figure shows the process of querying instance information.

Click to enlarge

Request Message

The following table describes the request parameters.

Request method: GET

Parameter	Mandatory	Type	Maximum Length	Description
authToken	Yes	String	50	Security verification token. For details about the value, see authToken Value.
activity	Yes	String	20	Request ID, which is used to distinguish the scenario. For instance query, the value is queryInstance.
timeStamp	Yes	String	20	UTC timestamp when a request is initiated. Format: yyyyMMddHHmmssSSS
instanceId	Yes	String	64	Instance IDs separated by commas (,). Up to 100 instances can be queried each time.
testFlag	No	String	2	Whether a request is submitted for debugging. 1: debugging request. 0: non-debugging request. The default value is 0.

Example request:

https://example.isv.com?activity=queryInstance&instanceId=ebc28eb6-4606-4098-b4bd-c201c99a0654%2Cfe28e27e-1157-4105-8592-24cc9488db10%2C92df74e4-163e-4e0b-a206-d9800d33881b&testFlag=1&timeStamp=20230327065233980&authToken=Eh%2F3Ud%2BR1j3d%2FwOui5CAcvRipM8IuribvgkXfJAsTfE%3D

Response Message

The following table describes the response parameters.

**Table 1** Response parameters
Parameter	Mandatory	Type	Maximum Length	Description
resultCode	Yes	String	6	Result code. For details, see Invocation Result Codes.
resultMsg	No	String	255	Result message.
encryptType	No	String	3	Algorithm for encrypting sensitive information. 1: AES256_CBC_PKCS5Padding (default) 2: AES128_CBC_PKCS5Padding NOTE: If AES256_CBC_PKCS5Padding is used, the return value is 1. If AES128_CBC_PKCS5Padding is used, the return value is 2.
info	No	InstanceInfo[]	/	Instance details.

The following table describes the InstanceInfo data structure.

**Table 2** Response parameters
Parameter	Mandatory	Type	Maximum Length	Description
instanceId	Yes	String	64	Instance ID.
appInfo	No	AppInfo	N/A	App instance information. After a customer purchases a product, return a login address (website address) or an address that does not require login for the customer to perform subsequent operations. NOTE: You must provide customers who purchase your SaaS products with the app usage information, including the addresses, accounts, and passwords. If the usage information can be sent through SMS messages, emails, or other methods, this parameter is not required in the response. Otherwise, the app instance information must be returned in the response. You can use the memo parameter to specify usage instructions or other information if any. For details about the appInfo data structure, see the following table.
usageInfo	No	UsageInfo[]	N/A	Usage information associated with an app instance. This parameter is required for pay-per-use specifications and packages. For pay-per-usage packages, the usage information of all billing items associated with the packages needs to be returned.

The following table describes the AppInfo data structure.

**Table 3** Response parameters
Parameter	Mandatory	Type	Maximum Length	Description
frontEndUrl	Yes	String	512	Frontend URL. URL of the website that the customer can access to use the purchased product.
adminUrl	No	String	512	Management URL. URL of the backend website that the customer can access to manage the purchased product.
userName	No	String	128	Encrypted administrator account. Account (usually an email address or mobile number) used by a customer to access the management backend. The value consists of a 16-bit encryption IV and a Base-encoded username ciphertext. iv+base64(AES_CBC(accessKey,userName)) The account is encrypted using the key and encryption algorithm specified by encryptType. For details about the example code, see ISV Server Encrypting the Username and Password After Resource Enabling.
password	No	String	128	Encrypted initial password of the administrator. Password (usually generated by you) used by a customer to access the management backend. The value consists of a 16-bit encryption IV and a Base-encoded password ciphertext. iv+base64(AES_CBC(accessKey,pwd)) The password is encrypted using the key and encryption algorithm specified by encryptType. For details about the example code, see ISV Server Encrypting the Username and Password After Resource Enabling.
memo	No	String	1,024	Remarks.

The following table describes the UsageInfo data structure.

**Table 4** Response parameters
Parameter	Mandatory	Type	Maximum Length	Description
relatedInstanceId	No	String	64	ID of the associated pay-per-use instance. When a customer queries the usage of resources in a pay-per-use package, the resource instance IDs also need to be returned. For example, if a package has 100 SMS messages and 50 MMS messages, UsageInfo and relatedInstanceId values of the two message types are returned.
usageValue	Yes	Double(12,4)	20	Usage value, with up to four decimal places. For pay-per-use specifications, the value is the accumulated resource usage. For pay-per-use packages, the value is the used package quota.
statisticalTime	Yes	String	20	UTC time when usage statistics are collected. Format: yyyyMMddHHmmssSSS
dashboardUrl	No	String	512	URL of the dashboard for viewing usage details. After purchasing a pay-per-use specification or pay-per-usage package, customers can view the usage information on this dashboard.

Example response:

{
    "resultCode" : "000000",
    "resultMsg" : "success.",
    "encryptType" : "1",
    "info" : [{
             "instanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654",
             "appInfo" : {
                 "frontEndUrl" : "https://www.baidu.com",
                 "adminUrl" : "https://www.baidu.com/admin",
                 "userName" : "huawei",
                 "password" : "huawei123456",
                 "memo" : "Test"
             },
             "usageInfo" : [{
                     "relatedInstanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654",
                     "usageValue" : "0.12",
                     "statisticalTime" : "20221101025113409",
                     "dashboardUrl" : "https://www.baidu.com/dashboard"
                 }
             ]
        }, {
             "instanceId" : "fe28e27e-1157-4105-8592-24cc9488db10",
             "appInfo" : {
                 "frontEndUrl" : "https://www.baidu.com",
                 "adminUrl" : "https://www.baidu.com/admin",
                 "userName" : "huawei",
                 "password" : "huawei123456",
                 "memo" : "Test"
             },
             "usageInfo" : [{
                     "relatedInstanceId" : "fe28e27e-1157-4105-8592-24cc9488db10",
                     "usageValue" : "2042",
                     "statisticalTime" : "20221101025113409",
                     "dashboardUrl" : "https://www.baidu.com/dashboard"
                 }
             ]
        }, {
             "instanceId" : "92df74e4-163e-4e0b-a206-d9800d33881b",
             "appInfo" : {
                 "frontEndUrl" : "https://www.baidu.com",
                 "adminUrl" : "https://www.baidu.com/admin",
                 "userName" : "huawei",
                 "password" : "huawei123456",
                 "memo" : "Test"
             },
             "usageInfo" : [{
                     "relatedInstanceId" : "ebc28eb6-4606-4098-b4bd-c201c99a0654",
                     "usageValue" : "3309",
                     "statisticalTime" : "20221101025113409",
                     "dashboardUrl" : "https://www.baidu.com/dashboard"
                 },
                 {
                     "relatedInstanceId" : "fe28e27e-1157-4105-8592-24cc9488db10",
                     "usageValue" : "3309",
                     "statisticalTime" : "20221101025113409",
                     "dashboardUrl" : "https://www.baidu.com/dashboard"
                 }
             ]
        }
    ]
}

Parent topic: Interface Description

Previous topic: Resource Status Change

Next topic: Pay-per-Use Resource Usage Push