Groupes d’objets statiques

Les groupes d'objets permettent de gérer plusieurs objets simultanément en les classant dans des groupes. Les groupes d’objets statiques contiennent des objets gérés grâce à la console, l'interface de ligne de commande ou l'API. Les groupes d’objets dynamiques, en revanche, contiennent des objets qui correspondent à une requête spécifiée. Les groupes d’objets statiques peuvent également contenir d'autres groupes d’objets statiques — vous pouvez créer une hiérarchie de groupes. Vous pouvez attacher à un groupe parent une stratégie dont héritent tous ses groupes enfants et tous les objets du groupe, ainsi que leurs groupes enfants. Cela facilite le contrôle des autorisations pour les grands nombres d'objets.

Note

Les politiques relatives aux groupes d'objets n'autorisent pas l'accès aux opérations du plan de AWS IoT Greengrass données. Pour autoriser un objet à accéder à une opération de plan de AWS IoT Greengrass données, ajoutez l'autorisation à une AWS IoT politique que vous associez au certificat de l'objet. Pour de plus amples informations, veuillez consulter Authentification et autorisation de l'appareil dans le AWS IoT Greengrass guide du développeur.

Voici ce que vous pouvez faire avec les groupes d'objets statiques :

• Créer, décrire ou supprimer un groupe.

• Ajouter un objet à un ou plusieurs groupes.

• Supprimer un objet d'un groupe.

• Répertorier les groupes que vous avez créés.

• Répertorier tous les groupes enfants d'un groupe (ses descendants directs et indirects).

• Répertorier les objets d'un groupe, y compris tous les objets de ses groupes enfants.

• Répertorier tous les groupes ascendants d'un groupe (ses parents directs et indirects).

• Ajouter, supprimer ou mettre à jour les attributs d'un groupe. Les attributs sont des paires nom-valeur que vous pouvez utiliser afin de stocker des informations relatives à un groupe.

• Attacher une stratégie à un groupe ou la détacher de celui-ci.

• Répertorier les stratégies attachées à un groupe.

• Répertorier les stratégies dont un objet hérite (en fonction des stratégies attachées à son groupe ou à l'un de ses groupes parents).

• Configurer les options de journalisation des objets d'un groupe. veuillez consulter Configuration de la AWS IoT journalisation.

• Créer des tâches qui sont envoyées vers et exécutées sur chaque objet d'un groupe et de ses groupes enfants. veuillez consulter Tâches.

Note

Lorsqu'un objet est attaché à un groupe d'objets statique auquel une AWS IoT Core politique est attachée, le nom de l'objet doit correspondre à l'ID du client.

Voici quelques restrictions relatives aux groupes d'objets statiques :

• Un groupe peut avoir un parent direct au maximum.

• Si un groupe est un enfant d'un autre groupe, indiquez-le au moment de sa création.

• Vous ne pouvez pas modifier le parent d'un groupe ultérieurement. Veillez donc à planifier votre hiérarchie de groupe et à créer un groupe parent avant de créer les groupes enfants qu'il contient.

• Le nombre de groupes auxquels un objet peut appartenir est limité.

• Vous ne pouvez pas ajouter un objet à plusieurs groupes de la même hiérarchie. (En d'autres termes, vous ne pouvez pas ajouter un objet à deux groupes qui partagent un même parent).

• Vous ne pouvez pas renommer un groupe.

• Les noms des groupes d'objets ne peuvent contenir aucun caractère international, comme û, é et ñ.

• N'utilisez pas d'informations personnellement identifiables dans le nom de votre groupe d'objets. Le nom de groupe d'objet peut apparaître dans les communications et les rapports non chiffrés.

Le fait d'attacher des stratégies aux groupes ou de les détacher de ceux-ci vous permet d'améliorer la sécurité des opérations AWS IoT de nombreuses façons importantes. La méthode par appareil qui consiste à attacher une stratégie à un certificat, qui est lui-même attaché ensuite à un objet, prend du temps et complique la mise à jour ou la modification rapide des stratégies pour tout un parc d'appareils. Le fait d'attacher une stratégie au groupe de l'objet permet d'éviter certaines étapes lors de la rotation des certificats pour un objet. De plus, les stratégies sont appliquées dynamiquement aux objets lorsqu'elles changent d'appartenance à un groupe, ce qui signifie que vous n'avez pas besoin de recréer un ensemble complexe d'autorisations chaque fois qu'un appareil change d'appartenance dans un groupe.

Créer un groupe d’objets statiques

Utilisez la commande CreateThingGroup pour créer un groupe d'objets statiques.

$ aws iot create-thing-group --thing-group-name LightBulbs

La commande CreateThingGroup renvoie une réponse qui contient le nom, l'ID et l'ARN du groupe d’objets statiques :

{
    "thingGroupName": "LightBulbs", 
    "thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx",
    "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
}

Note

Nous vous déconseillons d'utiliser des informations personnelles identifiables dans le nom de vos groupes d'objets.

Voici un exemple qui spécifie un parent du groupe d'objets statiques lors de sa création :

$ aws iot create-thing-group --thing-group-name RedLights --parent-group-name LightBulbs

Comme auparavant, la commande CreateThingGroup renvoie une réponse qui contient le nom, l’ID et l’ARN du groupe d'objets statiques :

{
    "thingGroupName": "RedLights", 
    "thingGroupId": "abcdefgh12345678ijklmnop12345678qrstuvwx",
    "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights",
}

Important

Gardez à l'esprit les limites suivantes lorsque vous créez des hiérarchies de groupes d’objets :

• Un groupe d’objets ne peut avoir qu'un seul parent direct.

• Le nombre de groupes d’enfants directs qu'un groupe d’objets peut avoir est limité.

• Le nombre maximal de niveaux d'une hiérarchie de groupes d'objets est limité.

• Le nombre d'attributs qu'un groupe d’objets peut avoir est limité. Les attributs sont des paires nom-valeur que vous pouvez utiliser afin de stocker des informations relatives à un groupe. La longueur du nom de chaque attribut et de chaque valeur est également limitée.

Décrire un groupe d'objets

Pour obtenir des informations sur un groupe d'objets, vous pouvez utiliser la commande DescribeThingGroup :

$ aws iot describe-thing-group --thing-group-name RedLights

La commande DescribeThingGroup renvoie des informations sur le groupe spécifié :

{
    "thingGroupName": "RedLights", 
    "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights",
    "thingGroupId": "12345678abcdefgh12345678ijklmnop12345678",
    "version": 1,
    "thingGroupMetadata": {
        "creationDate": 1478299948.882
        "parentGroupName": "Lights",
        "rootToParentThingGroups": [
            {
                "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ShinyObjects",
                "groupName": "ShinyObjects"
            },
            {
                "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs",
                "groupName": "LightBulbs"
            }
        ]
    },
    "thingGroupProperties": {
        "attributePayload": {
            "attributes": {
                "brightness": "3400_lumens"
            },
        },
        "thingGroupDescription": "string"
    },
}

Ajouter un objet à un groupe d’objets statiques

Vous pouvez utiliser la commande AddThingToThingGroup pour ajouter un objet à un groupe d’objets statiques :

$ aws iot add-thing-to-thing-group --thing-name MyLightBulb --thing-group-name RedLights

La commande AddThingToThingGroup ne génère pas de sortie.

Important

Vous pouvez ajouter un objet à un maximum de 10 groupes. Mais vous ne pouvez pas ajouter un objet à plusieurs groupes de la même hiérarchie. (En d'autres termes, vous ne pouvez pas ajouter un objet à deux groupes qui partagent un même parent.)

Si un objet appartient à autant de groupes d'objets que possible et qu'un ou plusieurs de ces groupes est un groupe d'objets dynamiques, vous pouvez utiliser l'indicateur overrideDynamicGroups pour que les groupes statiques soient prioritaires par rapport aux groupes dynamiques.

Supprimer un objet d'un groupe d’objet statiques

Vous pouvez utiliser la commande RemoveThingFromThingGroup pour supprimer un objet d'un groupe :

$ aws iot remove-thing-from-thing-group --thing-name MyLightBulb --thing-group-name RedLights

La commande RemoveThingFromThingGroup ne génère pas de sortie.

Répertorier les objets d'un groupe d'objets

Vous pouvez utiliser la commande ListThingsInThingGroup pour répertorier les objets appartenant à un groupe :

$ aws iot list-things-in-thing-group --thing-group-name LightBulbs

La commande ListThingsInThingGroup renvoie une liste des objets d'un groupe donné :

{
    "things":[
        "TestThingA"
    ]
}

Le paramètre --recursive vous permet de répertorier les objets appartenant à un groupe et ceux figurant dans ses groupes enfants :

$ aws iot list-things-in-thing-group --thing-group-name LightBulbs --recursive

{
    "things":[
        "TestThingA",
        "MyLightBulb"
    ]
}

Note

Cette opération est cohérente à terme. En d'autres termes, les modifications apportées au groupe d'objets peuvent ne pas être reflétées immédiatement.

Répertorier les groupes d'objets

Vous pouvez utiliser la commande ListThingGroups pour répertorier les groupes d’objets de votre compte :

$ aws iot list-thing-groups

La ListThingGroups commande renvoie une liste des groupes d'objets de votre Compte AWS :

{
    "thingGroups": [
        {
            "groupName": "LightBulbs", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
        },
        {
            "groupName": "RedLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
        },
        {
            "groupName": "RedLEDLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights"
        },
        {
            "groupName": "RedIncandescentLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights"
        }
        {
            "groupName": "ReplaceableObjects", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects"
        }
    ]
}

Utilisez les filtres facultatifs pour répertorier les groupes ayant un groupe donné comme parent (--parent-group) ou ceux dont le nom commence par un préfixe spécifique (--name-prefix-filter). Le paramètre --recursive vous permet de répertorier tous les groupes enfants, et pas seulement les groupes enfants directs d'un groupe d'objets :

$ aws iot list-thing-groups --parent-group LightBulbs

Dans ce cas, la ListThingGroups commande renvoie une liste des groupes enfants directs du groupe d'objets défini dans votre Compte AWS :

{
    "childGroups":[
        {
            "groupName": "RedLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
        }
    ]
}

Utilisez le paramètre --recursive avec la commande ListThingGroups pour répertorier tous les groupes enfants d'un groupe d'objets, et pas seulement les enfants directs :

$ aws iot list-thing-groups --parent-group LightBulbs --recursive

La commande ListThingGroups renvoie une liste de tous les groupes enfants du groupe d'objets :

{
    "childGroups":[
        {
            "groupName": "RedLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
        },
        {
            "groupName": "RedLEDLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLEDLights"
        },
        {
            "groupName": "RedIncandescentLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedIncandescentLights"
        }
    ]
}

Note

Cette opération est cohérente à terme. En d'autres termes, les modifications apportées au groupe d'objets peuvent ne pas être reflétées immédiatement.

Répertorier les groupes d'un objet

Vous pouvez utiliser la commande ListThingGroupsForThing pour répertorier les objets appartenant à un groupe :

$ aws iot list-thing-groups-for-thing --thing-name MyLightBulb

La ListThingGroupsForThing commande renvoie une liste des groupes d'objets auxquels appartient un objet :

{
    "thingGroups":[
        {
            "groupName": "LightBulbs", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs"
        },
        {
            "groupName": "RedLights", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"
        },
        {
            "groupName": "ReplaceableObjects", 
            "groupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/ReplaceableObjects"
        }
    ]
}

Mettre à jour un groupe d’objets statiques

Vous pouvez utiliser la commande UpdateThingGroup afin de mettre à jour les attributs d'un groupe d'objets statiques :

$ aws iot update-thing-group --thing-group-name "LightBulbs" --thing-group-properties "thingGroupDescription=\"this is a test group\", attributePayload=\"{\"attributes\"={\"Owner\"=\"150\",\"modelNames\"=\"456\"}}"

La commande UpdateThingGroup renvoie une réponse qui contient le numéro de version du groupe après la mise à jour :

{
    "version": 4
}

Note

Le nombre d'attributs qu'un objet peut avoir est limité.

Supprimer un groupe d'objets

Pour supprimer un groupe d'objets, utilisez la commande DeleteThingGroup :

$ aws iot delete-thing-group --thing-group-name "RedLights"

La commande DeleteThingGroup ne génère pas de sortie.

Important

Si vous essayez de supprimer un groupe d'objets qui comporte des groupes d'objets enfants, vous recevez une erreur :

A client error (InvalidRequestException) occurred when calling the DeleteThingGroup 
operation: Cannot delete thing group : RedLights when there are still child groups attached to it.

Avant de supprimer le groupe, supprimez d'abord tous les groupes d'enfants.

Vous pouvez supprimer un groupe qui a des objets enfants, mais les autorisations accordées aux objets par appartenance au groupe ne s'appliqueront plus. Avant de supprimer un groupe auquel une stratégie est attachée, vérifiez que la suppression de ces autorisations n'empêchera pas les objets du groupe de fonctionner correctement. En outre, les commandes qui indiquent à quels groupes appartient un objet (par exempleListGroupsForThing) peuvent continuer à afficher le groupe pendant la mise à jour des enregistrements dans le cloud.

Attacher une stratégie à un groupe d’objets statiques

Vous pouvez utiliser la commande AttachPolicy pour attacher une stratégie à un groupe d'objets statiques et, par extension, à tous les objets de ce groupe et de ses groupes enfants :

$ aws iot attach-policy \
  --target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" \
  --policy-name "myLightBulbPolicy"

La commande AttachPolicy ne génère pas de sortie

Important

Vous pouvez attacher au maximum deux stratégies à un groupe.

Note

Nous vous déconseillons d'utiliser des informations personnelles identifiables dans le nom de votre politique.

Le paramètre --target peut être un ARN de groupe d'objets (comme ci-dessus), un certificat d’ARN ou une identité Amazon Cognito. Pour plus d'informations sur les stratégies, les certificats et l'authentification, consultez Authentification.

Pour plus d'informations, consultez AWS IoT Core Stratégies .

Détacher une stratégie d'un groupe d’objets statiques

Vous pouvez utiliser la commande DetachPolicy pour détacher une stratégie d'un groupe d'objets et, par extension, de tous les objets de ce groupe et de ses groupes enfants :

$ aws iot detach-policy --target "arn:aws:iot:us-west-2:123456789012:thinggroup/LightBulbs" --policy-name "myLightBulbPolicy"

La commande DetachPolicy ne génère pas de sortie.

Répertorier les stratégies attachées à un groupe d'objets statiques

Vous pouvez utiliser la commande ListAttachedPolicies pour répertorier les stratégies attachées à un groupe d’objets statiques :

$ aws iot list-attached-policies --target "arn:aws:iot:us-west-2:123456789012:thinggroup/RedLights"

Le --target paramètre peut être un ARN de groupe d'objets (comme ci-dessus), un ARN de certificat ou une identité Amazon Cognito.

Ajoutez le paramètre facultatif --recursive afin d'inclure toutes les stratégies attachées aux groupes parents du groupe.

La commande ListAttachedPolicies renvoie une liste de stratégies :

{
    "policies": [
        "MyLightBulbPolicy" 
        ...
    ]
}

Répertorier les groupes d'une stratégie

Vous pouvez utiliser la commande ListTargetsForPolicy afin de répertorier les cibles, y compris tous les groupes éventuels, auxquelles une stratégie est attachée :

$ aws iot list-targets-for-policy --policy-name "MyLightBulbPolicy"

Ajoutez le paramètre facultatif --page-size number afin de spécifier le nombre maximal de résultats renvoyés par chaque demande, et le paramètre --marker string sur les appels suivants afin d'extraire l'ensemble de résultats suivant, le cas échéant.

La commande ListTargetsForPolicy renvoie une liste des cibles et des jetons à utiliser pour extraire davantage de résultats :

{
    "nextMarker": "string",
    "targets": [ "string" ... ]
}

Obtenir des stratégies efficaces pour un objet

Vous pouvez utiliser la commande GetEffectivePolicies afin de répertorier les stratégies en vigueur pour un objet, y compris les stratégies attachées aux groupes auxquels l'objet appartient (que le groupe soit un parent direct ou un ancêtre indirect) :

$ aws iot get-effective-policies \
  --thing-name "MyLightBulb" \
  --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847"

Utilisez le paramètre --principal afin de spécifier l'ARN du certificat attaché à l'objet. Si vous avez opté pour l'authentification d'identité Amazon Cognito, utilisez le --cognito-identity-pool-id paramètre et ajoutez si nécessaire --principal Amazon Cognitole paramètre afin de spécifier une identité . Si vous spécifiez uniquement le --cognito-identity-pool-id, les stratégies associées à ce rôle du pool d'identités pour les utilisateurs non authentifiés sont renvoyées. Si vous utilisez les deux, les stratégies associées à ce rôle du pool d'identités pour les utilisateurs authentifiés sont renvoyées.

Le paramètre --thing-name est facultatif et peut être utilisé à la place du paramètre --principal. Lorsqu'il est utilisé, les stratégies attachées aux groupes auxquels l'objet appartient et les stratégies attachées aux groupes parents de ces groupes (jusqu'au groupe racine dans la hiérarchie) sont renvoyées.

La commande GetEffectivePolicies renvoie une liste de stratégies :

{
    "effectivePolicies": [
        {
            "policyArn": "string",
            "policyDocument": "string",
            "policyName": "string"
        }
        ...
    ]
}

Tester l'autorisation pour les actions MQTT

Vous pouvez utiliser la TestAuthorization commande afin de tester si une action MQTT (Publish, Subscribe) est autorisée pour un objet :

aws iot test-authorization \
    --principal "arn:aws:iot:us-east-1:123456789012:cert/a0c01f5835079de0a7514643d68ef8414ab739a1e94ee4162977b02b12842847" \
    --auth-infos "{\"actionType\": \"PUBLISH\", \"resources\": [ \"arn:aws:iot:us-east-1:123456789012:topic/my/topic\"]}"

Utilisez le paramètre --principal afin de spécifier l'ARN du certificat attaché à l'objet. Si vous utilisez l'authentification d'identité Amazon Cognito, spécifiez une identité Cognito comme --principal ou utilisez le --cognito-identity-pool-id paramètre , ou les deux. Si vous spécifiez uniquement le paramètre --cognito-identity-pool-id, les stratégies associées à ce rôle du pool d'identités pour les utilisateurs non authentifiés sont appliquées. Si vous utilisez les deux, les stratégies associées à ce rôle du pool d'identités pour les utilisateurs authentifiés sont appliquées.

Spécifiez une ou plusieurs actions MQTT que vous souhaitez tester en répertoriant des ensembles de ressources et de types d'actions après le paramètre --auth-infos. Le champ actionType doit contenir « PUBLISH », « SUBSCRIBE », « RECEIVE » ou « CONNECT ». Le champ resources doit contenir une liste d'ARN des ressources. Pour plus d’informations, consultez AWS IoT Core politiques.

Vous pouvez tester les conséquences de l'ajout des stratégies en les spécifiant avec le paramètre --policy-names-to-add. Ou vous pouvez tester les conséquences de la suppression des stratégies en les spécifiant avec le paramètre --policy-names-to-skip.

Vous pouvez utiliser le paramètre facultatif --client-id pour affiner vos résultats.

La commande TestAuthorization renvoie des détails sur les actions qui ont été autorisées ou refusées pour chaque ensemble de requêtes --auth-infos que vous avez spécifié :

{
    "authResults": [
        {
            "allowed": {
                "policies": [
                    {
                        "policyArn": "string",
                        "policyName": "string"
                    }
                ]
            },
            "authDecision": "string",
            "authInfo": {
                "actionType": "string",
                "resources": [ "string" ]
            },
            "denied": {
                "explicitDeny": {
                    "policies": [
                        {
                            "policyArn": "string",
                            "policyName": "string"
                        }
                    ]
                },
                "implicitDeny": {
                    "policies": [
                        {
                            "policyArn": "string",
                            "policyName": "string"
                        }
                    ]
                }
            },
            "missingContextValues": [ "string" ]
        }
    ]
}