IoT Platform:API de service personnalisé

Prérequis

Vous avez créé des métriques et des tables de stockage pour vos sources de données. Pour plus d'informations, consultez les rubriques Aperçu des métriques et Tables de stockage personnalisées.

1. Dans la console IoT Platform, accédez à la page Overview et cliquez sur l'ID ou l'alias de l'instance Enterprise Edition cible.

2. Dans le volet de navigation de gauche, choisissez Data Service > Data API.

3. Sur la page Data API, cliquez sur l'onglet custom service API, puis sur Create API.

4. Dans l'assistant Create API, configurez les paramètres de la section API basic information, puis cliquez sur Next.

   Parameter	Description
   API name	Saisissez un nom pour l'API. Le nom peut contenir des caractères chinois, des lettres, des chiffres, des traits de soulignement (_) et des traits d'union (-), et comporter jusqu'à 30 caractères.
   API path	Saisissez le chemin de l'API. Il sert d'identifiant unique de ressource au sein de l'instance. Lors de l'appel à l'API, la valeur du paramètre de requête apiPath doit correspondre à ce chemin. Le chemin doit commencer par une barre oblique (/) et peut contenir des lettres, des chiffres, des traits de soulignement (_) et des barres obliques (/). La longueur maximale est de 128 caractères. Exemple : /pk/temperatureMax. Important Vous ne pouvez pas modifier le chemin de l'API après sa publication.
   API tag	Saisissez le contenu du tag et appuyez sur Entrée. Un tag peut contenir des caractères chinois, des lettres, des chiffres, des traits de soulignement (_) et des traits d'union (-), et comporter jusqu'à 30 caractères. Utilisez les tags comme identifiants personnalisés pour faciliter la gestion de vos API. Important Vous pouvez ajouter un maximum de cinq tags à une API.
   API description	Saisissez une description de l'API, indiquant par exemple son objectif et ses fonctionnalités.
   Response format	Le format des données de réponse est fixé à JSON.

5. Sur la page Configure and test parameters, effectuez les configurations suivantes.

   Category	Parameter	Description
   Data source	Metric	Sélectionnez un metric field et un dataset spécifiques. Un dataset correspond à une organisation spécifique d'objets au sein d'un champ de métrique, tel qu'un produit spécifique dans le champ produit ou un appareil spécifique dans le champ appareil. Pour plus d'informations sur les métriques, consultez la rubrique Qu'est-ce qu'une métrique ?.
   	Storage table	Sélectionnez une table de stockage personnalisée générée par une tâche d'analyse de données ou SQL. Pour plus d'informations, consultez la rubrique Table de stockage froid.
   Configure parameters	Dataset	Ce paramètre n'apparaît que si vous sélectionnez Metric comme data source et que vous spécifiez un metric field et un dataset. Cliquez sur Preview Data pour accéder à la page de détails de la source de données sélectionnée.
   	Data scope	Ce paramètre s'affiche uniquement si vous sélectionnez Metric comme data source. Sélectionnez la portée des données pour l'API : derived metric : Données obtenues à partir de métriques brutes, de définitions originales et de définitions dérivées via des calculs d'agrégation tels que la somme et la moyenne. derived definition : Métrique dérivée d'une définition originale et appliquée à des sous-entités. Pour plus d'informations sur les métriques et définitions dérivées, consultez la rubrique Types de métriques.
   	Request parameters	Cliquez sur Add Parameter pour ajouter des métriques de la source de données sélectionnée en tant que paramètres de requête pour l'API. Seuls les champs système et les champs de clé primaire d'une table de stockage personnalisée sont pris en charge. Pour chaque paramètre, configurez son champ de liaison, son nom, son type, son opérateur, son caractère obligatoire, une valeur d'exemple et une description. Important Si le type de paramètre est numérique, l'opérateur LIKE n'est pas pris en charge.
   	Response parameters	Cliquez sur Add Parameter pour ajouter des métriques de la source de données sélectionnée en tant que paramètres de réponse pour l'API. Pour chaque paramètre, configurez sa priorité, son champ de liaison, son nom, son type, son utilisation pour le tri, une valeur d'exemple et une description. Cochez la case Select All Parameters à droite pour inclure tous les champs de la table dans la réponse de l'API. Remarque Trie les résultats selon ce champ par ordre croissant ou décroissant. Chaque métrique ne peut être configurée que comme un seul paramètre de réponse.
   	Sort order	Sélectionnez l'ordre de tri des paramètres. Ascending (par défaut) : Les paramètres sont triés par ordre croissant. Descending : Les paramètres sont triés par ordre décroissant.
   Advanced Settings	Enable paginated response	Indique s'il faut activer la pagination pour la réponse. Disabled : Renvoie un maximum de 100 résultats. Enabled : Renvoie tous les résultats sous forme de pages. Si vous activez cette fonctionnalité, les paramètres communs suivants sont automatiquement ajoutés : pageNum : Le numéro de page. pageSize : La taille de la page. La valeur maximale est 100.
   	Timeout error setting	Si un appel d'API dépasse 8 secondes, une erreur de délai d'expiration est renvoyée. Ce paramètre ne peut pas être modifié.

   Une fois ces paramètres configurés, saisissez les valeurs de test pour les paramètres de requête dans la section Test API et cliquez sur Start Test.

   Consultez les exemples de données dans l'onglet Response Example, ou cliquez sur Request Details pour afficher les informations spécifiques de la requête. Si le test réussit, l'onglet Response Example affiche la réponse JSON, incluant des champs tels que errCode:0 et errMsg:"success". Un message Test succeeded et la durée de l'appel API apparaissent en bas de page.

6. Cliquez sur Publish.

   Important

   • Avant de publier une API, assurez-vous qu'elle a réussi le test.

   • Si vous cliquez uniquement sur Save, l'API est enregistrée avec le statut hors ligne.

   • Pour une API dont la configuration est incomplète, cliquez sur Edit pour finaliser la configuration, puis publiez-la.

   • Vous ne pouvez supprimer que les API hors ligne.

   Sur la page Published successfully, cliquez sur Create Another pour créer d'autres API personnalisées, ou sur View in List pour afficher l'API dans la liste.

Étapes suivantes

Après avoir créé une API de service personnalisé, appelez-la pour récupérer des données. Pour obtenir des instructions, consultez la rubrique Gérer et utiliser les API.

Pour des exemples d'appels, consultez :

• Exemple d'appel Java SDK

• Exemple d'appel Node.js SDK