Share via

Comment utiliser l’API REST IoT Central pour gérer les organisations

  • Article

L’API REST IoT Central vous permet de développer des applications clientes qui s’intègrent à des applications IoT Central. Vous pouvez utiliser l’API REST pour gérer les organisations dans votre application IoT Central.

Chaque appel d’API REST IoT Central nécessite un en-tête d’autorisation. Pour plus d’informations, consultez Comment authentifier et autoriser les appels d’API REST d’IoT Central.

Pour obtenir la documentation de référence sur l’API REST IoT Central, consultez Informations de référence sur l’API REST d’Azure IoT Central.

Pour en savoir plus sur les organisations dans une application IoT Central, consultez Gérer des organisations IoT Central.

Conseil

Vous pouvez utiliser Postman pour tester les appels d’API REST décrits dans cet article. Téléchargez la collection IoT Central Postman et importez-la dans Postman. Dans la collection, vous devez définir des variables telles que votre sous-domaine d’application et le jeton d’administrateur.

API REST Organisations

L’API REST d’IoT Central vous permet de :

  • Ajouter une organisation à votre application
  • Récupérer une organisation par ID
  • Mettre à jour une organisation dans votre application
  • Obtenir la liste des organisations dans l’application
  • Supprimer une organisation dans votre application

Créer des organisations

L’API REST vous permet de créer des organisations dans votre application IoT Central. Utilisez la requête suivante pour créer une organisation dans votre application :

PUT https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31
  • organizationId - ID unique de l’organisation

L’exemple suivant montre un corps de demande qui ajoute une organisation à une application IoT Central.

{
  "displayName": "Seattle",
}

Le corps de la demande contient des champs obligatoires :

  • @displayName : nom d’affichage de l’organisation.

Le corps de la demande contient des champs facultatifs :

  • @parent : ID du parent de l’organisation.

Si vous ne spécifiez pas de parent, l’organisation obtient l’organisation de niveau supérieur par défaut en tant que parent.

La réponse à cette demande ressemble à l’exemple suivant :

{
  "id": "seattle",
  "displayName": "Seattle"
}

Vous pouvez créer une organisation avec une hiérarchie. Par exemple, vous pouvez créer une organisation de ventes avec une organisation parente.

L’exemple suivant montre un corps de demande qui ajoute une organisation à une application IoT Central.

{
  "displayName": "Sales",
  "parent":"seattle"
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "id": "sales",
  "displayName": "Sales",
  "parent":"Seattle"
}

Obtenir une organisation

Utilisez la demande suivante pour récupérer les détails d’une organisation individuelle à partir de votre application :

GET https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant :

{
  "id": "seattle",
  "displayName": "Seattle",
  "parent": "washington"
}

Mettre à jour une organisation

Utilisez la demande suivante pour mettre à jour les détails d’une organisation dans votre application :

PATCH https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

L’exemple suivant montre un corps de requête qui met à jour le parent de l’organisation :

{
  "parent": "washington"
}

La réponse à cette demande ressemble à l’exemple suivant :

{
  "id": "seattle",
  "displayName": "Seattle Sales",
  "parent": "washington"
}

Afficher la liste des organisations

Utilisez la demande suivante pour récupérer une liste d’organisations à partir de votre application :

GET https://{your app subdomain}.azureiotcentral.com/api/organizations?api-version=2022-07-31

La réponse à cette demande se présente comme dans l’exemple suivant.

{
    "value": [
        {
            "id": "washington",
            "displayName": "Washington"
        },
        {
            "id": "redmond",
            "displayName": "Redmond"
        },
        {
            "id": "bellevue",
            "displayName": "Bellevue"
        },
        {
            "id": "spokane",
            "displayName": "Spokane",
            "parent": "washington"
        },
        {
            "id": "seattle",
            "displayName": "Seattle",
            "parent": "washington"
        }
    ]
}

Les organisations Washington, Redmond et Bellevue ont automatiquement l’organisation de niveau supérieur par défaut de l’application en tant que parent.

Supprimer une organisation

Utilisez la demande suivante pour supprimer une organisation :

DELETE https://{your app subdomain}.azureiotcentral.com/api/organizations/{organizationId}?api-version=2022-07-31

Utiliser des organisations

Utilisez des organisations pour gérer l’accès aux ressources dans votre application.

Gérer les rôles

L’API REST vous permet de répertorier les rôles définis dans votre application IoT Central. Utilisez la requête suivante pour récupérer une liste d’ID de rôle d’application et de rôle d’organisation à partir de votre application. Pour plus d’informations, consultez Comment gérer les organisations IoT Central :

GET https://{your app subdomain}.azureiotcentral.com/api/roles?api-version=2022-07-31

La réponse à cette demande ressemble à l’exemple suivant qui inclut les ID de rôle d’application et de rôle d’organisation.

{
    "value": [
        {
            "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
            "displayName": "Administrator"
        },
        {
            "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
            "displayName": "Operator"
        },
        {
            "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
            "displayName": "Builder"
        },
        {
            "id": "c495eb57-eb18-489e-9802-62c474e5645c",
            "displayName": "Org Admin"
        },
        {
            "id": "b4935647-30e4-4ed3-9074-dcac66c2f8ef",
            "displayName": "Org Operator"
        },
        {
            "id": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "displayName": "Org Viewer"
        }
    ]
}

Créer un jeton d’API attaché à un nœud dans une hiérarchie d’organisation

Utilisez la requête suivante pour créer un jeton d’API attaché à un nœud dans une hiérarchie d’organisation dans votre application :

PUT https://{your app subdomain}.azureiotcentral.com/api/apiTokens/{tokenId}?api-version=2022-07-31
  • tokenId - ID unique du jeton

L’exemple suivant montre un corps de requête qui crée un jeton d’API pour l’organisation seattle dans une application IoT Central.

{
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ]
}

Le corps de la demande contient des champs obligatoires :

Nom Description
role ID de l’un des rôles d’organisation
organisation ID de l’organisation

La réponse à cette demande ressemble à l’exemple suivant :

{
    "id": "token1",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "expiry": "2023-07-07T17:05:08.407Z",
    "token": "SharedAccessSignature sr=8a0617**********************4c0d71c&sig=3RyX69G4%2FBZZnG0LXOjQv*************e8s%3D&skn=token1&se=1688749508407"
}

Associer un utilisateur à un nœud dans une hiérarchie d’organisation

Utilisez la demande suivante pour créer et associer un utilisateur à un nœud dans une hiérarchie d’organisation dans votre application. L’ID et l’e-mail doivent être uniques dans l’application :

PUT https://{your app subdomain}.azureiotcentral.com/api/users/user-001?api-version=2022-07-31

Dans le corps de demande suivant, role est l’ID de l’un des rôles d’organisation, et organization l’ID de l’organisation

{
  "id": "user-001",
  "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"

}

La réponse à cette demande se présente comme dans l’exemple suivant. La valeur de rôle identifie le rôle auquel l’utilisateur est associé :

{
    "id": "user-001",
    "type": "email",
    "roles": [
        {
            "role": "84cc62c1-dabe-49d3-b16e-8b291232b285",
            "organization": "seattle"
        }
    ],
    "email": "user5@contoso.com"
}

Ajouter et associer un appareil à une organisation

Utilisez la demande suivante pour associer un nouvel appareil à une organisation

PUT https://{your app subdomain}.azureiotcentral.com/api/devices/{deviceId}?api-version=2022-07-31

L’exemple suivant montre un corps de demande qui ajoute un appareil pour un modèle d’appareil. Vous pouvez accéder aux détails template à partir de la page Modèles d’appareil dans l’interface utilisateur de l’application IoT Central.

{
    "displayName": "CheckoutThermostat",
    "template": "dtmi:contoso:Thermostat;1",
    "simulated": true,
    "enabled": true,
    "organizations": [
        "seattle"
    ]
}

Le corps de la demande contient des champs obligatoires :

  • @displayName : nom complet de l’appareil.
  • @enabled : déclare que cet objet est une interface.
  • @etag : ETag utilisé pour empêcher les conflits dans les mises à jour de l’appareil.
  • simulated: L’appareil est-il simulé ?
  • template : définition du modèle d’appareil pour l’appareil.
  • organizations : liste d’ID d’organisation auxquels l’appareil appartient. Actuellement, vous ne pouvez associer qu’un appareil à une organisation.

La réponse à cette demande ressemble à l’exemple suivant :

{
    "id": "thermostat1",
    "etag": "eyJoZWFkZXIiOiJcIjI0MDAwYTdkLTAwMDAtMDMwMC0wMDAwLTYxYjgxZDIwMDAwMFwiIiwiZGF0YSI6IlwiMzMwMDQ1M2EtMDAwMC0wMzAwLTAwMDAtNjFiODFkMjAwMDAwXCIifQ",
    "displayName": "CheckoutThermostat",
    "simulated": true,
    "provisioned": false,
    "template": "dtmi:contoso:Thermostat;1",
    "enabled": true,
   "organizations": [
    "seattle"
  ]

}

Ajouter et associer un groupe d’appareils à une organisation

Utilisez la demande suivante pour créer et associer un nouveau groupe d’appareils à une organisation.

PUT https://{your app subdomain}.azureiotcentral.com/api/deviceGroups/{deviceGroupId}?api-version=2022-07-31

Lorsque vous créez un groupe d’appareils, vous définissez un filter qui sélectionne les appareils à ajouter au groupe. Un filter identifie un modèle d’appareil et toutes les propriétés à mettre en correspondance. L’exemple suivant crée un groupe d’appareils qui contient tous les appareils associés au dtmi:modelDefinition:dtdlv2 modèle où la provisioned propriété est vraie.

{
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Le corps de la demande contient des champs obligatoires :

  • @displayName : nom d’affichage du groupe d’appareils.
  • @filter: requête définissant les appareils qui doivent se trouver dans ce groupe.
  • description : résumé court du groupe d’appareils.
  • organizations : liste d’ID d’organisation auxquels l’appareil appartient. Actuellement, vous ne pouvez associer qu’un appareil à une organisation.

La réponse à cette demande ressemble à l’exemple suivant :

{
  "id": "group1",
  "displayName": "Device group 1",
  "description": "Custom device group.",
  "filter": "SELECT * FROM devices WHERE $template = \"dtmi:modelDefinition:dtdlv2\" AND $provisioned = true",
  "organizations": [
    "seattle"
  ]
}

Étapes suivantes

Maintenant que vous savez comment gérer les organisations avec l’API REST, nous vous suggérons d’apprendre à utiliser l’API REST IoT Central pour gérer les exportations de données.