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

# Device Shadow REST API
<a name="device-shadow-rest-api"></a>

影子會公開下列 URI 以更新狀態資訊：

```
https://account-specific-prefix-ats.iot.region.amazonaws.com/things/thingName/shadow
```

端點專屬於您的 AWS 帳戶。如要尋找您的端點，您可以：
+ 使用來自 AWS CLI的 [describe-endpoint](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-endpoint.html) 命令。
+ 使用 AWS IoT 主控台設定。於 **Settings** (設定) 中，端點會列於 **Custom endpoint** (自訂端點) 之下
+ 使用 AWS IoT 主控台物件詳細資訊頁面。在主控台中：

  1. 開啟 **Manage** (管理)，在 **Manage** (管理) 之下，選擇 **Things** (物件)。

  1. 於物件清單中，選擇要取得端點 URI 的物件。

  1. 選擇 **Device Shadows** 索引標籤，選擇您的影子。您可在 **Device Shadow 詳細資訊**頁面的 **Device Shadow URL** 區段中檢視端點 URI。

端點格式如下：

```
identifier.iot.region.amazonaws.com
```

影子 REST API 會遵循相同的 HTTPS 通訊協定/連接埠映射，如 [裝置通訊協定](protocols.md) 中所述。

**注意**  
若要使用 API，您必須使用 `iotdevicegateway` 作為身分驗證的服務名稱。如需詳細資訊，請參閱 [IoTDataPlane](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-iot-data-plane/classes/iotdataplane.html)。

**Topics**
+ [GetThingShadow](#API_GetThingShadow)
+ [UpdateThingShadow](#API_UpdateThingShadow)
+ [DeleteThingShadow](#API_DeleteThingShadow)
+ [ListNamedShadowsForThing](#API_ListNamedShadowsForThing)

您也可以透過提供 `name=shadowName` 作為 API 的查詢參數的一部分，使用 API 建立已命名的影子。

## GetThingShadow
<a name="API_GetThingShadow"></a>

取得特定物件的影子。

回應狀態文件包括 `desired` 和 `reported` 狀態之間的差量。

**請求**  
此請求包括標準 HTTP 標頭加上以下 URI：

```
HTTP GET https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```

未命名 (典型) 影子不需要 `name` 查詢參數。

**回應**  
成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

```
HTTP 200
Response Body: response state document
```

如需詳細資訊，請參閱[回應狀態文件範例](device-shadow-document.md#device-shadow-example-response-json)。

**Authorization**  
擷取影子需要一項允許呼叫者可執行 `iot:GetThingShadow` 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者擷取裝置影子的政策範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:GetThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## UpdateThingShadow
<a name="API_UpdateThingShadow"></a>

更新指定之物件的影子。

更新僅會影響請求狀態文件中所指定的欄位。值為 `null` 的任何欄位，皆會從裝置影子中移除。

**請求**  
此請求包含標準 HTTP 標頭和內文加上以下 URI 與本文：

```
HTTP POST https://endpoint/things/thingName/shadow?name=shadowName
Request body: request state document
```

未命名 (典型) 影子不需要 `name` 查詢參數。

如需詳細資訊，請參閱[請求狀態文件範例](device-shadow-document.md#device-shadow-example-request-json)。

**回應**  
成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

```
HTTP 200
Response body: response state document
```

如需詳細資訊，請參閱[回應狀態文件範例](device-shadow-document.md#device-shadow-example-response-json)。

**Authorization**  
更新影子需要一項允許呼叫者執行 `iot:UpdateThingShadow` 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者更新裝置影子的政策範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:UpdateThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## DeleteThingShadow
<a name="API_DeleteThingShadow"></a>

刪除特定物件的影子。

**請求**  
此請求包括標準 HTTP 標頭加上以下 URI：

```
HTTP DELETE https://endpoint/things/thingName/shadow?name=shadowName
Request body: (none)
```

未命名 (典型) 影子不需要 `name` 查詢參數。

**回應**  
成功時，回應會包括標準 HTTP 標頭以及下列程式碼與本文：

```
HTTP 200
Response body: Empty response state document
```

請注意，刪除影子並不會將其版本號碼重設為 0。

**Authorization**  
刪除裝置影子需要一項允許呼叫者執行 `iot:DeleteThingShadow` 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

下列為允許呼叫者刪除裝置影子的政策範例：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:DeleteThingShadow",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```

## ListNamedShadowsForThing
<a name="API_ListNamedShadowsForThing"></a>

列出指定物件的影子。

**請求**  
此請求包括標準 HTTP 標頭加上以下 URI：

```
HTTP GET /api/things/shadow/ListNamedShadowsForThing/thingName?nextToken=nextToken&pageSize=pageSize
Request body: (none)
```

nextToken  
用來擷取下一組結果的符記。  
此值會在分頁結果上傳回，並在傳回下一頁的呼叫中使用。

pageSize  
影子名稱在每個呼叫中傳回的數目。另請參閱`nextToken`。

thingName  
要列出命名影子的物件的名稱。

**回應**  
成功時，回應會包括標準 HTTP 標頭以及下列回應程式碼與 [影子名稱清單回應文件](device-shadow-document.md#device-shadow-list-json)。

**注意**  
未命名 (傳統) 影子不會出現在此清單中。如果您只有一個經典的影子，或者您指定的 `thingName` 不存在，則回應將是一個空清單。

```
HTTP 200
Response body: Shadow name list document
```

**Authorization**  
列出裝置影子需要一項允許呼叫者執行 `iot:ListNamedShadowsForThing` 動作的政策。Device Shadow 服務接受兩種形式的身分驗證：使用 IAM 憑證的 Signature 第 4 版，或使用用戶端憑證的 TLS 交互身分驗證。

以下為允許呼叫者更新物件已命名影子的範例政策：

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "iot:ListNamedShadowsForThing",
            "Resource": [
                "arn:aws:iot:us-east-1:123456789012:thing/thing"
            ]
        }
    ]
}
```