Utiliser l’API REST pour créer et gérer des applications IoT Central
Vous pouvez utiliser l’API REST du plan de contrôle pour créer et gérer des applications IoT Central. Vous pouvez également utiliser l’API REST pour :
- Ajouter une identité managée à votre application.
- Gérer les tableaux de bord dans votre application
Pour utiliser cette API, vous avez besoin d’un jeton du porteur pour la ressource management.azure.com. Pour obtenir un jeton du porteur, vous pouvez utiliser Azure CLI :
az account get-access-token --resource https://management.azure.com
Pour savoir comment gérer l’application IoT Central à l’aide de l’interface utilisateur IoT Central, consultez Créer une application IoT Central.
Répertorier vos applications
Pour obtenir la liste des applications IoT Central dans un abonnement :
GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Pour obtenir la liste des applications IoT Central dans un groupe de ressources :
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps?api-version=2021-06-01
Vous pouvez récupérer les détails d’une application individuelle :
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.IoTCentral/iotApps/{applicationName}?api-version=2021-06-01
Créer une application IoT Central
Pour créer une application IoT Central avec une identité managée affectée par le système :
PUT https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
La charge utile suivante illustre la configuration de la nouvelle application, y compris l’identité managée :
{
"location": "eastus",
"sku": {
"name": "ST2"
},
"properties": {
"displayName": "Contoso IoT Central App",
"subdomain": "my-iot-central-app",
"template": "iotc-pnp-preview@1.0.0"
},
"identity": {
"type": "SystemAssigned"
}
}
Modifier une application IoT Central
Vous pouvez modifier une application IoT Central existante. L’exemple suivant montre comment modifier le nom d’affichage et activer l’identité managée affectée par le système :
PATCH https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Utilisez la charge utile suivante pour modifier le nom d’affichage et activer l’identité managée affectée par le système :
{
"properties": {
"displayName": "Contoso IoT Central App"
},
"identity": {
"type": "SystemAssigned"
}
}
Remarque
Vous pouvez uniquement ajouter une identité managée à une application IoT Central qui a été créée dans une région. Toutes les nouvelles applications sont créées dans une région.
Supprimer une application IoT Central
Pour supprimer une application IoT Central, utilisez :
DELETE https://management.azure.com/subscriptions/<your subscription id>/resourceGroups/<your resource group name>/providers/Microsoft.IoTCentral/iotApps/<your application name>?api-version=2021-06-01
Tableaux de bord
Vous pouvez créer des tableaux de bord associés à une organisation spécifique. Un tableau de bord d’organisation n’est visible que par des utilisateurs ayant accès à l’organisation à laquelle le tableau de bord est associé. Seuls les utilisateurs appartenant à un rôle disposant d’autorisations d’accès au tableau de bord de l’organisation peuvent créer, modifier et supprimer des tableaux de bord d’organisation.
Tous les utilisateurs peuvent créer des tableaux de bord personnels, que seuls eux voient. Les utilisateurs peuvent basculer entre les tableaux de bord de l’organisation et personnels.
Remarque
La création de tableaux de bord personnels en utilisant l’API n’est pas prise en charge.
Pour savoir comment gérer des tableaux de bord avec l’interface utilisateur IoT Central, consultez Comment gérer des tableaux de bord.
API REST des tableaux de bord
L’API REST d’IoT Central vous permet de :
- Ajouter un tableau de bord à votre application
- Mettre à jour un tableau de bord dans votre application
- Obtenir la liste des tableaux de bord dans l’application
- Obtenir un tableau de bord par ID
- Supprimer un tableau de bord dans votre application
Utiliser un tableau de bord
Utilisez la demande suivante pour créer un tableau de bord.
PUT https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
dashboardId : Identificateur DTMI unique pour le tableau de bord.
Le corps de la demande contient des champs obligatoires :
@displayName: Nom complet du tableau de bord.@favorite: Le tableau de bord figure-t-il dans la liste des favoris ?group: ID de groupe d’appareils.Tile: configuration spécifiant un objet de vignette, y compris la disposition et le nom d’affichage.
La vignette contient certains champs obligatoires :
| Nom | Description |
|---|---|
displayName |
Nom d’affichage de la vignette |
height |
Hauteur de la vignette |
width |
Largeur de la vignette |
x |
Position horizontale de la vignette |
y |
Position verticale de la vignette |
Les dimensions et l’emplacement d’une vignette utilisent des unités entières. La plus petite vignette possible a une hauteur et une largeur égales à un.
Vous pouvez configurer un objet de vignette pour afficher plusieurs types de données. Cet article comprend des exemples de vignettes qui affichent des graphiques en courbes, du contenu Markdown et une dernière valeur connue. Pour en découvrir plus sur les différents types de vignettes que vous pouvez ajouter à un tableau de bord, consultez Types de vignettes.
Vignette Graphique en courbes
Trace une ou plusieurs valeurs de télémétrie agrégées pour un ou plusieurs appareils sur une période donnée. Par exemple, vous pouvez afficher un graphique en courbes pour tracer la température et la pression moyennes d’un ou plusieurs appareils au cours de la dernière heure.
La vignette de graphique en courbes a la configuration suivante :
| Nom | Description |
|---|---|
capabilities |
Spécifie la valeur d’agrégation de la télémétrie à afficher. |
devices |
Liste des appareils à afficher. |
format |
Configuration de la mise en forme du graphique, comme les axes à utiliser. |
group |
ID du groupe d’appareils à afficher. |
queryRange |
Intervalle de temps et résolution à afficher. |
type |
lineChart |
Vignette Markdown
Vignettes interactives qui affichent un titre et un texte de description au format Markdown. L’URL peut être un lien relatif menant à une autre page de l’application, ou un lien absolu menant à un site externe. La vignette de contenu Markdown a la configuration suivante :
| Nom | Description |
|---|---|
description |
Chaîne Markdown à afficher à l’intérieur de la vignette. |
href |
Lien à visiter quand la vignette est sélectionnée. |
image |
Image encodée en base64 à afficher. |
type |
markdown |
Vignette de la dernière valeur connue
Affiche les dernières valeurs de télémétrie pour un ou plusieurs appareils. Par exemple, vous pouvez utiliser cette vignette pour afficher les valeurs de température, de pression et d’humidité les plus récentes d’un ou plusieurs appareils.
La vignette de la dernière valeur connue (DVC) a la configuration suivante :
| Nom | Description |
|---|---|
capabilities |
Spécifie la télémétrie à afficher. |
devices |
Liste des appareils à afficher. |
format |
Configuration de la mise en forme de la vignette DVC, comme la taille du texte ou le retour automatique à la ligne. |
group |
ID du groupe d’appareils à afficher. |
showTrend |
Afficher la différence entre la dernière valeur connue et la valeur précédente. |
type |
lkv |
L’exemple suivant montre un corps de demande qui ajoute un nouveau tableau de bord comportant des vignettes de graphique en courbes, de contenu Markdown et de dernière valeur connue. Les vignettes DVC et de graphique en courbes sont des vignettes 2x2. La vignette de contenu Markdown est une vignette 1x1. Les vignettes sont organisées sur la ligne supérieure du tableau de bord :
{
"displayName": "My Dashboard ",
"tiles": [
{
"displayName": "LKV Temperature",
"configuration": {
"type": "lkv",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"format": {
"abbreviateValue": false,
"wordWrap": false,
"textSize": 14
}
},
"x": 0,
"y": 0,
"width": 2,
"height": 2
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Average temperature",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"3xksbkqm8r",
"1ak6jtz2m5q",
"h4ow04mv3d"
],
"group": "0fb6cf08-f03c-4987-93f6-72103e9f6100",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 3,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
La réponse à cette demande ressemble à l’exemple suivant :
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "temperature",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Ajouter une configuration de compte de stockage de chargement de fichiers
Utilisez la demande suivante pour créer une configuration de compte de stockage de blob de chargement de fichiers dans votre application IoT Central :
PUT https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Le corps de la demande contient les champs suivants :
account: nom du compte de stockage dans lequel charger le fichier.connectionString: chaîne de connexion à connecter au compte de stockage.container: nom du conteneur à l’intérieur du compte de stockage. L’exemple suivant utilise le nomfileuploads.etag: ETag pour empêcher le conflit avec plusieurs chargementssasTtl: norme de durée ISO 8601, durée pendant laquelle la demande de l’appareil pour charger un fichier est valide avant son expiration.
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H"
}
La réponse à cette demande ressemble à l’exemple suivant :
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "fileuploads",
"sasTtl": "PT1H",
"state": "pending",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Obtenir une configuration de compte de stockage de chargement de fichiers
Utilisez la demande suivante pour récupérer des détails d’une configuration de compte de stockage de blob de chargement de fichiers dans votre application IoT Central :
GET https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
La réponse à cette demande ressemble à l’exemple suivant :
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Mettre à jour la configuration de compte de stockage de chargement de fichiers
Utilisez la demande suivante pour mettre à jour une chaîne de connexion de compte de stockage de blob de chargement de fichiers dans votre application IoT Central :
PATCH https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
{
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/"
}
La réponse à cette demande ressemble à l’exemple suivant :
{
"account": "yourAccountName",
"connectionString": "DefaultEndpointsProtocol=https;AccountName=yourAccountName;AccountKey=*****;BlobEndpoint=https://yourAccountName.blob.core.windows.net/",
"container": "yourContainerName",
"sasTtl": "PT1H",
"state": "succeeded",
"etag": "\"7502ac89-0000-0300-0000-627eaf100000\""
}
Supprimer une configuration de compte de stockage de chargement de fichiers
Utilisez la requête suivante pour supprimer une configuration de compte de stockage :
DELETE https://{your-app-subdomain}.azureiotcentral.com/api/fileUploads?api-version=2022-07-31
Obtenir un tableau de bord
Utilisez la demande suivante pour récupérer les détails d’un tableau de bord en utilisant un ID de tableau de bord.
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
La réponse à cette demande ressemble à l’exemple suivant :
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "My Dashboard",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
Mettre à jour un tableau de bord
PATCH https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
L’exemple suivant montre un corps de requête qui met à jour le nom d’affichage d’un tableau de bord et ajoute le tableau de bord à la liste des favoris :
{
"displayName": "New Dashboard Name",
"favorite": true
}
La réponse à cette demande ressemble à l’exemple suivant :
{
"id": "dtmi:kkfvwa2xi:p7pyt5x38",
"displayName": "New Dashboard Name",
"personal": false,
"tiles": [
{
"displayName": "lineChart",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 5,
"height": 5
}
],
"favorite": true
}
Supprimer un tableau de bord
Utilisez la demande suivante pour supprimer un tableau de bord en utilisant l’ID de tableau de bord :
DELETE https://{your app subdomain}.azureiotcentral.com/api/dashboards/{dashboardId}?api-version=2022-10-31-preview
Lister les tableaux de bord
Utilisez la demande suivante pour récupérer la liste des tableaux de bord à partir de votre application :
GET https://{your app subdomain}.azureiotcentral.com/api/dashboards?api-version=2022-10-31-preview
La réponse à cette demande ressemble à l’exemple suivant :
{
"value": [
{
"id": "dtmi:kkfvwa2xi:p7pyt5x3o",
"displayName": "Dashboard",
"personal": false,
"tiles": [
{
"displayName": "Device templates",
"configuration": {
"type": "markdown",
"description": "Get started by adding your first device.",
"href": "/device-templates/new/devicetemplates",
"image": "f5ba1b00-1d24-4781-869b-6f954df48736"
},
"x": 1,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Quick start demo",
"configuration": {
"type": "markdown",
"description": "Learn how to use Azure IoT Central in minutes.",
"href": "https://aka.ms/iotcentral-pnp-video",
"image": "9eb01d71-491a-44e5-8fac-7af3bc9f9acd"
},
"x": 2,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Tutorials",
"configuration": {
"type": "markdown",
"description": "Step-by-step articles teach you how to create apps and devices.",
"href": "https://aka.ms/iotcentral-pnp-tutorials",
"image": "7d9fc12c-d46e-41c6-885f-0a67c619366e"
},
"x": 3,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Documentation",
"configuration": {
"type": "markdown",
"description": "Comprehensive help articles and links to more support.",
"href": "https://aka.ms/iotcentral-pnp-docs",
"image": "4d6c6373-0220-4191-be2e-d58ca2a289e1"
},
"x": 4,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "IoT Central Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": ""
},
"x": 0,
"y": 0,
"width": 1,
"height": 1
},
{
"displayName": "Contoso Image",
"configuration": {
"type": "image",
"format": {
"backgroundColor": "#FFFFFF",
"fitImage": true,
"showTitle": false,
"textColor": "#FFFFFF",
"textSize": 0,
"textSizeUnit": "px"
},
"image": "c9ac5af4-f38e-4cd3-886a-e0cb107f391c"
},
"x": 0,
"y": 1,
"width": 5,
"height": 3
},
{
"displayName": "Available Memory",
"configuration": {
"type": "lineChart",
"capabilities": [
{
"capability": "AvailableMemory",
"aggregateFunction": "avg"
}
],
"devices": [
"1cfqhp3tue3",
"mcoi4i2qh3"
],
"group": "da48c8fe-bac7-42bc-81c0-d8158551f066",
"format": {
"xAxisEnabled": true,
"yAxisEnabled": true,
"legendEnabled": true
},
"queryRange": {
"type": "time",
"duration": "PT30M",
"resolution": "PT1M"
}
},
"x": 5,
"y": 0,
"width": 2,
"height": 2
}
],
"favorite": false
}
]
}