靜態物件群組 - AWS IoT Core

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

靜態物件群組

物件群組可讓您將多個物件分類成群組以方便同時管理。靜態物件群組包含一組使用主控台、 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動作 (PublishSubscribe):

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