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

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

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

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

オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、JSON Schema Validation: A Vocabulary for Structural Validation of JSONの仕様に従います。例：{data.customUtterance.text}。

オブジェクト

✕

friendlyName

オートメーションテンプレートユーザーへの表示名が指定されたオブジェクト。

オブジェクト

✕

friendlyName.value

フレンドリー名テキストが指定されたオブジェクト。

オブジェクト

✕

friendlyName.value.text

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

文字列

✕

応答

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

応答本文の例

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

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

パラメーター 説明 型 必須

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

オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、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 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

オートメーションテンプレート内部のデータパラメーターの定義。このオブジェクトの各キーがデータパラメーターの定義です。このデータは、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 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

Alexaによるこのオートメーションの実行対象である、関連付けられているエンティティ（ユニットなど）。

文字列

◯

associatedEntity.type

エンティティのタイプ。有効な値： UNIT。

文字列

◯

associatedEntity.id

関連付けられているエンティティのID。タイプがUNITの場合、IDの後ろにunitIdパターンとしてamzn1.alexa.unit.did.{id}を指定してください。

文字列

◯

automation.templateId

オートメーションインスタンスの作成元になるオートメーションテンプレートのID。templateIdの後ろにパターンamzn1.alexa.automation.templateを指定してください。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

オートメーションのフレンドリー名が指定された文字列。

文字列

◯

応答

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

応答本文の例

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

パターンamzn1.alexa.automation.{id}に含まれているオートメーションID。

文字列

associatedEntity

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

文字列

associatedEntity.type

エンティティのタイプ。有効な値： UNIT。

文字列

associatedEntity.id

ターゲットユーザーのID。タイプがUNITの場合、IDの後ろにunitIdパターンとしてamzn1.alexa.unit.did.{id}を指定してください。

文字列

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 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の後ろにunitIdパターンとしてamzn1.alexa.unit.did.{id}が続きます。

文字列

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

発話テキストが出力されるロケール。BCP-47形式で指定します。ロケールには言語と国／地域の両方を含める必要があります。例：en-US。

文字列

◯

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

発話テキストが出力されるロケール。BCP-47形式で指定します。ロケールには言語と国／地域の両方を含める必要があります。例：en-US。

文字列

◯

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

単一設定点サーモスタットの目標設定点。

Temperature

◯（単一設定点サーモスタットの場合）

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は無視されます。

文字列

✕

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

最終更新日: 2024 年 11 月 13 日