Device Shadow サービスドキュメント - AWS IoT Core
シャドウドキュメントの例ドキュメントのプロパティdelta 状態シャドウドキュメントのバージョニングシャドウドキュメント内のクライアントトークン空のシャドウドキュメントのプロパティシャドウドキュメント内の配列値

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

Device Shadow サービスドキュメント

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

シャドウドキュメントの例

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

リクエスト状態ドキュメント

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

{
    "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 サービスは更新を処理します。

レスポンス状態ドキュメント

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

/accepted レスポンス状態ドキュメント

{
    "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 レスポンス状態ドキュメント

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

/documents レスポンス状態ドキュメント

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

レスポンス状態ドキュメントのプロパティ

  • previous — 更新が成功した後、更新前のオブジェクトの state が含まれます。

  • current — 更新が成功した後、更新後のオブジェクトの state が含まれます。

  • state

    • reported — モノが reported セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。

    • desired — デバイスが desired セクション内の任意のデータを報告し、リクエスト状態ドキュメントにあったフィールドだけを含む場合にのみ存在します。

    • delta — desired データがシャドウの現在の reported データと異なる場合のみ存在します。

  • metadata — いつ状態が更新されたかを決定できるように、desired および reported セクションの属性ごとにタイムスタンプが含まれます。

  • timestamp — レスポンスが によって生成されたエポック日時 AWS IoT。

  • clientToken — /update トピックに有効な JSON を発行するときにクライアントトークンが使用された場合にのみ存在します。

  • version — AWS IoT で共有されるデバイスのシャドウのドキュメントの現在のバージョン。ドキュメントの前バージョンから 1 ずつインクリメントされます。

エラーレスポンスドキュメント

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

{
    "code": error-code,
    "message": "error-message",
    "timestamp": timestamp,
    "clientToken": "token"
}

  • code — エラーのタイプを示す HTTP レスポンスコード。

  • message — 追加の情報を提供するテキストメッセージ。

  • timestamp — レスポンスが によって生成された日時 AWS IoT。このプロパティはすべてのエラーレスポンスドキュメントに存在するわけではありません。

  • clientToken — 発行されたメッセージでクライアントトークンが使用された場合にのみ表示されます。

詳細については、「Device Shadow エラーメッセージ」を参照してください。

シャドウ名リストレスポンスドキュメント

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

{
    "results": [
        "shadowName-1",
        "shadowName-2",
        "shadowName-3",
        "shadowName-n"
    ],
    "nextToken": "nextToken",
    "timestamp": timestamp
}

  • results — シャドウ名の配列。

  • nextToken — シーケンス内の次のページを取得するためにページングされたリクエストで使用するトークン値。返すシャドウ名がなくなると、このプロパティは存在しません。

  • timestamp — レスポンスが によって生成された日時 AWS IoT。

ドキュメントのプロパティ

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

state
desired

デバイスの desired 状態。アプリケーションは、ドキュメントのこの部分に書き込んで、デバイスの状態を直接更新できます。そのために、デバイスに接続する必要はありません。

reported

デバイスの reported 状態。デバイスはドキュメントのこの部分に書き込んで、デバイスの新しい状態を報告します。アプリは、ドキュメントのこの部分を読み取り、デバイスの last-reported 状態を判断します。

metadata

ドキュメントの state セクションに保存されたデータに関する情報。この情報には state セクション内の属性ごとにタイムスタンプ (エポック時間) が含まれており、いつそれらの属性が更新されたかを決定できます。

注記

メタデータは、サービスの制限または料金に関連するドキュメントサイズに影響を与えません。詳細については、「AWS IoT サービス制限」を参照してください。

timestamp

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

clientToken

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

version

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

詳細については、「シャドウドキュメントの例」を参照してください。

delta 状態

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 配列全体が差分にコピーされます。

シャドウドキュメントのバージョニング

Device Shadow サービスは、リクエストとレスポンスの両方の更新メッセージごとにバージョニングをサポートします。つまり、シャドウが更新されるたびに、JSON ドキュメントのバージョンが増分されます。これにより、以下の 2 つのことが確実になります。

  • クライアントは、古いバージョン番号を使用して Shadow を上書きしようとした場合、エラーを受け取ることができます。デバイスのシャドウを更新するには、再同期する必要があることがクライアントに通知されます。

  • クライアントは、受信したメッセージ内のバージョンが自らで保存しているバージョンより古い場合、そのメッセージに基づいてアクションを実行しないことを決定できます。

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

シャドウドキュメント内のクライアントトークン

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

注記

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

空のシャドウドキュメントのプロパティ

シャドウドキュメントの 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 プロパティのいずれも持たないため、シャドウドキュメントは空になります。これは、空で有効なシャドウドキュメントの例です。

{
}

シャドウドキュメント内の配列値

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

初期状態:

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

更新:

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

最終状態:

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

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

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