オートメーションAPIリファレンス
オートメーションAPIを使用すると、Alexaがユーザーに代わって自動的に実行する操作を指定できます。個々のオートメーションは、トリガー、操作、オプション条件で構成されます。
オートメーションについて
オートメーションテンプレートは、プレースホルダーを使用して抽象的なオートメーションエクスペリエンスを表すものです。このテンプレートを使用すると、後からユニット固有のカスタマイズを指定してオートメーションを作成することができます。たとえば、毎日プレースホルダーの時間に音楽を再生するテンプレートを作成しておき、そのテンプレートから401号室用のオートメーションを作成して、Alexaが毎朝8時に401号室のEchoデバイスで音楽を再生するようにすることができます。オートメーションテンプレート自体では操作は一切実行されないため、オートメーションを機能させるには、テンプレートからオートメーションを作成する必要があります。
オートメーションを使用すると、Alexaコネクテッドデバイス(Echoデバイスなど)がユーザーに代わってタスクを自動的に実行できます。たとえば、日の入り時刻にキッチンの照明をつけることなどが可能です。個々のオートメーションは、1つのトリガー、1つ以上の操作、オプションの条件で構成されます。
トリガーとは、オートメーションを実行するために使用できる状態変化、イベント、ファクトを指します。Alexa Smart Propertiesのオートメーションでは、 発話、時刻、日の出、日の入りのトリガーがサポートされます。
操作とは、トリガーが呼び出されたときに実行できるアクションまたはタスクのことです。サポートされている操作には、 通知、明るさ(スマートホームデバイスのみ)、電源のオン/オフ、音量の設定、メディアの停止、設定値の設定(サーモスタットの温度など)、おやすみモードのオン/オフがあります。操作プロパティはツリーとして構築されるため、シリアルオブジェクト、パラレルオブジェクト、操作オブジェクトはそれぞれツリーノードとみなされます。各パラレルノードのノード数は90以下(パラレルノード、シリアルノード、操作ノードをすべて含む)にする必要があります。操作プロパティにパラレルノードまたはシリアルノードがあるかどうかにかかわらず、ノード数は150以下である必要があります。ノード数90のパラレルノードが2つある場合は、ノード数が180となるため、150の制限を超えてしまいます。
条件とは、Alexaが評価する1つ以上のルールのことで、このルールが当てはまる場合にのみ操作が実行されます。
APIエンドポイント
リクエストヘッダーでは、組織が所在する地域に応じて、Host
をhttps://api.amazonalexa.com
に設定してください。
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
オートメーションAPIには、以下の操作が用意されています。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
| |
| |
| |
| |
| |
| |
|
オートメーションテンプレートを作成する
LWAトークンで表されるユーザーが所有するオートメーションテンプレートを作成します。現在、オートメーションテンプレートはすべてプライベートとみなされ、そのテンプレートを基にオートメーションを作成できるのはテンプレートの所有者のみです。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ |
リクエスト本文の例
{
"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で定義済みのトリガースキーマのいずれかを使用できます。使用できるトリガータイプは |
オブジェクト |
◯ |
|
オートメーションテンプレートの操作。このフィールドには |
オブジェクト |
◯ |
|
オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。例: |
オブジェクト |
✕ |
|
オートメーションテンプレートユーザーへの表示名が指定されたオブジェクト。 |
オブジェクト |
✕ |
|
フレンドリー名テキストが指定されたオブジェクト。 |
オブジェクト |
✕ |
|
オートメーションテンプレートの名前。 |
文字列 |
✕ |
応答
正常に完了すると、テンプレートIDがLocation
ヘッダーに指定されたHTTP 201
が返されます。
応答本文の例
{
"templateId": "amzn1.alexa.automation.template.{example-template-id}"
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
作成したオートメーションテンプレート用にAlexaによって生成されたテンプレートID。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
オートメーションテンプレートが正常に作成されました。 |
|
リクエストの形式が、次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバー側のエラーが発生しました。 |
オートメーションテンプレートを削除する
指定されたテンプレートIDに関連付けられているオートメーションテンプレートを削除します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
削除するオートメーションテンプレートのID。テンプレートIDは |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 204が返されます。このテンプレートに基づくオートメーションインスタンスが存在する場合、AlexaはHTTP 400を返します。
応答本文の例
応答の本文はありません。
応答本文のパラメーター
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
このテンプレートに基づくオートメーションインスタンスが存在しているか、リクエストの形式が正しくありませんでした。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバー側のエラーが発生しました。 |
オートメーションテンプレートを取得する
指定されたテンプレートIDに関連付けられているオートメーションテンプレートを取得します。
呼び出し元がそのオートメーションテンプレートの所有者である必要があります。それ以外の場合、Alexaは応答として404を返します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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 Token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
取得するオートメーションテンプレートの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で定義済みのトリガースキーマのいずれかです。 |
オブジェクト |
|
オートメーションテンプレートの操作。このフィールドには |
オブジェクト |
|
オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。例: |
オブジェクト |
|
オートメーションテンプレートユーザーへの表示名が指定されたオブジェクト。 |
オブジェクト |
|
フレンドリー名テキストが指定されたオブジェクト。 |
オブジェクト |
|
オートメーションテンプレートの名前。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションテンプレートをリストする
オートメーションテンプレートをリストします。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
ページ分割された結果から特定のページを取得するためのトークン。このトークンがない場合、応答には結果の先頭ページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。 |
文字列 |
✕ |
|
応答本文で返される結果の最大数。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で定義済みのトリガースキーマのいずれかです。 |
オブジェクト |
|
オートメーションテンプレートの操作。このフィールドには |
オブジェクト |
|
オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。例: |
オブジェクト |
|
オートメーションテンプレートユーザーへの表示名が指定されたオブジェクト。 |
オブジェクト |
|
フレンドリー名テキストが指定されたオブジェクト。 |
オブジェクト |
|
オートメーションテンプレートの名前。 |
文字列 |
|
結果がページ分割されており、ほかにもまだある場合に、ほかの結果を取得するためのトークン。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式( |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
テンプレートが存在しません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションを作成する
関連付けられているエンティティ(ユニット)用のオートメーションテンプレートからオートメーションインスタンスを作成します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Senior Living | Core |
---|---|---|---|
米国 |
米国 |
米国 |
米国 |
リクエスト
オートメーションを作成するには、/v2/automations
リソースへのPOST
リクエストを行います。
リクエストヘッダーの例
POST /v2/automations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ |
リクエスト本文の例
{
"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"
}
}
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
Alexaによるこのオートメーションの実行対象である、関連付けられているエンティティ(ユニットなど)。 |
文字列 |
◯ |
|
エンティティのタイプ。有効な値: |
文字列 |
◯ |
|
関連付けられているエンティティのID。タイプが |
文字列 |
◯ |
|
オートメーションインスタンスの作成元になるオートメーションテンプレートのID。 |
文字列 |
◯ |
|
カスタム変数および値の、キーと値のマップ。 |
オブジェクト |
✕ |
|
リクエスターが定義したオートメーション名。ユーザーがこのフィールドを定義してオートメーションインスタンスを区別することもできます。 |
オブジェクト |
✕ |
|
オートメーションのフレンドリー名が指定された文字列。 |
文字列 |
◯ |
応答
正常に完了すると、オートメーションIDがLocation
ヘッダーに指定されたHTTP 201
が返されます。
応答本文の例
{
"automationId": "example-automation-id"
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
作成したオートメーション用にAlexaによって生成されたオートメーションID。 |
文字列 |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
オートメーションが正常に作成されました。 |
|
リクエストの形式が、次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
テンプレートまたはユニットが存在しません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバー側のエラーが発生しました。 |
オートメーションを更新する
指定されたオートメーションを更新します。現在、data
オブジェクトのみ更新できます。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
更新するオートメーションのオートメーションID。 |
文字列 |
◯ |
リクエスト本文の例
{
"automation":{
"data":{
"customUtterance":{
"text":"Good night"
}
}
}
}
リクエスト本文のパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
テンプレートに指定されている変数の解決に使用するデータのキー/値マッピング。たとえば、 |
オブジェクト |
✕ |
応答
正常に完了すると、HTTP 204
が返されます。automationId
へのアクセス権限がリクエスターにない場合、リクエストは失敗します。
応答本文の例
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が、次のいずれかの理由で正しくありません。
|
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
オートメーションが存在しないか、オートメーションを管理する権限がリクエスターにありません。 |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバー側のエラーが発生しました。 |
オートメーションを削除する
指定されたオートメーションIDに関連付けられているオートメーションを削除します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
削除するオートメーションのID。 |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答
正常に完了すると、HTTP 204が返されます。
応答本文の例
応答の本文はありません。
応答本文のパラメーター
応答の本文はありません。
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくありませんでした。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバー側のエラーが発生しました。 |
オートメーションを取得する
指定されたオートメーションIDに関連付けられているオートメーションのアトリビュートを取得します。Alexaは、パラメーターがすべて解決済みのオートメーションを返します。
呼び出し元がそのオートメーションの所有者である必要があります。それ以外の場合、Alexaは応答として404を返します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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}
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
取得するオートメーションの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"
}
}
]
}
}
}
]
}
}
}
応答本文のパラメーター
パラメーター | 説明 | 型 |
---|---|---|
|
パターン |
文字列 |
|
Alexaによるこのオートメーションの実行対象であるターゲットユーザー(ユニットなど)。 |
文字列 |
|
エンティティのタイプ。有効な値: |
文字列 |
|
ターゲットユーザーのID。タイプが |
文字列 |
|
オートメーションをテンプレートから作成した場合は、このオートメーションの作成に使用した |
文字列 |
|
オートメーションのトリガー。 |
オブジェクト |
|
オートメーションの操作。 |
オブジェクト |
|
リクエスターが定義したオートメーション名。ユーザーがこのフィールドを定義してオートメーションインスタンスを区別することもできます。 |
オブジェクト |
HTTPステータスコード
ステータス | 説明 |
---|---|
|
リクエストが成功しました。 |
|
リクエストの形式が正しくないか、必須パラメーターがありません。たとえば、 |
|
認可トークンが無効または期限切れか、リソースに対するアクセス権限が認可トークンにありません。 |
|
リクエストを完了できませんでした。この操作を実行する権限がクライアントにありません。 |
|
指定された |
|
ユーザーが、許可されたレート制限(単位時間あたりの指定されたリクエスト数)を超過しています。 |
|
サーバーでエラーが発生しました。 |
オートメーションをリストする
指定されたunitId
に関連付けられているオートメーションをリストします。指定されたユニットのオートメーションを表示するには、権限が必要です。それ以外の場合、Alexaは空のリストを返します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | 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
リクエストヘッダーのパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
文字列 |
◯ | |
|
|
文字列 |
◯ |
|
エンティティのタイプ。有効な値: |
文字列 |
◯ |
|
特定のオートメーションテンプレートから作成されたオートメーションに結果を絞り込むためのテンプレート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"
}
}
オブジェクトパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
カスタム発話トリガーの名前。有効な値: |
列挙型文字列 |
◯ |
|
トリガーとなる発話のリスト(優先度順)。 |
文字列の配列 |
◯ |
|
発話テキストが出力されるロケール。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!"
}]
}]
}
}]
}
}
}
オブジェクトパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
アナウンスの名前。有効な値: |
列挙型文字列 |
◯ |
|
アナウンス操作ペイロードのバージョン。 |
文字列 |
◯ |
|
通知オブジェクト。 |
オブジェクト |
◯ |
|
通知の配信タイプ。有効な値: |
列挙型文字列 |
◯ |
|
発話および画面表示を目的とするコンテンツの各種バリアント。 |
オブジェクト |
◯ |
|
ユーザーに配信される通知コンテンツ。 |
配列 |
◯ |
|
ローカライズされたテキスト入力。有効な値: |
列挙型文字列 |
◯ |
|
コンテンツ値の配列。各要素はローカライズされたテキスト入力です。 |
配列 |
◯ |
|
発話テキストが出力されるロケール。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"
}
}
}
}
}
オブジェクトパラメーター
パラメーター | 説明 | 型 | 必須 |
---|---|---|---|
|
単一設定点サーモスタットの目標設定点。 |
◯(単一設定点サーモスタットの場合) |
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標準形式で指定します。例: |
文字列 |
✕ |
関連トピック
最終更新日: 2024 年 11 月 13 日