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

靜態物件群組

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

注意

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

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

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

加入選用的 --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 角色對於授權使用者的相關政策。

若要指定一個或多個您想要測試的 MQTT 動作，請列出資源以及執行 --auth-infos 參數後的動作類型。actionType 欄位應包含 "PUBLISH"、"SUBSCRIBE"、"RECEIVE" 或 "CONNECT"。resources 欄位應包含一份資源 ARN 的清單。如需詳細資訊，請參閱 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 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

物件類型

動態物件群組