本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 靜態物件群組
物件群組可讓您將多個物件分類成群組以方便同時管理。靜態物件群組包含一組使用主控台、CLI 或 API 來管理的物件。另一方面，[動態物件群組](dynamic-thing-groups.md)會包含與指定查詢相符的物件。靜態物件群組還可包含其他靜態物件群組，您可建置一個群組階層。您可以將政策連接至父群組，而此政策會被其子群組以及父、子群組內的所有物件繼承。這可讓您輕易控制大量物件的許可。
**注意**
物件群組政策不允許存取 AWS IoT Greengrass 資料平面操作。若要允許物件存取 AWS IoT Greengrass 資料平面操作，請將 許可新增至您連接至物件憑證 AWS IoT 的政策。如需詳細資訊，請參閱《AWS IoT Greengrass 開發人員指南》**中的[裝置身分驗證和授權](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-auth#iot-policies.html)。
您可以對靜態物件群組執行下列操作：
+ 建立、描述或刪除群組。
+ 新增物件至一個多個群組。
+ 從群組移除物件。
+ 列出您建立的群組。
+ 列出群組的所有子群組 (直系與旁系的後代)。
+ 列出群組裡的物件，包括其子群組裡的所有物件。
+ 列出群組的所有上階群組 (直系與旁系的父群組)。
+ 新增、刪除或更新群組的屬性。(屬性是您可用於存放群組相關資訊的名稱/值對。)
+ 讓政策與群組連接或分離。
+ 列出連接至群組的政策。
+ 列出物件所繼承的政策 (透過連接至其群組或其父群組的政策)。
+ 設定群組中物件的記錄選項。請參閱 [設定 AWS IoT 記錄](configure-logging.md)。
+ 建立傳送至群組及其子群組中所有物件並執行的任務。請參閱 [AWS IoT 任務](iot-jobs.md)。
**注意**
當物件連接到 AWS IoT Core 政策所連接的靜態物件群組時，物件名稱必須符合用戶端 ID。
以下為靜態物件群組的限制：
+ 一個群組最多只能有一個直系的父群組。
+ 如果群組是另一個群組的子群組，請在建立時指定此項目。
+ 您之後便無法變更群組的父群組，因此請務必在建立群組所包含的任何子群組之前，先規劃群組階層並建立父群組。
+
物件所屬群組數[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits)。
+ 在相同的階層內，您無法讓一個物件加入超過一個群組。(亦即，您無法讓物件加入父群組相同的兩個群組。)
+ 您無法重新命名群組。
+ 物件群組名稱無法包含國際字元，例如 û、é 和 ñ。
+ 請勿在物件群組名稱中使用個人身分識別資訊。物件群組名稱可顯示於未加密的通訊和報告中。
讓政策跟群組連接和分離，可以在許多重要方面強化您的 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",
}
```
**重要**
在建立物件群組階層時，請注意下列限制：
物件群組只能有一個直接的父系群組。
物件群組可以擁有的直接子系群組數量[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits)。
群組階層的最大深度[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits)。
物件群組可以擁有的屬性數量[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits)。(屬性是您可用於存放群組相關資訊的名稱/值對。) 每個屬性名稱和每個值的長度也[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-group-limits)。
## 描述物件群組
您可以使用 **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 個物件群組，而其中有一或多個群組為動態物件群組，則您可以使用 [https://docs.aws.amazon.com/iot/latest/apireference/API_AddThingToThingGroup.html#iot-AddThingToThingGroup-request-overrideDynamicGroups](https://docs.aws.amazon.com/iot/latest/apireference/API_AddThingToThingGroup.html#iot-AddThingToThingGroup-request-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"
]
}
```
**注意**
此操作為[最終一致](https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf)。換句話說，可能不會一次反映物件群組的變更。
## 列出物件群組
您可以使用 **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"
}
]
}
```
**注意**
此操作為[最終一致](https://web.stanford.edu/class/cs345d-01/rl/eventually-consistent.pdf)。換句話說，可能不會一次反映物件群組的變更。
## 列出物件的群組
您可以使用 **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"
}
]
}
```
您也可以使用內嵌函數 在規則引擎內存取此 API`get_registry_data()`。您可以使用此函數，直接在 AWS IoT 規則內呼叫 和 `DescribeThing` `ListThingGroupsForThing` APIs，根據裝置登錄檔資料啟用即時訊息處理和路由，以動態存取和利用物件登錄檔資訊 （包括屬性、物件類型和群組成員資格）。如需詳細資訊，請參閱[https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-registry_data)。
## 更新靜態物件群組
您可以使用 **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
}
```
**注意**
一個物件可以擁有的屬性數量[有限](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#thing-limits)。
## 刪除物件群組
若要刪除物件群組，請使用 **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。如需關於政策、憑證與身分驗證的詳細資訊，請參閱 [身分驗證](authentication.md)。
如需詳細資訊，請參閱 [AWS IoT Core 政策](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html)。
## 將政策與靜態物件群組分離
您可以使用 **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](https://docs.aws.amazon.com/iot/latest/developerguide/mqtt.html) 動作 (`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 政策](iot-policies.md)。
若要測試新增政策的效果，請為其指定 `--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" ]
}
]
}
```