Partager via


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 nom fileuploads.
  • etag : ETag pour empêcher le conflit avec plusieurs chargements
  • sasTtl : 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
        }
    ]
}