オートメーションAPIリファレンス

オートメーションAPIリファレンス

オートメーションAPIを使用すると、Alexaがユーザーに代わって自動的に実行する操作を指定できます。オートメーションは、トリガー、操作、オプションの条件で構成されます。

APIエンドポイント

オートメーションAPIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストには認可ヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。

操作

オートメーションAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

オートメンションテンプレートを作成する

POST /v2/automations/templates

オートメーションテンプレートを削除する

DELETE /v2/automations/templates/{templateId}

オートメーションテンプレートを取得する

GET /v2/automations/templates/{templateId}

オートメーションテンプレートのリストを取得する

GET /v2/automations/templates

オートメーションを作成する

POST /v2/automations

オートメーションを更新する

PUT /v2/automations/{automationId}

オートメーションを削除する

DELETE /v2/automations/{automationId}

オートメーションを取得する

GET /v2/automations/{automationId}

オートメーションのリストを取得する

GET /v2/automations

オートメンションテンプレートを作成する

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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

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

リクエスト本文のパラメーター

パラメーター 説明 型 必須

template

オートメーションテンプレートです。

オブジェクト

◯

template.trigger

オートメーションテンプレートのトリガーです。トリガーオブジェクトには、Alexaで定義されているトリガースキーマのいずれかを使用できます。使用できるトリガータイプは、Alexa.Automation.Trigger.Voice.CustomUtterance、Alexa.Automation.Trigger.Schedule.AbsoluteTime、Alexa.Automation.Trigger.Schedule.SunriseInCustomLocation、Alexa.Automation.Trigger.Schedule.SunsetInCustomLocationです。

オブジェクト

◯

template.operations

オートメーションテンプレートの操作です。このフィールドには、serial、parallel、operationの各ノードを含めることができます。parallelノードの最大数は90、ノードの最大合計数は150です。

オブジェクト

◯

dataDefinition

オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では{data.customUtterance.text}が定義されています。

オブジェクト

✕

friendlyName

ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。

オブジェクト

✕

friendlyName.value

フレンドリー名のテキストを含むオブジェクトです。

オブジェクト

✕

friendlyName.value.text

オートメーションテンプレートの名前です。

文字列

✕

応答

正常に完了すると、HTTP 201と共に、応答のLocationヘッダーにテンプレートIDが返されます。

応答本文の例

{
  "templateId": "amzn1.alexa.automation.template.{example-template-id}"
}

応答本文のパラメーター

パラメーター 説明 型

templateId

作成されたオートメーションテンプレート用にAlexaによって生成されたテンプレートIDです。形式はamzn1.alexa.automation.template.{id}です。

文字列

HTTPステータスコード

ステータス 説明

201 Created

オートメーションテンプレートが正常に作成されました。

400 Bad Request

リクエストの形式が次のいずれかの理由で正しくありません。
  • リクエスト本文の形式が正しくありません。
  • トリガーまたは操作が存在しません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバー側でエラーが発生しました。

オートメーションテンプレートを削除する

指定されたテンプレート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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

templateId

削除するオートメーションテンプレートのIDです。テンプレートIDは、amzn1.alexa.automation.template.{id}の形式で指定する必要があります。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204が返されます。このテンプレートに基づくオートメーションインスタンスが存在する場合、AlexaはHTTP 400を返します。

応答本文の例

応答の本文はありません。

応答本文のパラメーター

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 Success

リクエストが成功しました。

400 Bad Request

このテンプレートに基づくオートメーションインスタンスが存在しているか、リクエストの形式が正しくありませんでした。たとえば、templateIdにはamzn1.alexa.automation.templateというプレフィックスが必要です。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

指定されたtemplateIdが存在しません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバー側でエラーが発生しました。

オートメーションテンプレートを取得する

指定されたテンプレート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トークン}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

templateId

取得するオートメーションテンプレートのIDです。テンプレートIDは、amzn1.alexa.automation.template.{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"
    }
  }
}

応答本文のパラメーター

パラメーター 説明 型

templateId

取得されたオートメーションテンプレートのIDです。テンプレートIDの形式はamzn1.alexa.automation.template.{id}です。

文字列

template.trigger

オートメーションテンプレートのトリガーです。トリガーオブジェクトは、Alexaで定義されているトリガースキーマのいずれかです。

オブジェクト

template.operations

オートメーションテンプレートの操作です。このフィールドには、serial、parallel、operationの各ノードが含まれる可能性があります。parallelノードの最大数は90、ノードの最大合計数は150です。

オブジェクト

dataDefinition

オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では{data.customUtterance.text}が定義されています。

オブジェクト

friendlyName

ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。

オブジェクト

friendlyName.value

フレンドリー名のテキストを含むオブジェクトです。

オブジェクト

friendlyName.value.text

オートメーションテンプレートの名前です。

文字列

HTTPステータスコード

ステータス 説明

200 Success

リクエストが成功しました。

400 Bad Request

リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、templateIdにamzn1.alexa.automation.templateというプレフィックスがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

指定されたtemplateIdが存在しません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバーでエラーが発生しました。

オートメーションテンプレートのリストを取得する

オートメーションテンプレートのリストを取得します。

この操作は以下の国で使用できます。

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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

nextToken

ページ分割された結果から特定のページを取得するためのトークンです。このトークンがない場合、応答には結果の最初のページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

✕

maxResults

応答本文で返される結果の最大数です。100以下の正の値を指定してください。デフォルト値は20です。詳細については、クエリ結果のページ分割を処理するを参照してください。

数値

✕

expand

応答に含めるアトリビュート（またはアトリビュートのセット）です。有効な値はallです。expandが設定されていない場合、AlexaはtemplateIdのリストを返します。

文字列

✕

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答

正常に完了すると、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":""
  }
}

応答本文のパラメーター

パラメーター 説明 型

results[]

クエリへの応答として返されたオートメーションテンプレートのリストです。

配列

results[].templateId

取得されたオートメーションテンプレートのIDです。テンプレートIDの形式はamzn1.alexa.automation.template.{id}です。

文字列

results[].template.trigger

オートメーションテンプレートのトリガーです。トリガーオブジェクトは、Alexaで定義されているトリガースキーマのいずれかです。

オブジェクト

results[].template.operations

オートメーションテンプレートの操作です。このフィールドには、serial、parallel、operationの各ノードが含まれる可能性があります。parallelノードの最大数は90、ノードの最大合計数は150です。

オブジェクト

results[].dataDefinition

オートメーションテンプレート内でのデータパラメーターの定義です。このオブジェクト内の各キーが、1つのデータパラメーターを定義します。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。たとえば、上の例では{data.customUtterance.text}が定義されています。

オブジェクト

results[].friendlyName

ユーザーに表示されるオートメーションテンプレートの名前を含むオブジェクトです。

オブジェクト

results[].friendlyName.value

フレンドリー名のテキストを含むオブジェクトです。

オブジェクト

results[].friendlyName.value.text

オートメーションテンプレートの名前です。

文字列

paginationContext.nextToken

結果がページ分割されていて続きがある場合に、追加の結果を取得するためのトークンです。

文字列

HTTPステータスコード

ステータス 説明

200 Success

リクエストが成功しました。

400 Bad Request

リクエストの形式（templateIdやunitIdの形式など）が正しくないか、必須パラメーターがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

テンプレートが存在しません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバーでエラーが発生しました。

オートメーションを作成する

オートメーションテンプレートから、関連付けられたエンティティ（ユニット）で実行されるオートメーションインスタンスを作成します。

この操作は以下の国で使用できます。

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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

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

リクエスト本文のパラメーター

パラメーター 説明 型 必須

associatedEntity

このオートメーションの実行対象として関連付けられるエンティティ（ユニットなど）です。

文字列

◯

associatedEntity.type

エンティティのタイプです。有効な値は UNITです。

文字列

◯

associatedEntity.id

関連付けられるエンティティのIDです。タイプがUNITの場合、IDはamzn1.alexa.unit.did.{id}というunitIdのパターンに従う必要があります。

文字列

◯

automation.templateId

オートメーションインスタンスの作成元となるオートメーションテンプレートのIDです。templateIdはamzn1.alexa.automation.template.{id}というパターンに従う必要があります。unitIdはamzn1.alexa.unit.did.{id}というパターンに従う必要があります。

文字列

◯

automation.data

カスタム変数と値を含むキーと値のマップです。data内の各フィールドは、テンプレートに指定されているdataDefinition JSONスキーマに照らして検証されます。検証は純粋にスキーマ検証です。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。

オブジェクト

✕

friendlyName

リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。

オブジェクト

✕

friendlyName.value.text

オートメーションのフレンドリー名を含む文字列です。

文字列

◯

応答

正常に完了すると、HTTP 201と共に、応答のLocationヘッダーにオートメーションIDが返されます。

応答本文の例

{
  "automationId": "example-automation-id"
}

応答本文のパラメーター

パラメーター 説明 型

automationId

作成されたオートメーション用にAlexaによって生成されたオートメーションIDです。形式はamzn1.alexa.automation.{id}です。

文字列

HTTPステータスコード

ステータス 説明

201 Created

オートメーションが正常に作成されました。

400 Bad Request

リクエストの形式が次のいずれかの理由で正しくありません。
  • リクエスト本文の形式が正しくありません。
  • トリガーまたは操作が存在しません。
  • templateIdまたはunitIdの形式が正しくありません。
  • テンプレートに未解決のバインドされていない変数があります。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

テンプレートまたはユニットが存在しません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバー側でエラーが発生しました。

オートメーションを更新する

指定されたオートメーションを更新します。現在更新できるのは、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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

automationId

更新するオートメーションのオートメーションIDです。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
  "automation":{
    "data":{
      "customUtterance":{
        "text":"Good night"
      }
    }
  }
}

リクエスト本文のパラメーター

パラメーター 説明 型 必須

automation.data

テンプレートで指定されている変数を解決するために使用される、キーと値のマッピングです。たとえば、${data.customUtterance}は、dataのcustomerUtteranceフィールドを参照します。${}で示された変数がデータ内に見つからない場合は、400エラーが発生します。

オブジェクト

✕

応答

正常に完了すると、HTTP 204が返されます。リクエスターにautomationIdへのアクセス権限がない場合、リクエストは失敗します。

応答本文の例

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 Succeeded

リクエストが成功しました。

400 Bad Request

リクエストの形式が次のいずれかの理由で正しくありません。
  • リクエスト本文の形式が正しくありません。
  • automationIdにamzn1.alexa.automationというプレフィックスがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

オートメーションが存在しないか、リクエスターにオートメーションを管理する権限がありません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバー側でエラーが発生しました。

オートメーションを削除する

指定されたオートメーション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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

automationId

削除するオートメーションのIDです。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204が返されます。

応答本文の例

応答の本文はありません。

応答本文のパラメーター

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 Success

リクエストが成功しました。

400 Bad Request

リクエストの形式が正しくありません。たとえば、automationIdにamzn1.alexa.automationというプレフィックスがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

指定されたautomationIdに関連付けられているオートメーションが存在しないか、リクエスターにそのオートメーションを管理する権限がありません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバー側でエラーが発生しました。

オートメーションを取得する

指定されたオートメーション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}

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

automationId

取得するオートメーションの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"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

応答本文のパラメーター

パラメーター 説明 型

automationId

オートメーションIDです。amzn1.alexa.automation.{id}というパターンに従います。

文字列

associatedEntity

このオートメーションの実行対象となるターゲットユーザー（ユニットなど）です。

文字列

associatedEntity.type

エンティティのタイプです。有効な値は UNITです。

文字列

associatedEntity.id

ターゲットユーザーのIDです。タイプがUNITの場合、IDはamzn1.alexa.unit.did.{id}というunitIdのパターンに従う必要があります。

文字列

automation.templateId

このオートメーションをテンプレートから作成した場合、オートメーションの作成に使用したtemplateIdです。

文字列

automation.trigger

オートメーションのトリガーです。

オブジェクト

automation.operations

オートメーションの操作です。

オブジェクト

friendlyName

リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。

オブジェクト

HTTPステータスコード

ステータス 説明

200 Success

リクエストが成功しました。

400 Bad Request

リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、automationIdにamzn1.alexa.automationというプレフィックスがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

操作を実行する権限がクライアントにないため、リクエストを完了できませんでした。

404 Not Found

指定されたautomationIdが存在しません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバーでエラーが発生しました。

オートメーションのリストを取得する

指定された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

リクエストヘッダーのパラメーター

パラメーター 説明 型 必須

access token

LWAトークンです。

文字列

◯

associatedEntity.id

特定のUNITに関連付けられているオートメーションのみに結果をフィルタリングするためのIDです。

文字列

◯

associatedEntity.type

エンティティのタイプです。有効な値は UNITです。

文字列

◯

templateId

特定のオートメーションテンプレートから作成されたオートメーションのみに結果をフィルタリングするためのテンプレートIDです。

文字列

◯

nextToken

ページ分割された結果から特定のページを取得するためのトークンです。このトークンがない場合、応答には結果の最初のページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

✕

maxResults

応答本文で返される結果の最大数です。100以下の正の値を指定してください。デフォルト値は20です。詳細については、クエリ結果のページ分割を処理するを参照してください。

数値

✕

expand

応答に含めるアトリビュート（またはアトリビュートのセット）です。有効な値はallです。expandが設定されていない場合、AlexaはautomationIdのリストを返します。

文字列

✕

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答

正常に完了すると、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":""
  }
}

応答本文のパラメーター

パラメーター 説明 型

results[]

クエリへの応答として返されたオートメーションのリストです。

配列

results[].associatedEntity

オートメーションが実行される、関連付けられたエンティティ（ユニット）です。

文字列

results[].associatedEntity.type

エンティティのタイプです。有効な値は UNITです。

文字列

results[].associatedEntity.id

ターゲットユーザーのIDです。タイプがUNITの場合、IDはamzn1.alexa.unit.did.{id}というunitIdのパターンに従います。

文字列

results[].automationId

オートメーションのIDです。

文字列

results[].automation.templateId

このオートメーションをテンプレートから作成した場合、オートメーションの作成に使用したtemplateIdです。templateIdはamzn1.alexa.automation.template.{id}というパターンに従います。

文字列

results[].automation.trigger

オートメーションのトリガーです。

オブジェクト

results[].automation.operations

オートメーションの操作です。

オブジェクト

results[].friendlyName

リクエスターが定義したオートメーションの名前です。オートメーションインスタンスを区別するために、ユーザーがこのフィールドを定義することもできます。

オブジェクト

paginationContext.nextToken

結果がページ分割されていて続きがある場合に、追加の結果を取得するためのトークンです。

文字列

HTTPステータスコード

ステータス 説明

200 Success

リクエストが成功しました。

400 Bad Request

リクエストの形式（templateIdの形式など）が正しくないか、必須パラメーターがありません。

401 Unauthorized

認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。

403 Forbidden

リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。

429 Too Many Requests

ユーザーが、許可されたレート制限（単位時間あたりの規定のリクエスト数）を超過しています。

500 Internal Server Error

サーバーでエラーが発生しました。

オブジェクトスキーマ

オートメーション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"
   }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

カスタム発話トリガーの名前です。有効な値は Alexa.Trigger.CustomUtteranceです。

列挙型文字列

◯

payload.utterances

トリガーとなる発話を優先度順に格納するリストです。

文字列の配列

◯

payload.locale

読み上げテキストがレンダリングされるロケールです。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"
      }
   }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

絶対時刻スケジュールトリガーの名前です。有効な値は Alexa.Automation.Trigger.Schedule.AbsoluteTimeです。

列挙型文字列

◯

version

絶対時刻スケジュールトリガーのペイロードのバージョンです。

文字列

◯

payload.schedule.triggerTime

アクションを実行する時刻です。RFC 5545 TIMEで定義される、「Z」表記のない形式を使用します。

文字列

◯

payload.schedule.timeZoneId

オートメーションのタイムゾーンです。夏時間が適用される場合に、自動的に時刻を調整するために必要です。詳細については、List of tz database time zonesを参照してください。

文字列

◯

payload.schedule.recurrence

繰り返しのスケジュールをRRULE形式で指定します。

文字列

◯

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

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

絶対時刻スケジュールトリガーの名前です。有効な値は Alexa.Automation.Trigger.Schedule.SunriseInCustomLocationです。

列挙型文字列

◯

version

日の出トリガーのバージョンです。

文字列

◯

payload.recurrence

繰り返しを定義する表現です。RFC 5545のパターンに従います。このトリガーは繰り返される必要があります。

文字列

◯

payload.latitude

日の出地点の緯度です。

数値

◯

payload.longitude

日の出地点の経度です。

数値

◯

payload.timeOffset

日の出時刻からの時間オフセット（分単位）です。デフォルトは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
    }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

絶対時刻スケジュールトリガーの名前です。有効な値は Alexa.Automation.Trigger.Schedule.SunsetInCustomLocationです。

列挙型文字列

◯

version

日の入りトリガーのバージョンです。

文字列

◯

payload.recurrence

繰り返しを定義する表現です。RFC 5545のパターンに従います。このトリガーは繰り返される必要があります。

文字列

◯

payload.latitude

日の入り地点の緯度です。

数値

◯

payload.longitude

日の入り地点の経度です。

数値

◯

payload.timeOffset

日の入り時刻からの時間オフセット（分単位）です。デフォルトは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!"
                        }]
                    }]
                }
            }]
        }
    }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

お知らせ操作の名前です。有効な値は Alexa.Automation.Operation.Notification.Notifyです。

列挙型文字列

◯

version

お知らせ操作のペイロードのバージョンです。

文字列

◯

payload.notification

通知オブジェクトです。

オブジェクト

◯

payload.notification.variants[].type

通知の配信タイプです。有効な値は Announcementです。

列挙型文字列

◯

payload.notification.variants[].content

読み上げ用および画面表示用のコンテンツの各種バリアントです。

オブジェクト

◯

payload.notification.variants[].content.variants[]

ユーザーに配信する通知コンテンツです。

配列

◯

payload.notification.variants[].content.variants[].type

ローカライズされたテキスト入力です。有効な値は SpokenTextです。

列挙型文字列

◯

payload.notification.variants[].content.variants[].values[]

コンテンツの値の配列です。各要素は、ローカライズされたテキスト入力を表します。

配列

◯

payload.notification.variants[].content.variants[].values[].locale

読み上げテキストがレンダリングされるロケールです。IETF BCP 47形式で表します。

文字列

◯

payload.notification.variants[].content.variants[].values[].text

プレーンテキスト形式の読み上げテキストです。最大長は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
      }
    }
  }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

endpoints

操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。idはamzn1.alexa.endpoint.*の形式で指定する必要があります。

配列

◯

payload.brightness

0～100の値です（両端の値を含みます）。

整数

◯

Alexa.Automation.Operation.Power.TurnOnオブジェクト

このオブジェクトは、エンドポイントをオンにする操作を表します。

オブジェクトの例

クリップボードにコピーされました。

{
  "operation": {
    "type": "Alexa.Automation.Operation.Power.TurnOn",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

endpoints

操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。idはamzn1.alexa.endpoint.*の形式で指定する必要があります。

配列

◯

Alexa.Automation.Operation.Power.TurnOffオブジェクト

このオブジェクトは、エンドポイントをオフにする操作を表します。

オブジェクトの例

クリップボードにコピーされました。

{
  "operation": {
    "type": "Alexa.Automation.Operation.Power.TurnOff",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

endpoints

操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。idはamzn1.alexa.endpoint.*の形式で指定する必要があります。

配列

◯

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

オブジェクトのパラメーター

パラメーター 説明 型 必須

endpoints

操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。idはamzn1.alexa.endpoint.*の形式で指定する必要があります。

配列

◯

volume

エンドポイントのスピーカー音量として設定する絶対音量です。有効な範囲は0～100です。

整数

◯

Alexa.Automation.Operation.Media.Stopオブジェクト

このオブジェクトは、エンドポイントでメディア再生を停止する操作を表します。

オブジェクトの例

クリップボードにコピーされました。

{
  "operation": {
    "type": "Alexa.Automation.Operation.Media.Stop",
    "version": "1.0",
    "payload": {
      "endpoints": [
        {
          "id": "amzn1.alexa.endpoint.1234567"
        }
      ]
    }
  }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

操作の名前です。有効な値は Alexa.DeviceControls.Stopです。

列挙型文字列

◯

version

操作スキーマのバージョンです。

文字列

◯

endpoints

操作が実行されるエンドポイントのセットです。サポートされるエンドポイントの最大数は 1つです。idはamzn1.alexa.endpoint.*の形式で指定する必要があります。

配列

◯

payload.endpoints.id

操作を実行するエンドポイントのIDです。このIDはターゲットデバイスを指定します。エンドポイントIDはamzn1.alexa.endpoint.*の形式に従う必要があります。

文字列

◯

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

オブジェクトのパラメーター

パラメーター 説明 型 必須

payload.targetSetpoint

設定値が1つのサーモスタットの目標設定値です。

Temperature

◯（設定値が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"
      }
    }
  }
}

オブジェクトのパラメーター

パラメーター 説明 型 必須

type

操作の名前です。有効な値は Alexa.DeviceControls.DoNotDisturbです。

列挙型文字列

◯

version

操作スキーマのバージョンです。

文字列

◯

payload.endpoints

操作が実行されるエンドポイントのセットです。サポートされる最大数は 1つです。

配列

◯

payload.endpoints.id

操作を実行するエンドポイントのIDです。このIDはターゲットデバイスを指定します。エンドポイントIDはamzn1.alexa.endpoint.*の形式に従う必要があります。

文字列

◯

payload.value

ターゲットデバイスでDoNotDisturbモードを有効にするかどうかを示します。有効な値はtrueまたはfalseです。

ブール値

◯

payload.schedule

指定された時間範囲でDoNotDisturbモードを有効および無効にするスケジュールです。このスケジュールが設定されていない場合、DoNotDisturbモードは永続的に変更されます。

オブジェクト

✕

payload.schedule.type

DoNotDisturb操作では、時間のタイプとして以下の2つがサポートされます。
  • DURATION：更新されたDoNotDisturbステータスを指定時間の間維持します。
  • TIME：更新されたDoNotDisturbステータスを指定時刻まで維持します。

列挙

◯

payload.schedule.value

期間または時刻の時間値です。ISO 8601形式で表します。例は以下のとおりです。
  • 期間： PT2H5M - 2時間5分
  • 時刻： T18:00 - 午後6時まで

文字列

◯

payload.schedule.timeZone

タイムゾーンです。ISO 8601標準に従います。たとえば、 America/New_Yorkのようになります。指定されていない場合、timeZoneは、操作の作成時にデバイスのデフォルト値に設定されます。スケジュールのタイプがDURATIONの場合、timeZoneは無視されます。

文字列

✕

このページは役に立ちましたか？

最終更新日: 2023 年 03 月 16 日