建立靜態物件群組描述物件群組新增一個物件到一個靜態的物件群組從靜態物件群組中移除一個物件列出物件群組中的物件列出物件群組列出物件的群組更新靜態物件群組刪除物件群組將政策附加到靜態物件群組將政策與靜態物件群組分離列出連線至靜態物件群組的政策列出政策所在的群組為物件取得有效政策 MQTT 測試動作的授權

靜態物件群組

物件群組可讓您將多個物件分類成群組以方便同時管理。靜態物件群組包含一組使用主控台、 CLI或管理的物件API。另一方面，動態物件群組會包含與指定查詢相符的物件。靜態物件群組還可包含其他靜態物件群組，您可建置一個群組階層。您可以將政策連接至父群組，而此政策會被其子群組以及父、子群組內的所有物件繼承。這可讓您輕易控制大量物件的許可。

注意

內容群組政策不允許存取 AWS IoT Greengrass 資料平面操作。若要允許物件存取 AWS IoT Greengrass 資料平面操作，請將許可新增至您附加到物件憑證 AWS IoT 的政策。如需詳細資訊，請參閱《AWS IoT Greengrass 開發人員指南》中的裝置身分驗證和授權。

您可以對靜態物件群組執行下列操作：

建立、描述或刪除群組。
新增物件至一個多個群組。
從群組移除物件。
列出您建立的群組。
列出群組的所有子群組 (直系與旁系的後代)。
列出群組裡的物件，包括其子群組裡的所有物件。
列出群組的所有上階群組 (直系與旁系的父群組)。
新增、刪除或更新群組的屬性。(屬性是您可用於存放群組相關資訊的名稱/值對。)
讓政策與群組連接或分離。
列出連接至群組的政策。
列出物件所繼承的政策 (透過連接至其群組或其父群組的政策)。
設定群組中物件的記錄選項。請參閱設定 AWS IoT 記錄。
建立傳送至群組及其子群組中所有物件並執行的任務。請參閱 AWS IoT 任務。

注意

當物件連接到 AWS IoT Core 政策所連接的靜態物件群組時，物件名稱必須符合用戶端 ID。

以下為靜態物件群組的限制：

一個群組最多只能有一個直系的父群組。
如果群組是另一個群組的子群組，請在建立時指定此選項。
您之後便無法變更群組的父群組，因此請務必在建立群組所包含的任何子群組之前，先規劃群組階層並建立父群組。
物件所屬群組數有限。
在相同的階層內，您無法讓一個物件加入超過一個群組。(亦即，您無法讓物件加入父群組相同的兩個群組。)
您無法重新命名群組。
物件群組名稱無法包含國際字元，例如 û、é 和 ñ。
請勿在物件群組名稱中使用個人識別資訊。物件群組名稱可顯示於未加密的通訊和報告中。

讓政策跟群組連接和分離，可以在許多重要方面強化您的 AWS IoT 操作安全。透過裝置將政策連接至憑證再連接到物件的方式相當耗時，而且在裝置機群中要迅速更新或變更政策也很困難。若政策連接至物件的群組，在輪換物件的憑證時就可以省卻許多步驟。此外，物件變更群組成員資格時，政策就會動態套用至物件，所以每當群組中有裝置變更成員資格，您就不必重新建立一組複雜的許可。

建立靜態物件群組

使用 CreateThingGroup 命令建立動態物件群組：


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

CreateThingGroup 命令會傳回包含靜態物件群組名稱、ID 和的回應ARN：


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

注意

我們不建議在物件群組名稱中使用個人識別資訊。

這個範例是在建立靜態物件群組時，為其指定一個父群組：


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

和之前一樣， CreateThingGroup命令會傳回包含靜態物件群組名稱、ID 和的回應ARN：


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

重要

在建立物件群組階層時，請注意下列限制：

物件群組只能有一個直接的父系群組。
物件群組可以擁有的直接子系群組數量有限。
群組階層的最大深度有限。
物件群組可以擁有的屬性數量有限。(屬性是您可用於存放群組相關資訊的名稱/值對。) 每個屬性名稱和每個值的長度也有限。

描述物件群組

您可以使用 DescribeThingGroup 命令獲得關於物件群組的資訊：


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

DescribeThingGroup 命令會傳回關於指定群組的資訊：


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

新增一個物件到一個靜態的物件群組

您可以使用 AddThingToThingGroup 命令將物件新增至靜態物件群組：


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

AddThingToThingGroup 命令不會產生任何輸出。

重要

一個物件最多可加入 10 個群組。但是在相同的階層內，您無法讓一個物件加入超過一個群組。(亦即，您無法讓物件加入父群組相同的兩個群組。)

如果物件屬於 10 個物件群組，而其中有一或多個群組為動態物件群組，則您可以使用 overrideDynamicGroups 旗標讓靜態群組的優先順序高於動態群組。

從靜態物件群組中移除一個物件

您可以使用 RemoveThingFromThingGroup 命令從群組移除物件：


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

RemoveThingFromThingGroup 命令不會產生任何輸出。

列出物件群組中的物件

您可以使用 ListThingsInThingGroup 命令列出屬於群組的物件：


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

ListThingsInThingGroup 命令會傳回該群組的物件清單：


{
    "things":[
        "TestThingA"
    ]
}

使用 --recursive 參數，您可以列出屬於某個群組及其任一子群組中的物件：


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


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

注意

此操作為最終一致。換句話說，可能不會一次反映物件群組的變更。

列出物件群組

您可以使用 ListThingGroups 命令來列出帳戶的物件群組：


$ aws iot list-thing-groups

ListThingGroups 命令會傳回中物件群組的清單 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"
        }
    ]
}

使用選用的篩選條件列出以特定群組為父群組的群組 (--parent-group) 或是名稱開頭為特定字首 (--name-prefix-filter) 的群組。--recursive 參數可讓您列出所有子群組，不只是物件群組的直系子群組：


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

在此情況下， ListThingGroups命令會傳回中定義之物件群組的直接子群組清單 AWS 帳戶：


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

使用 --recursive 參數與 ListThingGroups 命令來列出物件群組的所有子群組，不只是直系子群組：


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

ListThingGroups 命令會傳回一份清單，列出物件群組的所有子群組：


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

注意

此操作為最終一致。換句話說，可能不會一次反映物件群組的變更。

列出物件的群組

您可以使用 ListThingGroupsForThing 命令列出物件所屬的群組：


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

ListThingGroupsForThing 命令會傳回一份清單，其中會列出此物件所屬的直接物件群組：


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

更新靜態物件群組

您可以使用 UpdateThingGroup 命令更新靜態物件群組的屬性：


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

UpdateThingGroup 命令的回應會包含更新之後的群組版本編號：


{
    "version": 4
}

注意

一個物件可以擁有的屬性數量有限。

刪除物件群組

若要刪除物件群組，請使用 DeleteThingGroup 命令：


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

DeleteThingGroup 命令不會產生任何輸出。

重要

如果您嘗試刪除具有子物件群組的物件群組，就會收到錯誤：


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

刪除群組之前，請先刪除任何子群組。

您可以刪除具有子物件的群組，但由群組成員資格授予物件的任何許可將不再適用。在刪除已連接政策的群組之前，請確認移除這些許可不會使群組中的物件無法正常運作。此外，顯示物件所屬群組（例如 ListGroupsForThing）的命令可能會繼續顯示群組，而雲端中的記錄正在更新。

將政策附加到靜態物件群組

您可以使用 AttachPolicy 命令將政策連線至靜態物件群組，進而連線至該群組及其子群組中的所有物件。


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

AttachPolicy 命令不會產生任何輸出。

重要

您可以附加至群組的政策數上限為兩個。

注意

我們不建議在政策名稱中使用個人識別資訊。

--target 參數可以是物件群組 ARN（如上所述）ARN、憑證或 Amazon Cognito Identity。如需關於政策、憑證與身分驗證的詳細資訊，請參閱身分驗證。

如需詳細資訊，請參閱 AWS IoT Core 政策。

將政策與靜態物件群組分離

您可以使用 DetachPolicy 命令從物件群組分離政策，進而讓政策與該群組及其子群組中的所有物件分離。


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

DetachPolicy 命令不會產生任何輸出。

列出連線至靜態物件群組的政策

您可以使用 ListAttachedPolicies 命令列出連線至群組的政策：


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

--target 參數可以是物件群組 ARN（如上所述）ARN、憑證或 Amazon Cognito 身分。

加入選用的 --recursive 參數，納入與該群組之父群組連接的所有政策。

ListAttachedPolicies 命令會傳回政策清單：


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

列出政策所在的群組

您可以使用 ListTargetsForPolicy 命令列出政策連接的目標，包括任何群組：


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

新增選用的 --page-size number 參數來指定每次查詢所回傳的結果數量上限，並在後續呼叫使用 --marker string 參數以擷取下一組結果。

ListTargetsForPolicy 命令會傳回一份目標清單以及用於擷取更多結果的符記：


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

為物件取得有效政策

您可以使用 GetEffectivePolicies 命令列出物件的有效政策，包括連接至該物件所屬任何群組的政策 (無論此群組是直系的父群組或旁系的上階群組)：


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

使用 --principal 參數來指定附加至物件之憑證ARN的。如果您使用 Amazon Cognito 身分驗證，請使用 --cognito-identity-pool-id 參數並新增選用的 --principal 參數來指定一個 Amazon Cognito 身分。如果您僅指定 --cognito-identity-pool-id，則會傳回該身分集區角色對於未授權使用者的相關政策。如果您兩者都使用，則會傳回該 identity pool 角色對於授權使用者的相關政策。

--thing-name 參數為選用，可用於取代 --principal 參數。若使用此參數，則會傳回連接物件所屬群組的政策，以及連接這些群組之父群組 (最高到階層裡之根群組) 的政策。

GetEffectivePolicies 命令會傳回政策清單：


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

MQTT 測試動作的授權

您可以使用 TestAuthorization命令來測試物件是否允許MQTT動作（Publish、Subscribe）：


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

使用 --principal 參數來指定附加至物件之憑證ARN的。若使用 Amazon Cognito Identity 驗證，請指定一個 Cognito Identity 為 --principal 或使用 --cognito-identity-pool-id 參數，或兩者並用。(如果您僅指定 --cognito-identity-pool-id，則需考量該 identity pool 角色對於未授權使用者的相關政策。如果您兩者都使用，則需考量該 identity pool 角色對於授權使用者的相關政策。

透過列出--auth-infos參數後面的資源和MQTT動作類型集，指定您要測試的一或多個動作。actionType 欄位應包含「PUBLISH」、「SUBSCRIBE」、「RECEIVE」或「CONNECT」。resources 欄位應包含資源的清單ARNs。如需詳細資訊，請參閱 AWS IoT Core 政策。

若要測試新增政策的效果，請為其指定 --policy-names-to-add 參數。若要測試移除政策的效果，請為其指定 --policy-names-to-skip 參數。

您可以使用選用的 --client-id 參數進一步加強結果。

TestAuthorization 命令會傳回您指定的每筆 --auth-infos 查詢所允許或拒絕的動作詳細資訊：


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

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

物件類型

動態物件群組