IoT Platform:Custom Service API

Prerequisites

Ensure that the metrics and storage tables related to the data source are already established.

For more information, see Metric Overview and Custom Storage Table.

1. In the IoT Platform console, click Overview. On the Overview tab, find the instance that you want to manage and click the instance ID or the instance name.

2. Navigate to DataService Studio > Data APIs using the left-side navigation pane.

3. Navigate to the Data API page, select the Custom Service API tab, and click Create API.

4. In the Create API configuration wizard, fill in the API Basic Information and click Next.

   Parameter	Description
   API Name	Input the API name, which can include Chinese characters, English letters, numbers, underscores (_), and hyphens (-), up to 30 characters long.
   API Path	Specify the API path, which uniquely identifies the API resource within the instance. The apiPath in the request parameters must correspond to this value when calling the API. Must begin with a forward slash (/) and can include English letters, numbers, underscores (_), and forward slashes (/), with a maximum length of 128 characters. For instance: pk/temperatureMax. Important The API Path cannot be altered once the API is published.
   API Tag	Enter the tag content and press Enter to create the tag. Tags can include Chinese characters, English letters, numbers, underscores (_), and hyphens (-), and can be up to 30 characters long. Supports Chinese characters, English letters, digits, underscores (_), and hyphens (-), with a maximum length of 30 characters for the tag. Tags allow you to customize the API identity for more flexible management. Important A maximum of 5 tags can be added to an API.
   API Description	Provide a description for the API, detailing its functionality and other relevant information.
   Return Type	The data returned after calling the API is formatted as JSON.

5. On the Configure Parameters And Test page, proceed with the following settings:

   Category	Configuration Item	Description
   Data Source	Metric	Choose the relevant Metric Domain and Dataset. A Dataset represents the specific organization of objects within the metric domain, such as particular products or devices. For a detailed explanation of metrics, refer to What is a Metric.
   	Storage Table	Select the custom storage table that results from data parsing or SQL analysis tasks. For additional details, see Cold Data Storage Table.
   Configuration Parameters	Dataset	The Data Source is displayed automatically when Metric is selected, along with the specific Metric Domain and Dataset. Click Preview Data to access the data source details page.
   	Data Range	This option appears only when Data Source is set to Metric. Select the data range for the API: Derived Metric: Data derived from original metrics through aggregation calculations, such as summation and averaging. Derived Definition: A derivative of the original metric definition applied to sub-entities. For more on derived metrics and definitions, see Metric Types.
   	Request Parameters	Use Add Parameter to include data source metrics in the API's request parameters. Only system fields and primary key fields from custom storage tables are supported. Parameters must encompass binding fields, names, types, operators, whether they are required, example values, and descriptions. Important Numeric parameter types do not support the LIKE operator.
   	Response Parameters	Add response parameters by clicking Add Parameter. Parameters must include precedence, binding fields, names, types, sorting usage, example values, and descriptions. Check the Select All Parameters box to include all defined table fields in the API's response parameters. Note Sorting refers to arranging query results based on the value of a field, either ascending or descending. A metric can only be configured as one parameter in the response.
   	Sorting Method	Determine the parameter order. Ascending (default): Parameters are sorted in ascending order. Descending: Parameters are sorted in descending order.
   Advanced Settings	Enable return result paging	Choose whether to paginate the returned results. Disable: A maximum of 100 results can be viewed without pagination. Enable: View all results across multiple pages. Upon enabling, the following common parameters are automatically included: pageNum: The page number for pagination. pageSize: The number of results per page, with a maximum of 100.
   	Timeout Error Setting	A timeout error is returned if the API call exceeds 8000 milliseconds. This setting is fixed and cannot be modified.

   Once you have configured the above settings, use the Test API section to input test values for the request parameters and click Start Test.

   You can review the sample data returned in the Return Sample tab or view detailed request information by clicking Request Details after initiating the request.

6. Click Publish.

   Important

   • Ensure the API has passed testing before publishing.

   • APIs saved by clicking Save will be marked as unpublished.

   • You can edit incomplete API configurations by clicking Edit, and then publish them once finalized.

   • APIs can be deleted only if they are unpublished or offline.

   On the Publish Successful page, you can click Create Again to define additional custom APIs, or click Go To List to review the APIs you have created.

What to do next

Once created, you can invoke your custom service APIs to retrieve data. For instructions on managing and using these APIs, see Manage and Use.

For examples of API calls, refer to:

• See Java SDK Call Example for details.

• Example of a Node.js SDK Call