本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 用戶端裝置身分驗證
用戶端裝置驗證元件 (`aws.greengrass.clientdevices.Auth`) 會驗證用戶端裝置，並授權用戶端裝置動作。
**注意**
用戶端裝置是連線至 Greengrass 核心裝置的本機 IoT 裝置，用於傳送 MQTT 訊息和要處理的資料。如需詳細資訊，請參閱[與本機 IoT 裝置互動](interact-with-local-iot-devices.md)。
**Topics**
+ [版本](#client-device-auth-component-versions)
+ [類型](#client-device-auth-component-type)
+ [作業系統](#client-device-auth-component-os-support)
+ [要求](#client-device-auth-component-requirements)
+ [相依性](#client-device-auth-component-dependencies)
+ [Configuration](#client-device-auth-component-configuration)
+ [本機日誌檔案](#client-device-auth-component-log-file)
+ [變更記錄](#client-device-auth-component-changelog)
## 版本
**注意**
用戶端裝置驗證 2.3.0 版已停止。我們強烈建議您升級至用戶端裝置驗證版本 2.3.1 或更新版本。
此元件具有下列版本：
+ 2.5.x
+ 2.4.x 版本
+ 2.3.x 版本
+ 2.2.x 版本
+ 2.1.x
+ 2.0.x
## 類型
此元件是外掛程式元件 (`aws.greengrass.plugin`)。[Greengrass 核心](greengrass-nucleus-component.md)會在與核心相同的 Java 虛擬機器 (JVM) 中執行此元件。當您在核心裝置上變更此元件的版本時，核心會重新啟動。
此元件使用與 Greengrass 核相同的日誌檔案。如需詳細資訊，請參閱[監控 AWS IoT Greengrass 日誌](monitor-logs.md)。
如需詳細資訊，請參閱[元件類型](develop-greengrass-components.md#component-types)。
## 作業系統
此元件可以安裝在執行下列作業系統的核心裝置上：
+ Linux
+ Windows
## 要求
此元件有下列需求：
+ [Greengrass 服務角色](greengrass-service-role.md)必須與您的 相關聯， AWS 帳戶 並允許 `iot:DescribeCertificate`許可。
+ 核心裝置的 AWS IoT 政策必須允許下列許可：
+ `greengrass:GetConnectivityInfo`，其中資源包含執行此元件之核心裝置的 ARN
+ `greengrass:VerifyClientDeviceIoTCertificateAssociation`，其中資源包含連接至核心裝置之每個用戶端裝置的 Amazon Resource Name (ARN)
+ `greengrass:VerifyClientDeviceIdentity`
+ `greengrass:PutCertificateAuthorities`
+ `iot:Publish`，其中資源包含下列 MQTT 主題的 ARN：
+ `$aws/things/coreDeviceThingName*-gci/shadow/get`
+ `iot:Subscribe`，其中資源包含下列 MQTT 主題篩選條件的 ARNs：
+ `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
+ `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`
+ `iot:Receive`，其中資源包含下列 MQTT 主題ARNs：
+ `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
+ `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`
如需詳細資訊，請參閱[AWS IoT 資料平面操作的 政策](device-auth.md#iot-policies)及[支援用戶端裝置的最低 AWS IoT 政策](device-auth.md#client-device-support-minimal-iot-policy)。
+ （選用） 若要使用離線身分驗證，服務使用的 AWS Identity and Access Management AWS IoT Greengrass (IAM) 角色必須包含下列許可：
+ `greengrass:ListClientDevicesAssociatedWithCoreDevice` 讓核心裝置列出用戶端以進行離線身分驗證。
+ 用戶端裝置身分驗證元件支援在 VPC 中執行。若要在 VPC 中部署此元件，需要下列項目。
+ 用戶端裝置身分驗證元件必須連線至 AWS IoT data AWS IoT 、 登入資料和 Amazon S3。
### 端點和連接埠
除了基本操作所需的端點和連接埠之外，此元件還必須能夠對下列端點和連接埠執行傳出請求。如需詳細資訊，請參閱[允許透過代理或防火牆的裝置流量](allow-device-traffic.md)。
| Endpoint | 連線埠 | 必要 | 說明 |
| --- | --- | --- | --- |
| `iot.region.amazonaws.com` | 443 | 是 | 用來取得 AWS IoT 物件憑證的相關資訊。 |
## 相依性
當您部署元件時， AWS IoT Greengrass 也會部署其相依性的相容版本。這表示您必須符合元件及其所有相依性的要求，才能成功部署元件。本節列出此元件[發行版本的](#client-device-auth-component-changelog)相依性，以及為每個相依性定義元件版本的語意版本限制。您也可以在 [AWS IoT Greengrass 主控台](https://console.aws.amazon.com//greengrass)中檢視每個版本元件的相依性。在元件詳細資訊頁面上，尋找**相依性**清單。
------
#### [ 2.5.5 ]
下表列出此元件 2.5.5 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.17.0 | 軟式 |
------
#### [ 2.5.4 ]
下表列出此元件 2.5.4 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.16.0 | 軟式 |
------
#### [ 2.5.2 – 2.5.3 ]
下表列出此元件 2.5.2 和 2.5.3 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.15.0 | 軟式 |
------
#### [ 2.5.1 ]
下表列出此元件 2.5.1 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.14.0 | 軟式 |
------
#### [ 2.4.4 - 2.5.0 ]
下表列出此元件 2.4.4 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.13.0 | 軟式 |
------
#### [ 2.4.3 ]
下表列出此元件 2.4.3 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.12.0 | 軟式 |
------
#### [ 2.4.1 and 2.4.2 ]
下表列出此元件 2.4.1 和 2.4.2 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.11.0 | 軟式 |
------
#### [ 2.3.0 – 2.4.0 ]
下表列出此元件 2.3.0 至 2.4.0 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | 軟式 |
------
#### [ 2.3.0 ]
下表列出此元件 2.3.0 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | 軟式 |
------
#### [ 2.2.3 ]
下表列出此元件 2.2.3 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <=2.9.0 | 軟式 |
------
#### [ 2.2.2 ]
下表列出此元件 2.2.2 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <=2.8.0 | 軟式 |
------
#### [ 2.2.1 ]
下表列出此元件 2.2.1 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.8.0 | 軟式 |
------
#### [ 2.2.0 ]
下表列出此元件 2.2.0 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.6.0 <2.7.0 | 軟式 |
------
#### [ 2.1.0 ]
下表列出此元件 2.1.0 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.2.0 <2.7.0 | 軟式 |
------
#### [ 2.0.4 ]
下表列出此元件 2.0.4 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.2.0 <2.6.0 | 軟式 |
------
#### [ 2.0.2 and 2.0.3 ]
下表列出此元件 2.0.2 和 2.0.3 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.2.0 <2.5.0 | 軟式 |
------
#### [ 2.0.1 ]
下表列出此元件 2.0.1 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.2.0 <2.4.0 | 軟式 |
------
#### [ 2.0.0 ]
下表列出此元件 2.0.0 版的相依性。
| 相依性 | 相容版本 | 相依性類型 |
| --- | --- | --- |
| [Greengrass 核](greengrass-nucleus-component.md) | >=2.2.0 <2.3.0 | 軟式 |
------
如需元件相依性的詳細資訊，請參閱[元件配方參考](component-recipe-reference.md#recipe-reference-component-dependencies)。
## Configuration
此元件提供下列組態參數，您可以在部署元件時自訂這些參數。
**注意**
在向本機 MQTT 代理程式提出用戶端訂閱請求時，會評估訂閱許可。如果用戶端的現有訂閱許可遭到撤銷，用戶端將無法再訂閱主題。不過，它會繼續接收來自任何先前訂閱主題的訊息。為了防止這種行為，應在撤銷訂閱許可以強制重新授權用戶端之後重新啟動本機 MQTT 代理程式。
對於 MQTT 5 代理程式 (EMQX) 元件，請更新`restartIdentifier`組態以重新啟動 MQTT 5 代理程式。
對於 MQTT 3.1.1 代理程式 (Moquette) 元件，當伺服器憑證變更強制用戶端重新授權時，預設會每週重新啟動。您可以變更核心裝置的連線資訊 (IP 地址） 或進行部署以移除代理程式元件，然後稍後再次部署，強制重新啟動。
------
#### [ v2.5.0 – 2.5.4 ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義*用戶端裝置授權政策*，以指定每個裝置群組的許可。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則至少包含一個*選擇規則子句*，這是單一表達式查詢，可以符合用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選擇規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱的開頭和結尾使用此萬用字元，來比對名稱開頭或結尾為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱結尾為 的用戶端裝置`MyClientDevice`。
```
thingName: *MyClientDevice
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源不支援 MQTT 主題萬用字元。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以在資源變數內的任何位置指定`*`萬用字元，以允許存取所有資源。例如，您可以指定 **mqtt:topic:my\$1** 以允許存取符合該輸入的資源。
支援下列資源變數：
+ `mqtt:topic:${iot:Connection.Thing.ThingName}`
這會解析為正在評估政策之 AWS IoT Core 登錄檔中的物件名稱。 AWS IoT Core 會使用裝置在驗證時提供的憑證來判斷要使用哪些物件來驗證連線。本政策變數僅在裝置透過 MQTT 或 MQTT over WebSocket 通訊協定進行連線時可用。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線並重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，以改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
`certificateAuthority`
（選用） 憑證授權單位組態選項，可將核心裝置中繼授權單位取代為您自己的中繼憑證授權單位。
如果您使用自訂憑證授權機構 (CA) 設定 Greengrass 核心裝置，並使用相同的 CA 發出用戶端裝置憑證，Greengrass 會略過用戶端裝置 MQTT 操作的授權政策檢查。用戶端裝置身分驗證元件會使用其設定為使用的 CA 簽署的憑證，完全信任用戶端。
若要在使用自訂 CA 時限制此行為，請使用不同的 CA 或中繼 CA 建立和簽署用戶端裝置，然後調整 `certificateUri`和 `certificateChainUri` 欄位以指向正確的中繼 CA。
此物件包含下列資訊。
certificateUri
憑證的位置。它可以是檔案系統 URI 或指向存放在硬體安全模組中的憑證的 URI。
`certificateChainUri`
核心裝置 CA 的憑證鏈位置。這應該是返回根 CA 的完整憑證鏈。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證鏈。
`privateKeyUri`
核心裝置私有金鑰的位置。這可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證私有金鑰。
`security`
（選用） 此核心裝置的安全組態選項。此物件包含下列資訊。
`clientDeviceTrustDurationMinutes`
在使用核心裝置重新驗證之前，用戶端裝置的身分驗證資訊可信任的持續時間，以分鐘為單位。預設值為 1.
`metrics`
（選用） 此核心裝置的指標選項。只有在用戶端裝置驗證發生錯誤時，才會顯示錯誤指標。此物件包含下列資訊：
`disableMetrics`
如果 `disableMetrics` 欄位設定為 `true`，則用戶端裝置身分驗證不會收集指標。
預設：`false`
`aggregatePeriodSeconds`
以秒為單位的彙總期間，決定用戶端裝置身分驗證彙總指標並將其傳送至遙測代理程式的頻率。這不會變更指標發佈的頻率，因為遙測代理器仍會每天發佈一次。
預設：`3600`
startupTimeoutSeconds
（選用） 元件啟動的秒數上限。`ERRORED` 如果元件超過此逾時，元件的狀態會變更為 。
預設：`120`
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 的用戶端裝置`MyClientDevice`在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用物件名稱政策）**
下列範例組態可讓用戶端裝置在以用戶端裝置物件名稱開頭並以字串 結尾的主題上發佈`topic`。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"myThing": {
"selectionRule": "thingName: *",
"policyName": "MyThingNamePolicy"
}
},
"policies": {
"MyThingNamePolicy": {
"policyStatement": {
"statementDescription": "mqtt publish",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:${iot:Connection.Thing.ThingName}/*/topic"
]
}
}
}
}
}
```
------
#### [ v2.4.5 ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義指定每個裝置群組許可的*用戶端裝置授權政策*。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則至少包含一個*選擇規則子句*，這是單一表達式查詢，可以符合用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱的開頭和結尾使用此萬用字元，來比對名稱開頭或結尾為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱以 結尾的用戶端裝置`MyClientDevice`。
```
thingName: *MyClientDevice
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
此政策中允許 操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線和重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，以改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
`certificateAuthority`
（選用） 憑證授權單位組態選項，可將核心裝置中繼授權單位取代為您自己的中繼憑證授權單位。
如果您使用自訂憑證授權機構 (CA) 設定 Greengrass 核心裝置，並使用相同的 CA 發出用戶端裝置憑證，Greengrass 會略過用戶端裝置 MQTT 操作的授權政策檢查。用戶端裝置身分驗證元件會使用其設定為使用的 CA 簽署的憑證，完全信任用戶端。
若要在使用自訂 CA 時限制此行為，請使用不同的 CA 或中繼 CA 建立和簽署用戶端裝置，然後調整 `certificateUri`和 `certificateChainUri` 欄位以指向正確的中繼 CA。
此物件包含下列資訊。
certificateUri
憑證的位置。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證。
`certificateChainUri`
核心裝置 CA 的憑證鏈位置。這應該是返回根 CA 的完整憑證鏈。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證鏈。
`privateKeyUri`
核心裝置私有金鑰的位置。這可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證私有金鑰。
`security`
（選用） 此核心裝置的安全組態選項。此物件包含下列資訊。
`clientDeviceTrustDurationMinutes`
在使用核心裝置重新驗證之前，用戶端裝置的身分驗證資訊可信任的持續時間，以分鐘為單位。預設值為 1.
`metrics`
（選用） 此核心裝置的指標選項。只有在用戶端裝置驗證發生錯誤時，才會顯示錯誤指標。此物件包含下列資訊：
`disableMetrics`
如果 `disableMetrics` 欄位設定為 `true`，則用戶端裝置身分驗證不會收集指標。
預設：`false`
`aggregatePeriodSeconds`
以秒為單位的彙總期間，決定用戶端裝置身分驗證彙總指標並將其傳送至遙測代理程式的頻率。這不會變更指標發佈的頻率，因為遙測代理程式仍會每天發佈一次。
預設：`3600`
startupTimeoutSeconds
（選用） 元件啟動的時間上限，以秒為單位。`ERRORED` 如果元件超過此逾時，元件的狀態會變更為 。
預設：`120`
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 `MyClientDevice`的用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.4.2 - v2.4.4 ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義*用戶端裝置授權政策*，以指定每個裝置群組的許可。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則都包含至少一個*選擇規則子句*，這是單一表達式查詢，可以比對用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線並重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，以改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
`certificateAuthority`
（選用） 憑證授權單位組態選項，可將核心裝置中繼授權單位取代為您自己的中繼憑證授權單位。
如果您使用自訂憑證授權機構 (CA) 設定 Greengrass 核心裝置，並使用相同的 CA 發出用戶端裝置憑證，Greengrass 會略過用戶端裝置 MQTT 操作的授權政策檢查。用戶端裝置身分驗證元件會使用其設定為使用的 CA 簽署的憑證，完全信任用戶端。
若要在使用自訂 CA 時限制此行為，請使用不同的 CA 或中繼 CA 建立和簽署用戶端裝置，然後調整 `certificateUri`和 `certificateChainUri` 欄位以指向正確的中繼 CA。
此物件包含下列資訊。
certificateUri
憑證的位置。它可以是檔案系統 URI 或指向存放在硬體安全模組中的憑證的 URI。
`certificateChainUri`
核心裝置 CA 的憑證鏈位置。這應該是返回根 CA 的完整憑證鏈。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證鏈。
`privateKeyUri`
核心裝置私有金鑰的位置。這可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證私有金鑰。
`security`
（選用） 此核心裝置的安全組態選項。此物件包含下列資訊。
`clientDeviceTrustDurationMinutes`
在使用核心裝置重新驗證之前，用戶端裝置的身分驗證資訊可信任的持續時間，以分鐘為單位。預設值為 1.
`metrics`
（選用） 此核心裝置的指標選項。只有在用戶端裝置驗證發生錯誤時，才會顯示錯誤指標。此物件包含下列資訊：
`disableMetrics`
如果 `disableMetrics` 欄位設定為 `true`，則用戶端裝置身分驗證不會收集指標。
預設：`false`
`aggregatePeriodSeconds`
以秒為單位的彙總期間，決定用戶端裝置身分驗證彙總指標並將其傳送至遙測代理程式的頻率。這不會變更指標發佈的頻率，因為遙測代理器仍會每天發佈一次。
預設：`3600`
startupTimeoutSeconds
（選用） 元件啟動的時間上限，以秒為單位。`ERRORED` 如果元件超過此逾時，元件的狀態會變更為 。
預設：`120`
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 的用戶端裝置`MyClientDevice`在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.4.0 - v2.4.1 ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義*用戶端裝置授權政策*，以指定每個裝置群組的許可。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則至少包含一個*選擇規則子句*，這是單一表達式查詢，可以比對用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線並重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
`certificateAuthority`
（選用） 憑證授權機構組態選項，可將核心裝置中繼授權機構取代為您自己的中繼憑證授權機構。此物件包含下列資訊。
此物件包含下列資訊：
certificateUri
憑證的位置。它可以是檔案系統 URI 或指向存放在硬體安全模組中的憑證的 URI。
`certificateChainUri`
核心裝置 CA 的憑證鏈位置。這應該是返回根 CA 的完整憑證鏈。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證鏈。
`privateKeyUri`
核心裝置私有金鑰的位置。這可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證私有金鑰。
`security`
（選用） 此核心裝置的安全組態選項。此物件包含下列資訊。
`clientDeviceTrustDurationMinutes`
在使用核心裝置重新驗證之前，用戶端裝置的身分驗證資訊可信任的持續時間，以分鐘為單位。預設值為 1.
`metrics`
（選用） 此核心裝置的指標選項。只有在用戶端裝置驗證發生錯誤時，才會顯示錯誤指標。此物件包含下列資訊：
`disableMetrics`
如果 `disableMetrics` 欄位設定為 `true`，則用戶端裝置身分驗證不會收集指標。
預設：`false`
`aggregatePeriodSeconds`
以秒為單位的彙總期間，決定用戶端裝置身分驗證彙總指標並將其傳送至遙測代理程式的頻率。這不會變更指標發佈的頻率，因為遙測代理器仍會每天發佈一次。
預設：`3600`
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 的用戶端裝置`MyClientDevice`在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.3.x ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義*用戶端裝置授權政策*，以指定每個裝置群組的許可。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則都包含至少一個*選擇規則子句*，這是單一表達式查詢，可以比對用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線並重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
`certificateAuthority`
（選用） 憑證授權機構組態選項，可將核心裝置中繼授權機構取代為您自己的中繼憑證授權機構。此物件包含下列資訊。
certificateUri
憑證的位置。它可以是檔案系統 URI 或指向存放在硬體安全模組中的憑證的 URI。
`certificateChainUri`
核心裝置 CA 的憑證鏈位置。這應該是返回根 CA 的完整憑證鏈。它可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證鏈。
`privateKeyUri`
核心裝置私有金鑰的位置。這可以是檔案系統 URI 或 URI，指向存放在硬體安全模組中的憑證私有金鑰。
`security`
（選用） 此核心裝置的安全組態選項。此物件包含下列資訊。
`clientDeviceTrustDurationMinutes`
在需要使用核心裝置重新驗證之前，用戶端裝置的身分驗證資訊可信任的持續時間，以分鐘為單位。預設值為 1.
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 的用戶端裝置`MyClientDevice`在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.2.x ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義指定每個裝置群組許可的*用戶端裝置授權政策*。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則至少包含一個*選擇規則子句*，這是單一表達式查詢，可以比對用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線並重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
`performance`
（選用） 此核心裝置的效能組態選項。此物件包含下列資訊：
`maxActiveAuthTokens`
（選用） 作用中用戶端裝置授權字符的數量上限。您可以增加此數量，讓更多用戶端裝置連接到單一核心裝置，而無需重新驗證它們。
預設：`2500`
`cloudRequestQueueSize`
（選用） 此元件拒絕 AWS 雲端 請求之前佇列的請求數目上限。
預設：`100`
`maxConcurrentCloudRequests`
（選用） 要傳送至 的並行請求數目上限 AWS 雲端。您可以增加此數字，改善連接大量用戶端裝置的核心裝置上的身分驗證效能。
預設：`1`
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 的用戶端裝置`MyClientDevice`在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.1.x ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義*用戶端裝置授權政策*，以指定每個裝置群組的許可。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則至少包含一個*選擇規則子句*，這是單一表達式查詢，可以符合用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
允許此政策中操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
`certificates`
（選用） 此核心裝置的憑證組態選項。此物件包含下列資訊：
`serverCertificateValiditySeconds`
（選用） 本機 MQTT 伺服器憑證過期的時間量 （以秒為單位）。您可以設定此選項來自訂用戶端裝置中斷連線和重新連線至核心裝置的頻率。
此元件會在本機 MQTT 伺服器憑證過期前 24 小時輪換本機 MQTT 伺服器憑證。MQTT 代理程式，例如 [Moquette MQTT 代理程式元件](mqtt-broker-moquette-component.md)，會產生新的憑證並重新啟動。發生這種情況時，所有連接到此核心裝置的用戶端裝置都會中斷連線。用戶端裝置可以在短時間內重新連線至核心裝置。
預設：`604800`(7 天）
最小值：`172800`(2 天）
最大值： `864000` (10 天）
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 `MyClientDevice`的用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
#### [ v2.0.x ]
`deviceGroups`
裝置群組是具有與核心裝置連線和通訊許可的用戶端裝置群組。使用選取規則來識別用戶端裝置的群組，並定義指定每個裝置群組許可的*用戶端裝置授權政策*。
此物件包含下列資訊：
`formatVersion`
此組態物件的格式版本。
您可以從以下選項中選擇：
+ `2021-03-05`
`definitions`
此核心裝置的裝置群組。每個定義都會指定*選擇規則*，以評估用戶端裝置是否為 群組的成員。每個定義也會指定要套用至符合選取規則之用戶端裝置的許可政策。如果用戶端裝置是多個裝置群組的成員，則裝置的許可會包含每個群組的許可政策。
此物件包含下列資訊：
`groupNameKey`
此裝置群組的名稱。將 *groupNameKey* 取代為可協助您識別此裝置群組的名稱。
此物件包含下列資訊：
`selectionRule`
指定哪些用戶端裝置是此裝置群組成員的查詢。當用戶端裝置連線時，核心裝置會評估此選擇規則，以判斷用戶端裝置是否為此裝置群組的成員。如果用戶端裝置是成員，核心裝置會使用此裝置群組的政策來授權用戶端裝置的動作。
每個選擇規則都包含至少一個*選擇規則子句*，這是單一表達式查詢，可以比對用戶端裝置。選擇規則使用與 AWS IoT 機群索引相同的查詢語法。如需選取規則語法的詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的[AWS IoT 機群索引查詢語法](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html)。
使用`*`萬用字元來比對具有一個選取規則子句的多個用戶端裝置。您可以在物件名稱結尾使用此萬用字元，來比對名稱開頭為您所指定字串的用戶端裝置。您也可以使用此萬用字元來比對所有用戶端裝置。
若要選取包含冒號字元 (`:`) 的值，請使用反斜線字元 () 逸出冒號`\\`。在 JSON 等格式中，您必須逸出反斜線字元，以便在冒號字元之前輸入兩個反斜線字元。例如，指定 `thingName: MyTeam\\\\:ClientDevice1` 選取名稱為 的物件`MyTeam:ClientDevice1`。
您可以指定下列選擇器：
+ `thingName` – 用戶端裝置 AWS IoT 物件的名稱。
**Example 範例選取規則**
下列選擇規則符合名稱為 `MyClientDevice1`或 的用戶端裝置`MyClientDevice2`。
```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```
**Example 範例選取規則 （使用萬用字元）**
下列選擇規則符合名稱開頭為 的用戶端裝置`MyClientDevice`。
```
thingName: MyClientDevice*
```
**Example 範例選取規則 （符合所有裝置）**
下列選擇規則符合所有用戶端裝置。
```
thingName: *
```
`policyName`
套用至此裝置群組中用戶端裝置的許可政策。指定您在 `policies` 物件中定義的政策名稱。
`policies`
連接到核心裝置的用戶端裝置的用戶端裝置授權政策。每個授權政策都會指定一組動作，以及用戶端裝置可以執行這些動作的資源。
此物件包含下列資訊：
`policyNameKey`
此授權政策的名稱。將 *policyNameKey* 取代為可協助您識別此授權政策的名稱。您可以使用此政策名稱來定義適用於裝置群組的政策。
此物件包含下列資訊：
`statementNameKey`
此政策陳述式的名稱。將 *statementNameKey* 取代為可協助您識別此政策陳述式的名稱。
此物件包含下列資訊：
`operations`
允許此政策中資源的操作清單。
您可以包含下列任何操作：
+ `mqtt:connect` – 准許連線至核心裝置。用戶端裝置必須具有此許可才能連線至核心裝置。
此操作支援下列資源：
+ `mqtt:clientId:deviceClientId` – 根據用戶端裝置用來連線至核心裝置的 MQTT 代理程式的用戶端 ID 限制存取。將 *deviceClientId* 取代為要使用的用戶端 ID。
+ `mqtt:publish` – 准許將 MQTT 訊息發佈至主題。
此操作支援下列資源：
+ `mqtt:topic:mqttTopic` – 根據用戶端裝置發佈訊息的 MQTT 主題來限制存取。將 *mqttTopic* 取代為要使用的主題。
此資源不支援 MQTT 主題萬用字元。
+ `mqtt:subscribe` – 准許訂閱 MQTT 主題篩選條件以接收訊息。
此操作支援下列資源：
+ `mqtt:topicfilter:mqttTopicFilter` – 根據用戶端裝置可以訂閱訊息的 MQTT 主題來限制存取。將 *mqttTopicFilter* 取代為要使用的主題篩選條件。
此資源支援 `+`和 `#` MQTT 主題萬用字元。如需詳細資訊，請參閱《 *AWS IoT Core 開發人員指南*》中的 [MQTT 主題](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html)。
用戶端裝置可以訂閱您允許的確切主題篩選條件。例如，如果您允許用戶端裝置訂閱 `mqtt:topicfilter:client/+/status` 資源，用戶端裝置可以訂閱 `client/+/status`，但不能訂閱 `client/client1/status`。
您可以指定`*`萬用字元，以允許存取所有動作。
`resources`
此政策中允許 操作的資源清單。指定與此政策中 操作對應的資源。例如，您可以在指定 `mqtt:publish`操作的政策中指定 MQTT 主題資源 (`mqtt:topic:mqttTopic`) 的清單。
您可以指定`*`萬用字元，以允許存取所有資源。您無法使用`*`萬用字元來比對部分資源識別符。例如，您可以指定 **"resources": "\$1"**，但無法指定 **"resources": "mqtt:clientId:\$1"**。
`statementDescription`
（選用） 此政策陳述式的描述。
**Example 範例：組態合併更新 （使用限制性政策）**
下列範例組態指定 ，允許名稱開頭為 `MyClientDevice`的用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyDeviceGroup": {
"selectionRule": "thingName: MyClientDevice*",
"policyName": "MyRestrictivePolicy"
}
},
"policies": {
"MyRestrictivePolicy": {
"AllowConnect": {
"statementDescription": "Allow client devices to connect.",
"operations": [
"mqtt:connect"
],
"resources": [
"*"
]
},
"AllowPublish": {
"statementDescription": "Allow client devices to publish on test/topic.",
"operations": [
"mqtt:publish"
],
"resources": [
"mqtt:topic:test/topic"
]
},
"AllowSubscribe": {
"statementDescription": "Allow client devices to subscribe to test/topic/response.",
"operations": [
"mqtt:subscribe"
],
"resources": [
"mqtt:topicfilter:test/topic/response"
]
}
}
}
}
}
```
**Example 範例：組態合併更新 （使用寬鬆政策）**
下列範例組態指定 ，以允許所有用戶端裝置在所有主題上連線和發佈/訂閱。
```
{
"deviceGroups": {
"formatVersion": "2021-03-05",
"definitions": {
"MyPermissiveDeviceGroup": {
"selectionRule": "thingName: *",
"policyName": "MyPermissivePolicy"
}
},
"policies": {
"MyPermissivePolicy": {
"AllowAll": {
"statementDescription": "Allow client devices to perform all actions.",
"operations": [
"*"
],
"resources": [
"*"
]
}
}
}
}
}
```
------
## 本機日誌檔案
此元件使用與 [Greengrass 核](greengrass-nucleus-component.md)元件相同的日誌檔案。
------
#### [ Linux ]
```
/greengrass/v2/logs/greengrass.log
```
------
#### [ Windows ]
```
C:\greengrass\v2\logs\greengrass.log
```
------
**檢視此元件的日誌**
+ 在核心裝置上執行下列命令，以即時檢視此元件的日誌檔案。將 `/greengrass/v2`或 *C：\$1greengrass\$1v2* 取代為 AWS IoT Greengrass 根資料夾的路徑。
------
#### [ Linux ]
```
sudo tail -f /greengrass/v2/logs/greengrass.log
```
------
#### [ Windows (PowerShell) ]
```
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
```
------
## 變更記錄
下表說明每個版本元件的變更。
| **版本** | **變更** |
| --- | --- |
| 2.5.5 | 針對 Greengrass nucleus 2.16.0 版更新版本。 |
| 2.5.4 | 針對 Greengrass nucleus 2.15.0 版更新版本。 |
| 2.5.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.5.2 | 針對 Greengrass nucleus 2.14.0 版更新版本。 |
| 2.5.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.4.5 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.4.4 | 針對 Greengrass nucleus 2.12.0 版更新版本。 |
| 2.4.3 | 針對 Greengrass nucleus 2.11.0 版更新版本。 |
| 2.4.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.4.1 | 針對 Greengrass nucleus 2.10.0 版更新版本。 |
| 2.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.3.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.3.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.3.0 | 此版本不再可用。此版本的改善功能可在此元件的較新版本中使用。 新功能 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.2.3 | 針對 Greengrass nucleus 2.8.0 版更新版本。 |
| 2.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.2.1 | 針對 Greengrass nucleus 2.7.0 版更新版本。 |
| 2.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.0.4 | 針對 Greengrass nucleus 2.5.0 版更新版本。 |
| 2.0.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/greengrass/v2/developerguide/client-device-auth-component.html) |
| 2.0.2 | 針對 Greengrass nucleus 2.4.0 版更新版本。 |
| 2.0.1 | 針對 Greengrass nucleus 2.3.0 版更新版本。 |
| 2.0.0 | 初始版本。 |