Passer au contenu principal

Plan de contrôle

Les API du plan de contrôle gèrent la gestion de votre réseau sans fil LoRaWAN®. La page démarrage rapide vous montre comment commencer à utiliser les API du plan de contrôle.

API des passerelles​

Les API des passerelles permettent de déployer votre réseau sans fil LoRaWAN®.

Capteurs et API de connexions​

L'API de capteurs et de connexions permet de gérer vos capteurs, relais, groupes de multicast et connexions.

information

Les connexions ThingPark X IoT Flow sont gérées avec l'API DX Core.

Pour obtenir la description complète des opérations API disponibles pour la connexion ThingPark X IOT Flow, consultez la documentation de l'API DX Core de votre plateforme :

API de notifications​

Les API de notifications fournissent le résultat des tâches asynchrones telles que les opérations d'importation massive de capteurs.

API d'administration​

Les API d'administration gèrent les comptes utilisateurs, comptes de service et domaines.

Comportement commun​

Toutes les API du plan de contrôle partagent le comportement commun décrit dans cette section.

Authentification​

L'authentification repose sur OAuth v2. Toutes les requêtes doivent inclure un jeton Bearer valide dans l'en-tête HTTP Authorization. Le jeton Bearer est un jeton d'accès OAuth v2 délivré à l'aide du Client Credentials Grant.

L'URL du point de terminaison du jeton OAuth est https://PLATFORM-HOSTNAME/users-auth/protocol/openid-connect/token.

Pour obtenir un jeton d'accès, une requête POST doit être envoyée sur le point de terminaison du jeton fournissant un ID client et un secret client dans le corps.

L'ID client et le secret client sont des propriétés d'un compte de service. Les comptes de service sont gérés par l'administrateur sur l'interface utilisateur de ThingPark.

La réponse HTTP est un objet JSON contenant les propriétés suivantes :

  • access_token : le jeton d'accès,
  • expires_in : le nombre de secondes pendant lesquelles le jeton d'accès sera valide.

Le jeton d'accès est généralement valide pour 5 minutes. Lorsque le jeton est sur le point d'expirer, la même requête doit être rejouée pour en obtenir un nouveau.

POST /users-auth/protocol/openid-connect/token HTTP/1.1
Host: PLATFORM-HOSTNAME
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=SERVICE-ACCOUNT-CLIENT-ID
&client_secret=SERVICE-ACCOUNT-CLIENT-SECRET

HTTP/1.1 200 OK
Content-Type: application/json

{"access_token":"...","expires_in":300,"refresh_expires_in":0,"token_type":"Bearer","not-before-policy":0,"scope":"email profile"}

Voir démarrage rapide pour plus de détails.

Verbes HTTP​

Selon les conventions REST, les verbes HTTP sont utilisés pour réaliser les actions suivantes :

VerbeDescription
GETRécupérer une ressource
POSTCréer une ressource
PUTÉditer une ressource
DELETESupprimer une ressource

Cookies​

L'API REST ThingPark Wireless utilise des cookies. Un agent utilisateur implémentant le Mécanisme de Gestion d'État HTTP RFC-6265 doit être utilisé pour s'assurer que les en-têtes HTTP Set-Cookie présents dans les réponses sont gérés.

Voir la section cookies sur chaque documentation d'API REST pour obtenir la liste des noms de cookies utilisés.

Création de ressources​

Lorsqu'une ressource est créée par une requête POST, le code de réponse est 201 (Created) et le corps de réponse est la représentation de la ressource créée. Un en-tête Location est également présent dans la réponse avec l'URL de la ressource créée en tant que valeur.

Par exemple, la requête donnée crée un capteur.

POST /thingpark/wireless/rest/subscriptions/mine/devices HTTP/1.1
Host: XXX
Authorization: Bearer ...
Content-Length: 322
Accept: application/json
Content-Type: application/json

{
   "connectivity":"LORAWAN",
   "activation":"OTAA",
   "appEUI":"ACDE48234567ABCD",
   "EUI":"ACDE48234567ABCD",
   "model":{
      "ID":"LORA/GenericA.1_ETSI_Rx2-SF12"
   },
   "appKey":"DEC499C69E9C939E413B663961636C61",
}

Et la réponse contient l'URL de la ressource dans l'en-tête Location et la ressource elle-même dans le corps.

HTTP/1.1 201 Created
Date: Fri, 04 Jan 2019 14:12:49 GMT
Content-Type: application/json
Content-Length: 2014
Connection: keep-alive
Location: /thingpark/wireless/rest/subscriptions/33/devices/533011

{
   "now":1546611169519,
   "occContext":{
      "version":1,
      "lastUpdate":1546611169000,
      "who":"John Doe"
   },
   "name":"New device 533011",
   "model":{
      "commercialName":"LoRaWAN 1.0 - class A - Rx2_SF12",
      "logo":"/thingpark/wireless/rest/resources/files/logo/deviceProfile/3043",
      "typeMAC":"LoRaMAC",
      "type":"A",
      "macMajorVersion":0,
      "macMinorVersion":3,
      "ID":"LORA/GenericA.1_ETSI_Rx2-SF12"
   },
   "connectivity":"LORAWAN",
   "vendor":{
      "name":"Generic",
      "commercialName":"Generic",
      "commercialDescription":"LoRaWAN generic devices.",
      "ID":"generic",
      "logo":"/thingpark/wireless/rest/resources/files/logo/deviceVendor/313"
   },
   "creationDate":1546611169159,
   "activation":"OTAA",
   "nwAddress":null,
   "nwKey":null,
   "appKeys":null,
   "appEUI":"ACDE48234567ABCD",
   "appKey":"81CF679FFD70F5BD2B28C7A206BF4D6C",
   ...
}

Pagination​

La plupart des ressources de collection sont paginées pour des raisons de performance. Par défaut, la première page est livrée. Si une autre page est disponible pour récupérer plus de ressources, la valeur de la propriété more est true. Pour obtenir la page suivante, la même requête doit être faite avec le paramètre de requête pageIndex incrémenté.

Types de contenu​

Toutes les APIs supportent JSON comme format de données pour à la fois l'entrée et la sortie.

Le type de contenu est contrôlé par l'en-tête HTTP Accept pour la réponse et Content-Type pour la requête. Les en-têtes suivants doivent être inclus dans toutes les requêtes.

Accept: application/json
Content-Type: application/json

Réponses d'erreur​

Toute opération peut renvoyer une erreur. Dans ce cas, la réponse HTTP a un code d'état supérieur ou égal à 400. Le corps de la réponse peut contenir plus de détails sur la cause de l'erreur en fournissant une ressource d'erreur dans le corps de la requête.

Habituellement, le schéma de la ressource d'erreur est le suivant :

Error:
   required:
      - code
      - message
   properties:
      code:
         type: integer
         format: int32
         example: '25'
      message:
         type: string
         example: unknown error

Limiteur de taux​

Les API REST sont protégées par un mécanisme de limitation de débit contre le déluge de requêtes HTTP. Ce mécanisme de limitation de débit utilise l'algorithme de seau percé décrit dans Limitation de débit NGINX .

Les points de terminaison de l'API REST sont classés en trois catégories :

  • HIGH_IMPACT : Cette catégorie s'applique aux points de terminaison avec le plus haut niveau d'impact sur les ressources système
  • MEDIUM_IMPACT : Cette catégorie s'applique aux points de terminaison avec un impact significatif sur les ressources système
  • LOW_IMPACT : Tous les autres points de terminaison qui devraient avoir un impact faible sur les ressources système

La catégorie d'un point de terminaison est documentée dans le contrat OpenAPI à l'aide de l'extension vendeur x-rateLimit dans les paramètres d'opération. Par défaut, la catégorie est LOW_IMPACT. Par conséquent, l'extension vendeur x-rateLimit n'est spécifiée que pour les catégories MEDIUM_IMPACT et HIGH_IMPACT.

paths:
  /customers:
    get:
      ...
      x-rateLimit:
         category: MEDIUM_IMPACT

Chaque catégorie est associée à :

  • Limite globale : Un taux maximum de requêtes/s soutenu par le système sans considération pour l'adresse IP source et sans considération pour le domaine ciblé
  • Limite IP source : Un taux maximum de requêtes/s autorisé pour une adresse IP source donnée

Lorsqu'une limite est atteinte, soit globale, soit pour l'IP source, la requête HTTP est rejetée avec une réponse 429 Trop de Requêtes.

La configuration suivante est définie par défaut pour la limite IP source :

CatégorieLimite IP source
HIGH_IMPACT2r/s (burst=6 nodelay)
MEDIUM_IMPACT6r/s (burst=18 nodelay)
LOW_IMPACT20r/s (burst=80 nodelay)
Dernière mise à jour sur
Copyright © 2025 Actility
Sur cette page