オートメーションAPIリファレンス
オートメーションAPIを使用すると、Alexaがユーザーに代わって自動的に実行する操作を指定できます。オートメーションは、トリガー、操作、オプションの条件で構成されます。
APIエンドポイント
オートメーションAPIのエンドポイントは、https://api.amazonalexa.com
です。
認証
すべてのAPIリクエストには認可ヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
オートメーションAPIには、以下の操作が用意されています。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
|
オートメンションテンプレートを作成する
LWAトークンで表されるユーザーが所有するオートメーションテンプレートを作成します。現在、オートメーションテンプレートはすべてプライベートと見なされます。つまり、テンプレートの所有者だけが、そのテンプレートからオートメーションを作成できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションテンプレートを作成するには、/v2/automations/templates
リソースに対してPOST
リクエストを送信します。
リクエストヘッダーの例
POST /v2/automations/templates HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
リクエスト本文の例
{
"template":{
"trigger":{
"type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
"version": "1.0",
"payload": {
"utterances": ["${data.customUtterance.text}", "utterance B", "utterance C"],
"locale": "en-US"
}
},
"operations":{
"serial":[
{
"operation":{
"type": "Alexa.Automation.Operation.Notification.Notify",
"version": "1.0",
"payload": {
"notification": {
"variants": [{
"type": "Announcement",
"content": {
"variants": [{
"type": "SpokenText",
"values": [{
"locale": "en-US",
"text": "Happy hour is starting now in the pool area!"
}]
}]
}
}]
}
}
}
}
]
}
},
"dataDefinition":{
"customUtterance":{
"type":"object",
"required":[
"text"
],
"properties":{
"text":{
"type":"string",
"minLength":1
}
}
}
},
"friendlyName":{
"value":{
"text":"Test template"
}
}
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
オートメーションテンプレートです。 |
オブジェクト |
◯ |
|
オートメーションテンプレートのトリガーです。トリガーオブジェクトには、Alexaで定義されているトリガースキーマのいずれかを使用できます。使用できるトリガータイプは、 |
オブジェクト |
◯ |
|
オートメーションテンプレートの操作です。このフィールドには、 |
オブジェクト |
◯ |
|
オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では |
オブジェクト |
✕ |
|
ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。 |
オブジェクト |
✕ |
|
フレンドリー名のテキストを含むオブジェクトです。 |
オブジェクト |
✕ |
|
オートメーションテンプレートの名前です。 |
文字列 |
✕ |
応答
正常に完了すると、HTTP 201
と共に、応答のLocation
ヘッダーにテンプレートIDが返されます。
応答本文の例
{
"templateId": "amzn1.alexa.automation.template.{example-template-id}"
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
作成されたオートメーションテンプレート用にAlexaによって生成されたテンプレートIDです。形式は |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
オートメーションテンプレートが正常に作成されました。 |
|
リクエストの形式が次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバー側でエラーが発生しました。 |
オートメーションテンプレートを削除する
指定されたテンプレートIDに関連付けられているオートメーションテンプレートを削除します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションテンプレートを削除するには、/v2/automations/templates/{templateId}
リソースに対してDELETE
リクエストを送信します。
オートメーションテンプレートを削除できるのは、そのオートメーションテンプレートの所有者だけです。
リクエストヘッダーの例
DELETE /v2/automations/templates/{templateId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
削除するオートメーションテンプレートのIDです。テンプレートIDは、 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 204が返されます。このテンプレートに基づくオートメーションインスタンスが存在する場合、AlexaはHTTP 400を返します。
応答本文の例
応答の本文はありません。
応答本文のパラメーター
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
このテンプレートに基づくオートメーションインスタンスが存在しているか、リクエストの形式が正しくありませんでした。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバー側でエラーが発生しました。 |
オートメーションテンプレートを取得する
指定されたテンプレートIDに関連付けられているオートメーションテンプレートを取得します。
呼び出し元は、そのオートメーションテンプレートの所有者である必要があります。そうでない場合、Alexaから404応答が返されます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションテンプレートを取得するには、/v2/automations/templates/{templateId}
リソースに対してGETリクエストを送信します。
リクエストヘッダーの例
GET /v2/automations/templates/{templateId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
取得するオートメーションテンプレートのIDです。テンプレートIDは、 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200と共に、指定したオートメーションテンプレートの詳細が返されます。
応答本文の例
以下は、応答の例です。
{
"templateId":"amzn1.alexa.automation.template.{id}",
"template":{
"trigger":{
"type":"CustomUtterance",
"version":"1.0",
"payload":{
"utterance":"${data.customUtterance.text}",
"locale":"en-US"
}
},
"operations":{
"serial":[
{
"operation":{
"type":"AlexaAnnouncement",
"version":1.0,
"payload":{
"content":[
{
"locale":"en-US",
"speak":{
"type":"text",
"value":"Hello"
}
}
]
}
}
}
]
}
},
"dataDefinition":{
"customUtterance":{
"type":"object",
"required":[
"text"
],
"properties":{
"text":{
"type":"string",
"minLength":1
}
}
}
},
"friendlyName":{
"value":{
"text":"Test template"
}
}
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
取得されたオートメーションテンプレートのIDです。テンプレートIDの形式は |
文字列 |
|
オートメーションテンプレートのトリガーです。トリガーオブジェクトは、Alexaで定義されているトリガースキーマのいずれかです。 |
オブジェクト |
|
オートメーションテンプレートの操作です。このフィールドには、 |
オブジェクト |
|
オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では |
オブジェクト |
|
ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。 |
オブジェクト |
|
フレンドリー名のテキストを含むオブジェクトです。 |
オブジェクト |
|
オートメーションテンプレートの名前です。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションテンプレートのリストを取得する
オートメーションテンプレートのリストを取得します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションテンプレートのリストを取得するには、/v2/automations/templates
リソースに対してGETリクエストを送信します。Alexaは、LWAトークンに関連付けられているcustomerId
によって作成されたすべてのテンプレートを返します。
リクエストヘッダーの例
GET /v2/automations/templates?maxResults={maxResults}&nextToken={nextToken}&expand=all HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
ページ分割された結果から特定のページを取得するためのトークンです。このトークンがない場合、応答には結果の最初のページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
文字列 |
✕ |
|
応答本文で返される結果の最大数です。100以下の正の値を指定してください。デフォルト値は20です。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
数値 |
✕ |
|
応答に含めるアトリビュート(またはアトリビュートのセット)です。有効な値は |
文字列 |
✕ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200と共に、オートメーションテンプレートのリストが返されます。
expandがallに設定されていない場合の応答本文の例
以下は、expand
がall
に設定されていない場合の応答の例です。
{
"results":[
{
"templateId":"amzn1.alexa.automation.template.{id}"
}
],
"paginationContext":{
"nextToken":""
}
}
expandがallに設定されている場合の応答本文の例
以下は、expand
がall
に設定されている場合の応答の例です。
{
"results":[
{
"templateId":"amzn1.alexa.automation.template.{id}",
"template":{
"trigger":{
"type":"CustomUtterance",
"version":"1.0",
"payload":{
"utterance":"${data.customUtterance.text}",
"locale":"en-US"
}
},
"operations":{
"serial":[
{
"operation":{
"type":"AlexaAnnouncement",
"version":1.0,
"payload":{
"content":[
{
"locale":"en-US",
"speak":{
"type":"text",
"value":"Hello"
}
}
]
}
}
}
]
}
},
"dataDefinition":{
"customUtterance":{
"type":"object",
"required":[
"text"
],
"properties":{
"text":{
"type":"string",
"minLength":1
}
}
}
},
"friendlyName":{
"value":{
"text":"Test template"
}
}
}
],
"paginationContext":{
"nextToken":""
}
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
クエリへの応答として返されたオートメーションテンプレートのリストです。 |
配列 |
|
取得されたオートメーションテンプレートのIDです。テンプレートIDの形式は |
文字列 |
|
オートメーションテンプレートのトリガーです。トリガーオブジェクトは、Alexaで定義されているトリガースキーマのいずれかです。 |
オブジェクト |
|
オートメーションテンプレートの操作です。このフィールドには、 |
オブジェクト |
|
オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では |
オブジェクト |
|
ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。 |
オブジェクト |
|
フレンドリー名のテキストを含むオブジェクトです。 |
オブジェクト |
|
オートメーションテンプレートの名前です。 |
文字列 |
|
結果がページ分割されていて続きがある場合に、追加の結果を取得するためのトークンです。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式( |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
テンプレートが存在しません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションを作成する
オートメーションテンプレートから、関連付けられたエンティティ(ユニット)で実行されるオートメーションインスタンスを作成します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションを作成するには、/v2/automations
リソースに対してPOST
リクエストを送信します。
リクエストヘッダーの例
POST /v2/automations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
リクエスト本文の例
{
"associatedEntity":{
"type":"UNIT",
"id":"amzn1.alexa.unit.did.{id}"
},
"automation":{
"templateId":"amzn1.alexa.automation.template.{id}",
"data":{
"customUtterance":{
"text":"Good morning"
}
}
},
"friendlyName":{
"value":{
"text":"Test automation"
}
}
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
このオートメーションの実行対象として関連付けられるエンティティ(ユニットなど)です。 |
文字列 |
◯ |
|
エンティティのタイプです。有効な値は |
文字列 |
◯ |
|
関連付けられるエンティティのIDです。タイプが |
文字列 |
◯ |
|
オートメーションインスタンスの作成元となるオートメーションテンプレートのIDです。 |
文字列 |
◯ |
|
カスタム変数と値を含むキーと値のマップです。 |
オブジェクト |
✕ |
|
リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。 |
オブジェクト |
✕ |
|
オートメーションのフレンドリー名を含む文字列です。 |
文字列 |
◯ |
応答
正常に完了すると、HTTP 201
と共に、応答のLocation
ヘッダーにオートメーションIDが返されます。
応答本文の例
{
"automationId": "example-automation-id"
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
作成されたオートメーション用にAlexaによって生成されたオートメーションIDです。形式は |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
オートメーションが正常に作成されました。 |
|
リクエストの形式が次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
テンプレートまたはユニットが存在しません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバー側でエラーが発生しました。 |
オートメーションを更新する
指定されたオートメーションを更新します。現在更新できるのは、data
オブジェクトのみです。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションを更新するには、/v2/automations/{automationId}
リソースに対してPUT
リクエストを送信します。
リクエストヘッダーの例
PUT /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
更新するオートメーションのオートメーションIDです。 |
文字列 |
◯ |
リクエスト本文の例
{
"automation":{
"data":{
"customUtterance":{
"text":"Good night"
}
}
}
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
テンプレートで指定されている変数を解決するために使用される、キーと値のマッピングです。たとえば、 |
オブジェクト |
✕ |
応答
正常に完了すると、HTTP 204
が返されます。リクエスターにautomationId
へのアクセス権限がない場合、リクエストは失敗します。
応答本文の例
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
オートメーションが存在しないか、リクエスターにオートメーションを管理する権限がありません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバー側でエラーが発生しました。 |
オートメーションを削除する
指定されたオートメーションIDに関連付けられているオートメーションを削除します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションを削除するには、/v2/automations/{automationId}
リソースに対してDELETE
リクエストを送信します。
リクエストヘッダーの例
DELETE /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
削除するオートメーションのIDです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 204が返されます。
応答本文の例
応答の本文はありません。
応答本文のパラメーター
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくありません。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバー側でエラーが発生しました。 |
オートメーションを取得する
指定されたオートメーションIDに関連付けられているオートメーションのアトリビュートを取得します。Alexaは、オートメーションと、すべての解決済みのパラメーターを返します。
呼び出し元は、そのオートメーションの所有者である必要があります。そうでない場合、Alexaから404応答が返されます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションを取得するには、/v2/automations/{automationId}
リクエストに対してGETリクエストを送信します。
リクエストヘッダーの例
GET /v2/automations/{automationId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
取得するオートメーションのIDです。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200と共に、指定したオートメーションの詳細が返されます。
応答本文の例
以下は、応答の例です。
{
"automationId":"amzn1.alexa.automation.{id}",
"friendlyName":{
"value":{
"text":"Good morning"
}
},
"associatedEntity":{
"type":"UNIT",
"id":"amzn1.alexa.unit.did.{id}"
},
"automation":{
"templateId":"amzn1.alexa.automation.template.{id}",
"trigger":{
"type":"CustomUtterance",
"version":"1.0",
"payload":{
"utterance":"I'm home",
"locale":"en-US"
}
},
"operations":{
"serial":[
{
"operation":{
"type":"AlexaAnnouncement",
"version":1.0,
"payload":{
"content":[
{
"locale":"en-US",
"speak":{
"type":"text",
"value":"Hello"
}
}
]
}
}
}
]
}
}
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
オートメーションIDです。 |
文字列 |
|
このオートメーションの実行対象となるターゲットユーザー(ユニットなど)です。 |
文字列 |
|
エンティティのタイプです。有効な値は |
文字列 |
|
ターゲットユーザーのIDです。タイプが |
文字列 |
|
このオートメーションをテンプレートから作成した場合、オートメーションの作成に使用した |
文字列 |
|
オートメーションのトリガーです。 |
オブジェクト |
|
オートメーションの操作です。 |
オブジェクト |
|
リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。 |
オブジェクト |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションのリストを取得する
指定されたunitId
に関連付けられているオートメーションのリストを取得します。呼び出し元に、指定したユニット内のオートメーションを表示する権限が必要です。そうでない場合、Alexaは空のリストを返します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションのリストを表示するには、/v2/automations
リソースに対してGETリクエストを送信します。
ユニットのオートメーションのリストを取得するリクエストヘッダーの例
GET
/v2/automations?associatedEntity.type=UNIT&associatedEntity.id={id}&maxResults={maxResults}&nextToken={nextToken}&expand=all
ユニットとテンプレートIDを指定してオートメーションのリストを取得するリクエストヘッダーの例
GET
/v2/automations?associatedEntity.type=UNIT&associatedEntity.id={id}&templateId={templateId}&maxResults={maxResults}&nextToken={nextToken}&expand=all
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
LWAトークンです。 |
文字列 |
◯ |
|
特定の |
文字列 |
◯ |
|
エンティティのタイプです。有効な値は |
文字列 |
◯ |
|
特定のオートメーションテンプレートから作成されたオートメーションのみに結果をフィルタリングするためのテンプレートIDです。 |
文字列 |
◯ |
|
ページ分割された結果から特定のページを取得するためのトークンです。このトークンがない場合、応答には結果の最初のページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
文字列 |
✕ |
|
応答本文で返される結果の最大数です。100以下の正の値を指定してください。デフォルト値は20です。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
数値 |
✕ |
|
応答に含めるアトリビュート(またはアトリビュートのセット)です。有効な値は |
文字列 |
✕ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 200と共に、オートメーションのリストが返されます。
expandがallに設定されていない場合の応答本文の例
以下は、expand
がall
に設定されていない場合の応答の例です。
{
"results":[
{
"automationId":"amzn1.alexa.automation.{id}"
}
],
"paginationContext":{
"nextToken":""
}
}
expandがallに設定されている場合の応答本文の例
以下は、expand
がall
に設定されている場合の応答の例です。
{
"results":[
{
"automationId":"amzn1.alexa.automation.{id}",
"friendlyName":{
"value":{
"text":"Good morning"
}
},
"associatedEntity":{
"type":"UNIT",
"id":"amzn1.alexa.unit.did.{id}"
},
"automation":{
"templateId":"amzn1.alexa.automation.template.{id}",
"trigger":{
"type":"CustomUtterance",
"version":"1.0",
"payload":{
"utterance":"I'm home",
"locale":"en-US"
}
},
"operations":{
"serial":[
{
"operation":{
"type":"AlexaAnnouncement",
"version":1.0,
"payload":{
"content":[
{
"locale":"en-US",
"speak":{
"type":"text",
"value":"Hello"
}
}
]
}
}
}
]
}
}
}
],
"paginationContext":{
"nextToken":""
}
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
クエリへの応答として返されたオートメーションのリストです。 |
配列 |
|
オートメーションが実行される、関連付けられたエンティティ(ユニット)です。 |
文字列 |
|
エンティティのタイプです。有効な値は |
文字列 |
|
ターゲットユーザーのIDです。タイプが |
文字列 |
|
オートメーションのIDです。 |
文字列 |
|
このオートメーションをテンプレートから作成した場合、オートメーションの作成に使用した |
文字列 |
|
オートメーションのトリガーです。 |
オブジェクト |
|
オートメーションの操作です。 |
オブジェクト |
|
リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。 |
オブジェクト |
|
結果がページ分割されていて続きがある場合に、追加の結果を取得するためのトークンです。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式( |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの規定のリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オブジェクトスキーマ
オートメーションAPIでは、以下のオブジェクトを使用します。
Alexa.Automation.Trigger.Voice.CustomUtteranceオブジェクト
このオブジェクトは、オートメーションの実行をトリガーする音声フレーズを表します。このトリガーは、スコープがalexa::enterprise:management
の場合にのみ使用できます。同じ発話をトリガーとするオートメーションがユニットに存在する場合、AlexaはHTTP 400を返します。
オブジェクトの例
{
"type": "Alexa.Automation.Trigger.Voice.CustomUtterance",
"version": "1.0",
"payload": {
"utterances": ["utterance A", "utterance B", "utterance C"],
"locale": "en-US"
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
カスタム発話トリガーの名前です。有効な値は |
列挙型文字列 |
◯ |
|
トリガーとなる発話を優先度順に格納するリストです。 |
文字列の配列 |
◯ |
|
読み上げテキストがレンダリングされるロケールです。IETF BCP 47形式で表します。 |
文字列 |
◯ |
Alexa.Automation.Trigger.Schedule.AbsoluteTimeオブジェクト
このオブジェクトは、オートメーションの実行をトリガーする時刻を表します。
オブジェクトの例
{
"type": "Alexa.Automation.Trigger.Schedule.AbsoluteTime",
"version": "1.0",
"payload": {
"schedule": {
"triggerTime": "193209",
"timeZoneId": "UTC",
"recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO"
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
絶対時刻スケジュールトリガーの名前です。有効な値は |
列挙型文字列 |
◯ |
|
絶対時刻スケジュールトリガーのペイロードのバージョンです。 |
文字列 |
◯ |
|
アクションを実行する時刻です。RFC 5545 TIMEで定義される、「Z」表記のない形式を使用します。 |
文字列 |
◯ |
|
オートメーションのタイムゾーンです。夏時間が適用される場合に、自動的に時刻を調整するために必要です。詳細については、List of tz database time zonesを参照してください。 |
文字列 |
◯ |
|
繰り返しのスケジュールを |
文字列 |
◯ |
Alexa.Automation.Trigger.Schedule.SunriseInCustomLocationオブジェクト
このオブジェクトは、オートメーションの実行をトリガーする日の出時刻を表します。
オブジェクトの例
{
"type": "Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation",
"version": "1.0",
"payload": {
"recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
"timeZoneId": "test-timezone-id",
"latitude": 100,
"longitude": 100,
"timeOffset": 100
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
絶対時刻スケジュールトリガーの名前です。有効な値は |
列挙型文字列 |
◯ |
|
日の出トリガーのバージョンです。 |
文字列 |
◯ |
|
繰り返しを定義する表現です。RFC 5545のパターンに従います。このトリガーは繰り返される必要があります。 |
文字列 |
◯ |
|
日の出地点の緯度です。 |
数値 |
◯ |
|
日の出地点の経度です。 |
数値 |
◯ |
|
日の出時刻からの時間オフセット(分単位)です。デフォルトは0です。 |
長整数 |
✕ |
Alexa.Automation.Trigger.Schedule.SunsetInCustomLocationオブジェクト
このオブジェクトは、オートメーションの実行をトリガーする日の入り時刻を表します。
オブジェクトの例
{
"type": "Alexa.Automation.Trigger.Schedule.SunsetInCustomLocation",
"version": "1.0",
"payload": {
"recurrence": "RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA",
"timeZoneId": "test-timezone-id",
"latitude": 100,
"longitude": 100,
"timeOffset": 100
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
絶対時刻スケジュールトリガーの名前です。有効な値は |
列挙型文字列 |
◯ |
|
日の入りトリガーのバージョンです。 |
文字列 |
◯ |
|
繰り返しを定義する表現です。RFC 5545のパターンに従います。このトリガーは繰り返される必要があります。 |
文字列 |
◯ |
|
日の入り地点の緯度です。 |
数値 |
◯ |
|
日の入り地点の経度です。 |
数値 |
◯ |
|
日の入り時刻からの時間オフセット(分単位)です。デフォルトは0です。 |
長整数 |
✕ |
Alexa.Automation.Operation.Notification.Notifyオブジェクト
関連付けられているトリガーが呼び出されたときにユニットにお知らせを送信する操作を表します。デフォルトの受信者は、オートメーションを関連付けたときに指定したユニットです。この操作は現在、スコープがalexa::enterprise:management
の場合にのみ使用できます。
オブジェクトの例
{
"type": "Alexa.Automation.Operation.Notification.Notify",
"version": "1.0",
"payload": {
"notification": {
"variants": [{
"type": "Announcement",
"content": {
"variants": [{
"type": "SpokenText",
"values": [{
"locale": "en-US",
"text": "Happy hour is starting now in the pool area!"
}]
}]
}
}]
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
お知らせ操作の名前です。有効な値は |
列挙型文字列 |
◯ |
|
お知らせ操作のペイロードのバージョンです。 |
文字列 |
◯ |
|
通知オブジェクトです。 |
オブジェクト |
◯ |
|
通知の配信タイプです。有効な値は |
列挙型文字列 |
◯ |
|
読み上げ用および画面表示用のコンテンツの各種バリアントです。 |
オブジェクト |
◯ |
|
ユーザーに配信する通知コンテンツです。 |
配列 |
◯ |
|
ローカライズされたテキスト入力です。有効な値は |
列挙型文字列 |
◯ |
|
コンテンツの値の配列です。各要素は、ローカライズされたテキスト入力を表します。 |
配列 |
◯ |
|
読み上げテキストがレンダリングされるロケールです。IETF BCP 47形式で表します。 |
文字列 |
◯ |
|
プレーンテキスト形式の読み上げテキストです。最大長は1024文字または2048バイトです。 |
文字列 |
◯ |
Alexa.Automation.Operation.Brightness.SetBrightnessオブジェクト
このオブジェクトは、エンドポイントの明るさを設定する操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Brightness.SetBrightness",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
],
"payload": {
"brightness": 10
}
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。 |
配列 |
◯ |
|
0~100の値です(両端の値を含みます)。 |
整数 |
◯ |
Alexa.Automation.Operation.Power.TurnOnオブジェクト
このオブジェクトは、エンドポイントをオンにする操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Power.TurnOn",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
]
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。 |
配列 |
◯ |
Alexa.Automation.Operation.Power.TurnOffオブジェクト
このオブジェクトは、エンドポイントをオフにする操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Power.TurnOff",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
]
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。 |
配列 |
◯ |
Alexa.Automation.Operation.Speaker.SetVolumeオブジェクト
このオブジェクトは、エンドポイントの音量を設定する操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Speaker.SetVolume",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
],
"payload": {
"volume": 10
}
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。 |
配列 |
◯ |
|
エンドポイントのスピーカー音量として設定する絶対音量です。有効な範囲は0~100です。 |
整数 |
◯ |
Alexa.Automation.Operation.Media.Stopオブジェクト
このオブジェクトは、エンドポイントでメディア再生を停止する操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Media.Stop",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
]
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作の名前です。有効な値は |
列挙型文字列 |
◯ |
|
操作スキーマのバージョンです。 |
文字列 |
◯ |
|
操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。 |
配列 |
◯ |
|
操作を実行するエンドポイントのIDです。このIDはターゲットデバイスを指定します。エンドポイントIDは |
文字列 |
◯ |
Alexa.Automation.Operation.Thermostat.SetTargetSetpointオブジェクト
このオブジェクトは、サーモスタットの目標温度を設定する操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Thermostat.SetTargetSetpoint",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
],
"payload": {
"targetSetpoint": {
"value": 20,
"scale": "CELSIUS"
}
}
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
設定値が1つのサーモスタットの目標設定値です。 |
◯(設定値が1つのサーモスタットの場合) |
Alexa.Automation.Operation.Settings.SetDoNotDisturbStateオブジェクト
このオブジェクトは、エンドポイントをおやすみモードにする操作を表します。
オブジェクトの例
{
"operation": {
"type": "Alexa.Automation.Operation.Settings.SetDoNotDisturbState",
"version": "1.0",
"payload": {
"endpoints": [
{
"id": "amzn1.alexa.endpoint.1234567"
}
],
"value": true,
"schedule": {
"type": "DURATION",
"value": "PT2H5M"
}
}
}
}
オブジェクトのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
操作の名前です。有効な値は |
列挙型文字列 |
◯ |
|
操作スキーマのバージョンです。 |
文字列 |
◯ |
|
操作が実行されるエンドポイントのセットです。サポートされる最大数は 1つです。 |
配列 |
◯ |
|
操作を実行するエンドポイントのIDです。このIDはターゲットデバイスを指定します。エンドポイントIDは |
文字列 |
◯ |
|
ターゲットデバイスで |
ブール値 |
◯ |
|
指定された時間範囲で |
オブジェクト |
✕ |
|
|
列挙 |
◯ |
|
期間または時刻の時間値です。ISO 8601形式で表します。例は以下のとおりです。
|
文字列 |
◯ |
|
タイムゾーンです。ISO 8601標準に従います。たとえば、 |
文字列 |
✕ |
関連トピック
最終更新日: 2023 年 03 月 16 日