翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Device Shadow サービスドキュメント
<a name="device-shadow-document"></a>

Device Shadow サービスは JSON 仕様のすべてのルールに準拠します。値、オブジェクト、配列はデバイスのシャドウドキュメントに保存されます。

**Topics**
+ [シャドウドキュメントの例](#device-shadow-document-syntax)
+ [ドキュメントのプロパティ](#document-structure)
+ [delta 状態](#delta-state)
+ [シャドウドキュメントのバージョニング](#versioning)
+ [シャドウドキュメント内のクライアントトークン](#client-token)
+ [空のシャドウドキュメントのプロパティ](#device-shadow-empty-fields)
+ [シャドウドキュメント内の配列値](#device-shadow-arrays)

## シャドウドキュメントの例
<a name="device-shadow-document-syntax"></a><a name="device-shadow-example"></a>

Device Shadow サービスは、[REST API](device-shadow-rest-api.md) または [MQTT パブリッシュ/サブスクライブメッセージ](device-shadow-mqtt.md)を使用する UPDATE、GET、DELETE オペレーションで、以下のドキュメントを使用します。

**Topics**
+ [リクエスト状態ドキュメント](#device-shadow-example-request-json)
+ [レスポンス状態ドキュメント](#device-shadow-example-response-json)
+ [エラーレスポンスドキュメント](#device-shadow-example-error-json)
+ [シャドウ名リストレスポンスドキュメント](#device-shadow-list-json)

### リクエスト状態ドキュメント
<a name="device-shadow-example-request-json"></a>

リクエスト状態ドキュメントの形式は次のとおりです。

```
{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "clientToken": "token",
    "version": version
}
```
+ `state` — 更新は、指定したフィールドにのみ反映されます。通常、同じリクエストで `desired` または `reported` プロパティのいずれかを使用しますが、両方を使用することはありません。
  + `desired` — デバイスで更新がリクエストされた state のプロパティと値。
  + `reported` — デバイスによってレポートされた state のプロパティと値。
+ `clientToken` — 使用する場合は、クライアントトークンによってリクエストとレスポンスを対応付けることができます。
+ `version` — 使用した場合、指定したバージョンが最新バージョンと一致すると、Device Shadow サービスは更新を処理します。

### レスポンス状態ドキュメント
<a name="device-shadow-example-response-json"></a>

レスポンス状態ドキュメントはレスポンスタイプに応じて以下の形式になります。

#### /accepted レスポンス状態ドキュメント
<a name="device-shadow-example-response-json-accepted"></a>

```
{
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}
```

#### /delta レスポンス状態ドキュメント
<a name="device-shadow-example-response-json-delta"></a>

```
{
    "state": {
        "attribute1": integer2,
        "attribute2": "string2",
        ...
        "attributeN": boolean2
    },
    "metadata": {
        "attribute1": {
            "timestamp": timestamp
        },
        "attribute2": {
            "timestamp": timestamp
        },
        ...
        "attributeN": {
            "timestamp": timestamp
        }
    },
    "timestamp": timestamp,
    "clientToken": "token",
    "version": version
}
```

#### /documents レスポンス状態ドキュメント
<a name="device-shadow-example-response-json-documents"></a>

```
{
  "previous" : {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer1,
            "attribute2": "string1",
            ...
            "attributeN": boolean1
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version-1
  },
  "current": {
    "state": {
        "desired": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        },
        "reported": {
            "attribute1": integer2,
            "attribute2": "string2",
            ...
            "attributeN": boolean2
        }
    },
    "metadata": {
        "desired": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        },
        "reported": {
            "attribute1": {
                "timestamp": timestamp
            },
            "attribute2": {
                "timestamp": timestamp
            },
            ...
            "attributeN": {
                "timestamp": timestamp
            }
        }
    },
    "version": version
  },
  "timestamp": timestamp,
  "clientToken": "token"
}
```

#### レスポンス状態ドキュメントのプロパティ
<a name="device-shadow-example-response-json-properties"></a>
+ `previous` — 更新が成功した後、更新前のオブジェクトの `state` が含まれます。
+ `current` — 更新が成功した後、更新後のオブジェクトの `state` が含まれます。
+ `state`
  + `reported` — モノが `reported` セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。
  + `desired` — デバイスが `desired` セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。
+ `metadata` — いつ状態が更新されたかを決定できるように、`desired` および `reported` セクションの属性ごとにタイムスタンプが含まれます。
+ `timestamp` — レスポンスが生成されたエポック日時 AWS IoT。
+ `clientToken` — `/update` トピックに有効な JSON を発行するときにクライアントトークンが使用された場合にのみ存在します。
+ `version` — AWS IoTで共有されるデバイスのシャドウのドキュメントの現在のバージョン。ドキュメントの前バージョンから 1 ずつインクリメントされます。

### エラーレスポンスドキュメント
<a name="device-shadow-example-error-json"></a>

エラーレスポンスドキュメントの形式は次のとおりです。

```
{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}
```
+ `code` — エラーのタイプを示す HTTP レスポンスコード。
+ `message` — 追加の情報を提供するテキストメッセージ。
+ `timestamp` — レスポンスが生成された日時 AWS IoT。このプロパティはすべてのエラーレスポンスドキュメントに存在するわけではありません。
+ `clientToken` — 発行されたメッセージでクライアントトークンが使用された場合にのみ表示されます。

詳細については、「[Device Shadow エラーメッセージ](device-shadow-error-messages.md)」を参照してください。

### シャドウ名リストレスポンスドキュメント
<a name="device-shadow-list-json"></a>

シャドウ名リストレスポンスドキュメントの形式は次のとおりです。

```
{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}
```
+ `results` — シャドウ名の配列。
+ `nextToken` — シーケンス内の次のページを取得するためにページングされたリクエストで使用するトークン値。返すシャドウ名がなくなると、このプロパティは存在しません。
+ `timestamp` — レスポンスが生成された日時 AWS IoT。

## ドキュメントのプロパティ
<a name="document-structure"></a>

デバイスのシャドウドキュメントには、以下のプロパティがあります。

`state`  <a name="state"></a>  
`desired`  <a name="desired"></a>
デバイスの desired 状態。アプリケーションは、ドキュメントのこの部分に書き込んで、デバイスの状態を直接更新できます。そのために、デバイスに接続する必要はありません。  
`reported`  <a name="reported"></a>
デバイスの reported 状態。デバイスはドキュメントのこの部分に書き込んで、デバイスの新しい状態を報告します。アプリは、ドキュメントのこの部分を読み取り、デバイスの last-reported 状態を判断します。

`metadata`  <a name="metadata"></a>
ドキュメントの `state` セクションに保存されたデータに関する情報。この情報には `state` セクション内の属性ごとにタイムスタンプ (エポック時間) が含まれており、いつそれらの属性が更新されたかを決定できます。  
メタデータは、サービスの制限または料金に関連するドキュメントサイズに影響を与えません。詳細については、「[AWS IoT サービス制限](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot)」を参照してください。

`timestamp`  <a name="timestamp"></a>
メッセージがいつ送信されたかを示します AWS IoT。メッセージ内のタイムスタンプと、 `desired` または `reported` セクションの個々の属性のタイムスタンプを使用すると、デバイスに内部クロックがない場合でも、デバイスはプロパティの経過時間を判断できます。

`clientToken`  <a name="clientToken"></a>
デバイスに一意の文字列。MQTT 環境でレスポンスをリクエストに関連付けるために使用されます。

`version`  <a name="version"></a>
ドキュメントのバージョン。ドキュメントが更新されるたびに、このバージョン番号がインクリメントされます。更新されるドキュメントのバージョンが最新になるように使用されます。

詳細については、「[シャドウドキュメントの例](#device-shadow-document-syntax)」を参照してください。

## delta 状態
<a name="delta-state"></a><a name="observing-state-changes"></a>

delta 状態は、`desired` 状態と `reported` 状態の違いを含む virtual 型の状態です。`desired` セクションに含まれるが、`reported` セクションに含まれないフィールドは、差分に含まれます。`reported` セクションに含まれるが、`desired` セクションに含まれないフィールドは、差分に含まれません。差分にはメタデータが含まれ、その値は `desired` フィールドのメタデータに一致します。以下に例を示します。

```
{
  "state": {
    "desired": {
      "color": "RED",
      "state": "STOP"
    },
    "reported": {
      "color": "GREEN",
      "engine": "ON"
    },
    "delta": {
      "color": "RED",
      "state": "STOP"
    }
  },
  "metadata": {
    "desired": {
      "color": {
        "timestamp": 12345
      },
      "state": {
        "timestamp": 12345
      }
      },
      "reported": {
        "color": {
          "timestamp": 12345
        },
        "engine": {
          "timestamp": 12345
        }
      },
      "delta": {
        "color": {
          "timestamp": 12345
        },
        "state": {
          "timestamp": 12345
        }
      }
    },
    "version": 17,
    "timestamp": 123456789
  }
}
```

ネストされたオブジェクトが異なると、差分にはルートへのパスが含まれます。

```
{
  "state": {
    "desired": {
      "lights": {
        "color": {
          "r": 255,
          "g": 255,
          "b": 255
        }
      }
    },
    "reported": {
      "lights": {
        "color": {
          "r": 255,
          "g": 0,
          "b": 255
        }
      }
    },
    "delta": {
      "lights": {
        "color": {
          "g": 255
        }
      }
    }
  },
  "version": 18,
  "timestamp": 123456789
}
```

Device Shadow サービスは、`desired` 状態の各フィールドを反復処理し、`reported` 状態と比較することで、差分を計算します。

配列は値のように扱われます。`desired` セクションの配列が `reported` セクションの配列に一致しない場合は、desired 配列全体が差分にコピーされます。

## シャドウドキュメントのバージョニング
<a name="versioning"></a>

Device Shadow サービスは、リクエストとレスポンスの両方の更新メッセージごとにバージョニングをサポートします。つまり、シャドウが更新されるたびに、JSON ドキュメントのバージョンが増分されます。これにより、以下の 2 つのことが確実になります。
+ クライアントは、古いバージョン番号を使用して Shadow を上書きしようとした場合、エラーを受け取ることができます。デバイスのシャドウを更新するには、再同期する必要があることがクライアントに通知されます。
+ クライアントは、受信したメッセージ内のバージョンが自らで保存しているバージョンより古い場合、そのメッセージに基づいてアクションを実行しないことを決定できます。

クライアントは、シャドウドキュメントにバージョンを含めないことで、バージョン一致を回避できます。

## シャドウドキュメント内のクライアントトークン
<a name="client-token"></a>

クライアントトークンを MQTT ベースのメッセージングで使用して、リクエストとそのレスポンスに同じクライアントトークンが含まれていることを確認できます。これにより確実にレスポンスとリクエストが関連付けられます。

**注記**  
クライアントトークンは 64 バイトを超えない範囲にします。64 バイトを超えるクライアントトークンは、400 (不適切なリクエスト) レスポンスと*Invalid clientToken* エラーメッセージの原因となります。

## 空のシャドウドキュメントのプロパティ
<a name="device-shadow-empty-fields"></a>

シャドウドキュメントの `reported` プロパティと `desired` プロパティは、現在のシャドウ状態に適用されない場合は空にすることも、省略することもできます。たとえば、シャドウドキュメントには、desired 状態がある場合にのみ、`desired` プロパティが含まれます。次に、`desired` プロパティのない状態ドキュメントの有効な例を示します。

```
{
    "reported" : { "temp": 55 }
}
```

デバイスによってシャドウが更新されていない場合など、`reported` プロパティは空にすることもできます。

```
{
    "desired" : { "color" : "RED" }
}
```

更新によって `desired` または `reported` プロパティが null になると、ドキュメントから削除されます。次に、`desired` プロパティを `null` に設定して削除する方法を示します。たとえば、デバイスの状態を更新するときにこれを行うことができます。

```
{ 
    "state": {
        "reported": {
            "color": "red" 
        }, 
        "desired": null 
    } 
}
```

シャドウドキュメントには、`desired` プロパティと `reported` プロパティのいずれも持たないため、シャドウドキュメントは空になります。これは、空で有効なシャドウドキュメントの例です。

```
{
}
```

## シャドウドキュメント内の配列値
<a name="device-shadow-arrays"></a>

シャドウでは、配列がサポートされていますが、配列に対する更新により配列全体が置き換わる点では、通常の値として扱われます。配列の一部を更新することはできません。

初期状態:

```
{
    "desired" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
```

更新:

```
{
    "desired" : { "colors" : ["RED"] }
}
```

最終状態:

```
{
    "desired" : { "colors" : ["RED"] }
}
```

配列に null 値を含めることはできません。たとえば、以下の配列は有効ではなく、拒否されます。

```
{
    "desired" : { 
        "colors" : [ null, "RED", "GREEN" ]
    }
}
```