Gruppi di oggetti statici

La classificazione degli oggetti in gruppi statici consente di gestire diversi oggetti contemporaneamente. I gruppi di oggetti statici contengono un gruppo di oggetti gestiti utilizzando la console, l'interfaccia a riga di comando o l'API. I gruppi di oggetti dinamici, d'altra parte, contengono oggetti che corrispondono a una query specificata. I gruppi di oggetti statici possono anche contenere altri gruppi di oggetti statici. È possibile creare una gerarchia di gruppi. È possibile collegare una policy a un gruppo padre affinché venga ereditata dai gruppi figlio, oltre che da tutti gli oggetti nel gruppo e nei relativi gruppi figlio. In questo modo, si semplifica il controllo delle autorizzazioni per un numero elevato di oggetti.

Nota

Le policy dei gruppi di oggetti non consentono l'accesso alle operazioni del piano AWS IoT Greengrass dati. Per consentire a un oggetto l'accesso a un'operazione del piano AWS IoT Greengrass dati, aggiungi l'autorizzazione a una AWS IoT policy che alleghi al certificato dell'oggetto. Per ulteriori informazioni, consultare Autenticazione e autorizzazione del dispositivo nella Guida per gli sviluppatori di AWS IoT Greengrass .

Di seguito sono elencate le operazioni che è possibile eseguire con i gruppi di oggetti statici:

Creare, descrivere o eliminare un gruppo.
Aggiungere un oggetto a un gruppo o a più gruppi.
Rimuovere un oggetto da un gruppo.
Elencare i gruppi creati.
Elencare tutti i gruppi figlio di un gruppo (i relativi discendenti diretti e indiretti).
Elencare gli oggetti in un gruppo, inclusi tutti gli oggetti nei relativi gruppi figlio.
Elencare tutti i gruppi predecessore di un gruppo (i relativi oggetti padre diretti e indiretti).
Aggiungere, eliminare o aggiornare gli attributi di un gruppo. Gli attributi sono coppie nome–valore che è possibile usare per archiviare le informazioni su un gruppo.
Collegare o scollegare una policy a o da un gruppo.
Elencare le policy collegate a un gruppo.
Elencare le policy ereditate da un oggetto (in forza delle policy collegate al relativo gruppo o a uno dei gruppi padre).
Configurare le opzioni di logging per gli oggetti in un gruppo. Per informazioni, consulta Configurare la registrazione AWS IoT.
Creare processi che vengono inviati ed eseguiti su ogni oggetto in un gruppo e nei relativi gruppi figlio. Per informazioni, consulta Processi.

Nota

Quando un oggetto è collegato a un gruppo di oggetti statico a cui è associata una AWS IoT Core policy, il nome dell'oggetto deve corrispondere all'ID client.

Di seguito sono elencate alcune limitazioni dei gruppi di oggetti statici:

Un gruppo può avere un solo elemento padre diretto.
Se un gruppo è figlio di un altro gruppo, specificalo al momento della creazione.
Non è possibile modificare il padre di un gruppo in un secondo momento, quindi assicurati di pianificare la gerarchia del gruppo e crea un gruppo padre prima di creare i gruppi figlio in esso contenuti.
Il numero di gruppi a cui un oggetto può appartenere è limitato.
Non è possibile aggiungere un oggetto a più di un gruppo nella stessa gerarchia. (In altre parole, non è possibile aggiungere un oggetto a due gruppi che condividono uno stesso padre.)
Non è possibile rinominare un gruppo.
I nomi dei gruppo di oggetti non possono contenere caratteri internazionali, ad esempio, û, é e ñ.
Non utilizzare informazioni di identificazione personale nel nome del gruppo di oggetti. Il nome del gruppo di oggetti può essere visualizzato nelle comunicazioni e nei report non crittografati.

Le operazioni di collegamento e scollegamento di policy ai e dai gruppi possono migliorare notevolmente la sicurezza delle operazioni di AWS IoT in diversi modi. Il metodo per dispositivo di collegamento di una policy a un certificato, che viene quindi collegato a un oggetto, richiede molto tempo e rende difficile aggiornare rapidamente le policy o modificarle in un parco istanze di dispositivi. Se si collega una policy al gruppo di oggetti, sono necessarie meno operazioni quando è il momento di ruotare i certificati di un oggetto. Le policy vengono inoltre applicate dinamicamente agli oggetti quando cambia l'appartenenza ai gruppi, quindi non è necessario ricreare un set di autorizzazioni complesso ogni volta che per un dispositivo cambia l'appartenenza a un gruppo.

Creazione di un gruppo di oggetti statico

Utilizza il comando CreateThingGroup per creare un gruppo di oggetti statico.


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

Il comando CreateThingGroup restituisce una risposta che contiene il nome, l'ID e l'ARN del gruppo di oggetti statico:


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

Nota

Non è consigliabile utilizzare informazioni di identificazione personale nei nomi dei gruppi di oggetti.

Di seguito è illustrato un esempio in cui viene specificato un elemento padre del gruppo di oggetti statico al momento della creazione:


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

Come in precedenza, il comando CreateThingGroup restituisce una risposta che contiene il nome del gruppo di oggetti statico e i relativi ID e ARN:


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

Importante

Quando crei gerarchie di gruppi, tieni presenti i limiti seguenti:

Un gruppo di oggetti può avere un solo elemento padre diretto.
Il numero di gruppi figlio diretti che un gruppo di oggetti può avere è limitato.
La profondità massima di una gerarchia di gruppi è limitata.
Il numero di attributi che un gruppo di oggetti può avere è limitato. Gli attributi sono coppie nome–valore che è possibile usare per archiviare le informazioni su un gruppo. Anche le lunghezze di ciascun nome di attributo e di ogni valore sono limitate.

Descrizione di un gruppo di oggetti

Usa il comando DescribeThingGroup per ottenere informazioni su un gruppo di oggetti:


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

Il comando DescribeThingGroup restituisce le informazioni relative al gruppo specificato:


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

Aggiunta di un oggetto a un gruppo di oggetti statico

È possibile usare il comando AddThingToThingGroup per aggiungere un oggetto a un gruppo di oggetti statico:


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

Il comando AddThingToThingGroup non produce output.

Importante

È possibile aggiungere un oggetto a un massimo di 10 gruppi. Non è tuttavia possibile aggiungere un oggetto a più di un gruppo nella stessa gerarchia. (In altre parole, non è possibile aggiungere un oggetto a due gruppi che condividono uno stesso padre.)

Se un oggetto appartiene al massimo numero possibile di gruppi di oggetti e almeno uno di questi gruppi è un gruppo di oggetti dinamico, è possibile utilizzare il flag overrideDynamicGroups per far sì che i gruppi statici abbiano la priorità sui gruppi dinamici.

Rimozione di un oggetto da un gruppo di oggetti statico

Usa il comando RemoveThingFromThingGroup per rimuovere un oggetto da un gruppo:


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

Il comando RemoveThingFromThingGroup non produce output.

Elenco di oggetti in un gruppo di oggetti

Utilizza il comando ListThingsInThingGroup per elencare gli oggetti che appartengono a un gruppo:


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

Il comando ListThingsInThingGroup restituisce un elenco degli oggetti nel gruppo specificato:


{
    "things":[
        "TestThingA"
    ]
}

Il parametro --recursive permette di elencare gli oggetti appartenenti a un gruppo e quelli nei relativi gruppi figlio:


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


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

Nota

Questa operazione è consistente finale. In altre parole, le modifiche al gruppo di cose potrebbero non essere riflesse contemporaneamente.

Visualizzazione dell'elenco di gruppi di oggetti

Puoi usare il comando ListThingGroups per elencare i gruppi di oggetti del tuo account:


$ aws iot list-thing-groups

Il ListThingGroups comando restituisce un elenco dei gruppi di cose presenti in Account 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"
        }
    ]
}

Usa i filtri facoltativi per elencare i gruppi con un determinato gruppo padre (--parent-group) o i gruppi il cui nome inizia con un determinato prefisso (--name-prefix-filter). Il parametro --recursive permette di elencare anche tutti i gruppi figlio e non solo i gruppi figlio diretti di un gruppo di oggetti:


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

In questo caso, il ListThingGroups comando restituisce un elenco dei gruppi figli diretti del gruppo di cose definito in Account AWS:


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

Utilizza il parametro --recursive con il comando ListThingGroups per elencare tutti i gruppi figlio di un gruppo di oggetti, non solo i figli diretti:


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

Il comando ListThingGroups restituisce un elenco di tutti i gruppi figlio del gruppo di oggetti:


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

Nota

Questa operazione è consistente finale. In altre parole, le modifiche al gruppo di cose potrebbero non essere riflesse contemporaneamente.

Elenco dei gruppi per un oggetto

Puoi utilizzare il comando ListThingGroupsForThing per elencare i gruppi diretti a cui appartiene l'oggetto:


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

Il comando ListThingGroupsForThing restituisce un elenco dei gruppi di oggetti diretti a cui l'oggetto appartiene:


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

Aggiornamento di un gruppo di oggetti statico

Usa il comando UpdateThingGroup per aggiornare gli attributi di un gruppo di oggetti statico:


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

Il comando UpdateThingGroup restituisce una risposta che contiene il numero di versione del gruppo dopo l'aggiornamento:


{
    "version": 4
}

Nota

Il numero di attributi che un oggetto può avere è limitato.

Eliminazione di un gruppo di oggetti

Per eliminare un gruppo di oggetti, usa il comando DeleteThingGroup:


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

Il comando DeleteThingGroup non produce output.

Importante

Se tenti di eliminare un gruppo di oggetti con gruppi di oggetti figlio, viene generato un errore:


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

Prima di eliminare il gruppo, eliminate prima tutti i gruppi di figli.

È possibile eliminare un gruppo con oggetti figlio, ma le autorizzazioni concesse agli oggetti in virtù dell'appartenenza al gruppo non sono più valide. Prima di eliminare un gruppo a cui è collegata una policy, controlla attentamente che la rimozione delle autorizzazioni non comprometta il corretto funzionamento degli oggetti nel gruppo. Inoltre, i comandi che mostrano a quali gruppi appartiene un oggetto (ad esempio,ListGroupsForThing) potrebbero continuare a mostrare il gruppo mentre i record nel cloud vengono aggiornati.

Collegamento di una policy a un gruppo di oggetti statico

Usa il comando AttachPolicy per collegare una policy a un gruppo di oggetti statico e, di conseguenza, a tutti gli oggetti presenti nel gruppo e agli oggetti nei relativi gruppi figlio:


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

Il comando AttachPolicy non produce output

Importante

È possibile collegare un numero massimo di due policy per un gruppo.

Nota

Non è consigliabile utilizzare informazioni di identificazione personale nei nomi delle policy.

Il parametro --target può essere l'ARN di un gruppo di oggetti (come indicato sopra), l'ARN di un certificato o un'identità Amazon Cognito. Per ulteriori informazioni su policy, certificati e autenticazione, consulta Autenticazione.

Per ulteriori informazioni, consulta policy AWS IoT Core.

Scollegamento di una policy da un gruppo di oggetti statico

Usa il comando DetachPolicy per scollegare una policy da un gruppo di oggetti e, di conseguenza, da tutti gli oggetti presenti nel gruppo e gli oggetti nei relativi gruppi figlio:


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

Il comando DetachPolicy non produce output.

Elenco di policy collegate a un gruppo di oggetti statico

Usa il comando ListAttachedPolicies per elencare le policy collegate a un gruppo di oggetti statico:


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

Il parametro --target può essere l'ARN di un gruppo di oggetti (come indicato sopra), l'ARN di un certificato o un'identità Amazon Cognito.

Aggiungi il parametro opzionale --recursive per includere tutte le policy collegate ai gruppi padre del gruppo.

Il comando ListAttachedPolicies restituisce un elenco di policy:


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

Visualizzazione dell'elenco di gruppi per una policy

Usa il comando ListTargetsForPolicy per elencare i target, inclusi i gruppi, a cui una policy è collegata:


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

Aggiungi il parametro opzionale --page-size number per specificare il numero massimo di risultati da restituire per ogni query e il parametro --marker string nelle chiamate successive per recuperare il set di risultati successivo, se presente.

Il comando ListTargetsForPolicy restituisce un elenco di target e il token da usare per recuperare ulteriori risultati:


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

Recupero delle policy valide per un oggetto

Usa il comando GetEffectivePolicies per elencare le policy valide per un oggetto, incluse le policy collegate ai gruppi a cui l'oggetto appartiene, indipendentemente dal fatto che il gruppo sia un padre diretto o un predecessore indiretto:


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

Usa il parametro --principal per specificare l'ARN del certificato collegato all'oggetto. Se usi l'autenticazione dell'identità di Amazon Cognito, utilizza il parametro --cognito-identity-pool-id e, facoltativamente, aggiungi il parametro --principal per specificare un'identità di Amazon Cognito. Se specifichi solo --cognito-identity-pool-id, vengono restituite le policy associate al ruolo del pool di identità per gli utenti non autenticati. Se usi entrambi i parametri, vengono restituite le policy associate al ruolo del pool di identità per gli utenti autenticati.

Il parametro --thing-name è opzionale e può essere usato al posto del parametro --principal. Quando viene usato, vengono restituite le policy collegate a qualsiasi gruppo a cui l'oggetto appartiene e le policy collegate a qualsiasi gruppo padre di questi gruppi (fino al gruppo root della gerarchia).

Il comando GetEffectivePolicies restituisce un elenco di policy:


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

Test dell'autorizzazione per le operazioni MQTT

Usa il comando TestAuthorization per verificare se un'operazione MQTT (Publish, Subscribe) è permessa per un oggetto:


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

Usa il parametro --principal per specificare l'ARN del certificato collegato all'oggetto. Se utilizzi l'autenticazione dell'identità di Amazon Cognito, specifica un'identità di Cognito come --principal oppure utilizza il parametro --cognito-identity-pool-id o entrambe le cose. Se specifichi solo --cognito-identity-pool-id, vengono considerate le policy associate al ruolo del pool di identità per gli utenti non autenticati. Se usi entrambi i parametri, vengono considerate le policy associate al ruolo del pool di identità per gli utenti autenticati.

Specifica una o più operazioni MQTT da testare elencando i set di risorse e i tipi di operazioni dopo il parametro --auth-infos. Il campo actionType deve contenere "PUBLISH", "SUBSCRIBE", "RECEIVE" o "CONNECT". Il campo resources deve contenere un elenco di ARN di risorse. Per ulteriori informazioni, consulta AWS IoT Core politiche.

È possibile testare gli effetti dell'aggiunta di policy specificandole con il parametro --policy-names-to-add. In alternativa, è possibile testare gli effetti della rimozione di policy con il parametro --policy-names-to-skip.

Puoi usare il parametro opzionale --client-id per affinare ulteriormente i risultati.

Il comando TestAuthorization restituisce i dettagli delle operazioni permesse o non permesse per ogni set di query --auth-infos specificato:


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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Tipi di oggetti

Gruppo di oggetti dinamici