Grupos de objetos estáticas

Os grupos de objetos estáticas permitem gerenciar várias objetos simultaneamente, categorizando-as em grupos. Os grupos de objetos estáticas contêm um grupo de objetos que são gerenciadas usando o console, a CLI ou a API. Grupos de objetos dinâmicos, por outro lado, contêm objetos que correspondem a uma consulta especificada. Os grupos de itens estáticos também podem conter outros grupos do mesmo tipo. Então, você pode criar uma hierarquia de grupos. Você pode anexar uma política a um grupo pai, e ela será herdada pelos grupos filho, e por todas as objetos do grupo e também dos grupos filho. Isso facilita o controle de permissões para grandes números de objetos.

Veja o que você pode fazer com grupos de objetos estáticas:

Estas são algumas limitações de grupos de objetos estáticas:

Anexar e desanexar políticas em grupos pode aprimorar a segurança das operações da AWS IoT de várias maneiras significativas. O método por dispositivo de anexar uma política a um certificado, que, depois, é anexado a um objeto, é demorado e dificulta a atualização ou a alteração rápida de políticas em toda a frota de dispositivos. Ter uma política anexada ao grupo do objeto economiza etapas na hora de alternar os certificados em um objeto. Além disso, as políticas são aplicadas dinamicamente o objetos quando suas associações a grupos é alterada, portanto, não é necessário recriar um conjunto complexo de permissões toda vez que a associação de um dispositivo é alterada em um grupo.

Criar um grupo de objetos estáticas

Use o comando CreateThingGroup para criar um grupo de objetos estáticas:

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

O comando CreateThingGroup retorna uma resposta que contém o nome, ID e ARN do grupo de objetos estáticas:

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

Este é um exemplo que especifica um pai do grupo de objetos estáticas quando ele é criado:

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

Como anteriormente, o comando CreateThingGroup retorna uma resposta que contém o grupo de objetos, seu ID e ARN:

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

Descrever um grupo de objetos

Você pode usar o comando DescribeThingGroup para obter informações sobre um grupo de objetos:

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

O comando DescribeThingGroup retorna informações sobre o grupo especificado:

{
    "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"
    },
}

Adicionar um objeto a um grupo de objetos estáticas

Você pode usar o comando AddThingToThingGroup para adicionar um objeto a um grupo de objetos estáticas:

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

O comando AddThingToThingGroup não produz nenhuma saída.

Remover um objeto de um grupo de objetos estáticas

Você pode usar o comando RemoveThingFromThingGroup para remover um objeto de um grupo:

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

O comando RemoveThingFromThingGroup não produz nenhuma saída.

Listar objetos em um grupo de objetos

Você pode usar o comando ListThingsInThingGroup para listar objetos que pertencem a um grupo:

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

O comando ListThingsInThingGroup retorna uma lista das objetos no grupo especificado:

{
    "things":[
        "TestThingA"
    ]
}

Com o parâmetro --recursive, você pode listar objetos que pertencem a um grupo e a qualquer um dos grupos filho:

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

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

Listar grupos de objetos

Você pode usar o comando ListThingGroups para listar grupos de objetos da sua conta:

$ aws iot list-thing-groups

O ListThingGroups comando retorna uma lista dos grupos de coisas em seu Conta da 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"
        }
    ]
}

Use os filtros opcionais para listar os grupos que têm um determinado grupo como pai (--parent-group) ou grupos cujos nomes começam com um determinado prefixo (--name-prefix-filter). O parâmetro --recursive permite que você liste todos os grupos filho, não apenas grupos filho diretos de um grupo de objetos:

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

Nesse caso, o ListThingGroups comando retorna uma lista dos grupos secundários diretos do grupo de coisas definido em seu Conta da AWS:

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

Use o parâmetro --recursive com o comando ListThingGroups para listar todos os grupos filho de um grupo de objetos, não apenas os filhos diretos:

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

O comando ListThingGroups retorna uma lista de todos os grupos filho de um grupo de objetos:

{
    "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"
        }
    ]
}

Listar grupos para um objeto

Você pode usar o comando ListThingGroupsForThing para listar grupos diretos a que um objeto pertence:

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

O comando ListThingGroupsForThing retorna uma lista dos grupos diretos de objetos aos quais o objeto pertence, incluindo todos os grupos pai:

{
    "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"
        }
    ]
}

Atualizar um grupo de objetos estáticas

Você pode usar o comando UpdateThingGroup para atualizar os atributos de um grupo de objetos estáticas:

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

O comando UpdateThingGroup retorna uma resposta que contém o número da versão do grupo depois da atualização:

{
    "version": 4
}

Excluir um grupo de objetos

Para excluir um grupo de objetos, use o comando DeleteThingGroup:

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

O comando DeleteThingGroup não produz nenhuma saída.

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

Você pode excluir um grupo de objetos filho, mas as permissões concedidas para as objetos por associação no grupo não se aplicarão mais. Antes de excluir um grupo que tem uma política anexada, verifique cuidadosamente se a remoção dessas permissões não fará com que as objetos no grupo não funcionem corretamente. Além disso, os comandos que mostram a quais grupos uma coisa pertence (por exemplo,ListGroupsForThing) podem continuar mostrando o grupo enquanto os registros na nuvem estão sendo atualizados.

Anexar uma política a um grupo de objetos estáticas

Você pode usar o comando AttachPolicy para anexar uma política a um grupo de objetos estáticas e, por extensão, a todas as objetos daquele grupo e objetos em qualquer um dos grupos filho:

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

O comando AttachPolicy não produz nenhuma saída

O parâmetro --target pode ser o ARN de um grupo de objetos (conforme acima), o ARN de um certificado ou uma identidade do Amazon Cognito. Para obter mais informações sobre políticas, certificados e autenticação, consulte Autenticação.

Para obter mais informações, consulte Políticas AWS IoT Core.

Desanexar uma política de um grupo de objetos estáticas

Você pode usar o comando DetachPolicy para desanexar uma política de um grupo de objetos e, portanto, por extensão, de todas as objetos daquele grupo e objetos em qualquer um dos grupos filho:

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

O comando DetachPolicy não produz nenhuma saída.

Listar as políticas anexadas a um grupo de objetos estáticas

Você pode usar o comando ListAttachedPolicies para listar as políticas anexadas a um grupo de objetos estáticas:

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

O parâmetro --target pode ser o ARN de um grupo de objetos (conforme acima), o ARN de um certificado ou uma identidade do Amazon Cognito.

Adicione o parâmetro --recursive opcional para incluir todas as políticas anexadas aos grupos pai do grupo.

O comando ListAttachedPolicies retorna uma lista de políticas:

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

Listar os grupos para uma política

Você pode usar o comando ListTargetsForPolicy para listar os destinos, incluindo todos os grupos, aos quais uma política está anexada:

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

Adicione o parâmetro --page-size number opcional para especificar o número máximo de resultados a serem retornados em cada consulta, e o parâmetro --marker string em chamadas subsequentes para recuperar o próximo conjunto de resultados, se houver.

O comando ListTargetsForPolicy retorna uma lista de destinos e o token a ser usado para recuperar mais resultados:

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

Obter políticas efetivas para um objeto

Você pode usar o comando GetEffectivePolicies para listar as políticas em vigor para um objeto, incluindo as políticas anexadas a todos os grupos aos quais o objeto pertence (se o grupo for um pai direto ou um ancestral indireto):

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

Use o parâmetro --principal para especificar o ARN do certificado anexado ao objeto. Se você estiver usando a autenticação de identidades do Amazon Cognito, use o parâmetro --cognito-identity-pool-id e, opcionalmente, adicione o parâmetro --principal para especificar uma identidade específica do Amazon Cognito. Se você especificar apenas o --cognito-identity-pool-id, as políticas associadas a essa função do banco de identidades para usuários não autenticados serão retornadas. Se usar os dois, as políticas associadas a essa função do banco de identidades para usuários autenticados serão retornadas.

O parâmetro --thing-name é opcional e pode ser usado em vez do parâmetro --principal. Quando o parâmetro é usado, as políticas anexadas a qualquer grupo ao qual o objeto pertence e as políticas anexadas a qualquer grupo pai desses grupos (até o grupo raiz na hierarquia) são retornadas.

O comando GetEffectivePolicies retorna uma lista de políticas:

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

Testar a autorização de ações MQTT

Você pode usar o comando TestAuthorization para testar se uma ação MQTT (Publish, Subscribe) é permitida para um objeto:

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\"]}"

Use o parâmetro --principal para especificar o ARN do certificado anexado ao objeto. Se estiver usando a autenticação de identidade do Amazon Cognito, especifique uma identidade do Cognito como --principal ou use o parâmetro --cognito-identity-pool-id ou ambos. (Se você especificar apenas o --cognito-identity-pool-id, as políticas associadas a essa função do banco de identidades para usuários não autenticados serão consideradas. Se você usar os dois parâmetros, as políticas associadas a essa função do banco de identidades para usuários autenticados serão consideradas.

Especifique uma ou mais ações MQTT que você deseja testar listando conjuntos de recursos e tipos de ação depois do parâmetro --auth-infos. O campo actionType deve conter as opções "PUBLICAR", "ASSINAR", "RECEBER" ou "CONECTAR". O campo resources deve conter uma lista de ARNs de recursos. Consulte AWS IoT Core políticas para obter mais informações.

Você pode testar os efeitos da adição de políticas especificando-as com o parâmetro --policy-names-to-add. Ou pode testar os efeitos da remoção de políticas especificando-as com o parâmetro --policy-names-to-skip.

Você pode usar o parâmetro --client-id opcional para refinar ainda mais os resultados.

O comando TestAuthorization retorna detalhes das ações que foram permitidas ou negadas para cada conjunto de consultas --auth-infos que você especificou:

{
    "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" ]
        }
    ]
}