スマートホーム評価API
Smart Home Evaluation API(スマートホーム評価API)を使用すると、照明機能やサーモスタット機能を使用するスキルに、自動化された一連のテストを実施できます。以下のような利点があります。
- スキル開発の全体的な所要時間が短縮されます。
- 手動でテストする労力を軽減することで、コストが削減されます。
- 「Works with Alexa」認定にパスする可能性が高まります。
- スキルの質が向上します。
- 前提条件
- スマートホーム機能のテスト計画を一覧表示する
- スマートホーム機能評価を作成する
- スマートホーム機能評価を一覧表示する
- スマートホーム機能評価を取得する
- スマートホーム機能評価の結果を取得する
前提条件
- 使用するAlexaアカウントがアカウントリンク済みであること。
- 使用するAlexaアカウントでテストデバイスが検出済みであり、表示されていることが必要です。
スマートホーム機能のテスト計画を一覧表示する
この処理は、すべてのテスト計画情報を返します。利用できるテスト計画については、 こちらを参照してください。
リクエスト
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
HTTPメソッドとURIパス
GET /v1/skills/{skillId}/smartHome/testing/capabilityTestPlans?maxResults=<integer>&nextToken=<string>
リクエストのパラメーター
パラメーターの型 | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId |
一意のスキルIDです。 | パス | ◯ |
maxResults |
応答で返される項目の最大数です。このパラメーターを含めない場合、デフォルトの最大値は20です。このパラメーターを含める場合、応答に含まれる項目数は、指定した値を下回ることはあっても、上回ることはありません。1000を超える値は指定しないでください。 | クエリ | ✕ |
nextToken |
前回のリクエストから引き続き結果を返すためのトークンです。NextTokenは、利用可能な結果の数が、リクエストされた項目数以上の場合にのみ使用できます。 | クエリ | ✕ |
リクエストヘッダー
Content-Type: application/json
Accept: application/json
X-Amzn-RequiestId: string
応答
正常に完了すると、HTTP 200 OK
が返されます。
応答ヘッダー
Content-Type: application/json
X-Amzn-RequiestId: string
応答本文の構造
{
"paginationContext": {
"nextToken": string
"totalCount": integer
},
"testPlans": [
{
"id": string,
"description": string
}
]
}
応答本文のフィールド
paginationContextオブジェクト
フィールド | 説明 |
---|---|
nextToken |
前回のリクエストから引き続き結果を返すためのトークンです。NextTokenは、利用可能な結果の数が、リクエストされた項目数以上の場合にのみ使用できます。 |
totalCount |
リクエストを満たす項目の総数です。この数字は、この応答で返される項目の数よりも多い場合があります。 |
testPlansオブジェクト
フィールド | 説明 |
---|---|
id |
一意のテスト計画IDです。 |
description |
テスト計画の説明です。 |
200以外の応答本文
{
"message": string
}
フィールド | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
例
以下に、リクエストと応答の例を示します。
サンプルリクエスト
GET /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityTestPlans?maxResults=1
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 123-1234567-123
応答の例
HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: 123-1234567-123
応答本文
{
"paginationContext": {
"nextToken": "879731421==",
"totalCount": 2
},
"testPlans": [
{
"id": "1231231",
"description": "LightingTestPlanの説明"
}
]
}
スマートホーム機能評価を作成する
スマートホームスキルの機能評価を作成して開始するには、この処理を使用します。
リクエスト
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
HTTPメソッドとURIパス
POST /v1/skills/{skillId}/smartHome/testing/capabilityEvaluations
リクエストのパラメーター
パラメーター | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId |
一意のスキルIDです。 | パス | ◯ |
リクエストヘッダー
Content-Type: application/json
Accept: application/json
X-Amzn-RequiestId: string
リクエスト本文の構造
{
"endpoint": {
"endpointId": string
},
"capabilityTestPlan": {
"id": string
},
"stage": string
}
リクエスト本文の要素
パラメーター | 説明 | 必須 |
---|---|---|
stage |
スキルのステージを表します。有効な値はdevelopment とlive です。 |
◯ |
endpointオブジェクト
パラメーター | 説明 | 必須 |
---|---|---|
endpointId |
一意のエンドポイントIDです。 | ◯ |
capabilityTestPlanオブジェクト
パラメーター | 説明 | 必須 |
---|---|---|
id |
各テスト計画を示す一意のIDです。 | ◯ |
応答
リクエストが成功すると、HTTP 200 OK
が返されます。
応答ヘッダー
Content-Type: application/json
X-Amzn-RequestId: string
Location: string
応答本文の構造
{
"id": string,
"endpoint": {
"endpointId": string
},
"capabilityTestPlan": {
"id": string
},
"stage": string
}
応答本文の要素
応答本文には「requestオブジェクト」が含まれます。
パラメーター | 説明 |
---|---|
id |
各機能評価を識別する一意のIDです。 |
200以外の応答本文
{
"message": string
}
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
例
以下に、リクエストと応答の例を示します。
サンプルリクエスト
POST /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityEvaluations
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 123-1234567-123
{
"endpoint": {
"endpointId": "endpoint-001"
},
"capabilityTestPlan": {
"id": "test-plan-001"
},
"stage": "live"
}
応答の例
HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: 123-1234567-123
Location: /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityEvaluations/testRunId12312
{
"id": "testRunId12312",
"endpoint": {
"endpointId": "endpoint-001"
},
"capabilityTestPlan": {
"id": " test-plan-001"
},
"stage": "live"
}
スマートホーム機能評価を一覧表示する
指定されたスキルIDのすべての機能評価情報を返します。
リクエスト
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
HTTPメソッドとURIパス
GET /v1/skills/{skillId}/smartHome/testing/capabilityEvaluations?stage=<string>&startTimestampFrom=<string>&startTimestampTo=<string>&maxResults=<integer>&nextToken=<string>
リクエストのパラメーター
パラメーター | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId |
一意のスキルIDです。 | パス | ◯ |
stage |
スキルのステージを表します。有効な値はdevelopment とlive です。 |
クエリ | ◯ |
startTimestampFrom |
評価履歴の照会対象とする最初の評価開始日時です。タイムスタンプの形式はyyyy-MM-dd'T'HH:mm:ss.SSS'Zです。形式の例: 2019-10-10T23:37:37.982Z | クエリ | ✕ |
startTimestampTo |
評価履歴の照会対象とする最終の評価開始日時です。タイムスタンプの形式はyyyy-MM-dd'T'HH:mm:ss.SSS'Zです。形式の例: 2019-10-10T23:37:37.982Z | クエリ | ✕ |
maxResults |
応答で返される項目の最大数です。このパラメーターを含めない場合、デフォルトの最大値は20です。このパラメーターを含める場合、応答に含まれる項目数は、指定した値を下回ることはあっても、上回ることはありません。1000を超える値は指定しないでください。 | クエリ | ✕ |
nextToken |
前回のリクエストから引き続き結果を返すためのトークンです。NextTokenは、利用可能な結果の数が、リクエストされた項目数以上の場合にのみ使用できます。 | クエリ | ✕ |
リクエストヘッダー
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string
応答
リクエストが成功すると、HTTP 200 OK
が返されます。
応答ヘッダー
Content-Type: application/json
X-Amzn-RequestId: string
HTTP 200 OK
{
"paginationContext": {
"nextToken": string,
"totalCount": integer
},
"evaluations": [
{
"id": string,
"status": string,
"startTimestamp": string,
"endTimestamp": string,
}
]
}
paginationContextオブジェクト
パラメーター | 説明 |
---|---|
nextToken |
前回のリクエストから引き続き結果を返すためのトークンです。NextTokenは、利用可能な結果の数が、リクエストされた項目数以上の場合にのみ使用できます。 |
totalCount |
リクエストを満たす項目の総数です。この数字は、この応答で返される項目の数よりも多い場合があります。 |
evaluationsオブジェクト
パラメーター | 説明 |
---|---|
id |
各機能評価を識別する一意のIDです。 |
status |
評価のステータスです。有効な値は、 PASSED、FAILED、IN_PROGRESS、ERRORです。 |
startTimestamp |
評価の開始時刻です。形式の例:yyyy-MM-dd'T'HH:mm:ss.SSS'Z |
endTimestamp |
評価の終了時刻です。形式の例:yyyy-MM-dd'T'HH:mm:ss.SSS'Z |
200以外の応答本文
{
"message": string
}
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
例
以下に、リクエストと応答の例を示します。
サンプルリクエスト
GET /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityEvaluations?maxResults=1
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 123-1234567-123
応答の例
HTTP 200 Ok
Content-Type: application/json
X-Amzn-RequestId: 123-1234567-123
{
"paginationContext": {
"nextToken": "879731421==",
"totalCount": 2
},
"evaluations": [
{
"startTimestamp": "2019-07-12T21:52:10.329Z",
"endTimestamp": "2019-07-12T21:55:10.329Z",
"status": "PASSED",
"id": "213123"
}
]
}
スマートホーム機能評価を取得する
スマートホーム機能評価の重要な情報とステータスを取得します。
リクエスト
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
HTTPメソッドとURIパス
GET /v1/skills/{skillId}/smartHome/testing/capabilityEvaluations/{evaluationId}
リクエストのパラメーター
パラメーター | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId |
一意のスキルIDです。 | パス | ◯ |
evaluationId |
各機能評価を識別する一意のIDです。 | パス | ◯ |
リクエストヘッダー
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string
応答
リクエストが成功すると、HTTP 200 OK
が返されます。
応答ヘッダー
Content-Type: application/json
X-Amzn-RequestId: string
応答本文の構造
{
"startTimestamp": string,
"endTimestamp": string,
"status": string,
"error": {
"message": string
},
"metrics": {
"totalTestCases": integer,
"passedTestCases": integer,
"failedTestCases": integer,
},
"input": {
"endpoint": {
"endpointId": string
},
"capabilityTestPlan": {
"id": string
},
"stage": string
}
}
応答本文の要素
パラメーター | 説明 |
---|---|
startTimestamp |
評価の開始時刻です。形式の例:yyyy-MM-dd'T'HH:mm:ss.SSS'Z |
endTimestamp |
評価の終了時刻です。形式の例:yyyy-MM-dd'T'HH:mm:ss.SSS'Z |
status |
評価のステータスです。有効な値は、 PASSED、FAILED、IN_PROGRESS、ERRORです。 |
errorオブジェクトの形式
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
metricsオブジェクト
パラメーター | 説明 |
---|---|
totalTestCases |
テストケースの総数です。 |
passedTestCases |
合格だったテストケースの数です。 |
failedTestCases |
不合格だったテストケースの数です。 |
inputオブジェクト
スマートホーム機能評価を作成するのリクエスト本文です。
200以外の応答本文
{
"message": string
}
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
例
以下に、リクエストと応答の例を示します。
サンプルリクエスト
GET /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityEvaluations/2131231
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 123-1234567-123
応答の例
Content-Type: application/json
X-Amzn-RequestId: 123-1234567-123
{
"startTimestamp": "2019-07-17T06:45:40.689Z",
"endTimestamp": "2019-07-17T06:55:40.689Z",
"status": "PASSED",
"metrics": {
"totalTestCases": 2,
"passedTestCases": 2,
"failedTestCases": 0
},
"input": {
"endpoint": {
"endpointId": "endpoint-001"
},
"capabilityTestPlan": {
"id": "test-plan-001"
},
"stage": "live"
}
}
スマートホーム機能評価の結果を取得する
テストケースについて評価を実行した結果を取得します。
リクエスト
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値にはLogin with Amazonから取得したアクセストークンが入ります。
HTTPメソッドとURIパス
GET /v1/skills/{skillId}/smartHome/testing/capabilityEvaluations/{evaluationId}/results?maxResults=<integer>&offset=<integer>
リクエストのパラメーター
パラメーター | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId |
一意のスキルIDです。 | パス | ◯ |
evaluationId |
各機能評価を識別する一意のIDです。 | パス | ◯ |
maxResults |
応答で返される項目の最大数です。このパラメーターを含めない場合、デフォルトの最大値は20です。このパラメーターを含める場合、応答に含まれる項目数は、指定した値を下回ることはあっても、上回ることはありません。1000を超える値は指定しないでください。 | クエリ | ✕ |
offSet |
返される結果ページのオフセットです。 | クエリ | ✕ |
リクエストヘッダー
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string
応答
リクエストが成功すると、HTTP 200 OK
が返されます。
応答ヘッダー
Content-Type: application/json
X-Amzn-RequestId: string
応答本文の構造
{
"paginationContext": {
"offset": integer,
"totalCount": integer
},
"testCaseResults": [
{
"name": string,
"status": string,
"expectedCapabilityStates": [
{
"namespace": string,
"name": string,
"comparison": string,
"value": object
}
],
"directive": {
"header": {
"namespace": string,
"name": string,
},
"payload": object
},
"actualCapabilityStates": [
{
"namespace": string,
"name": string,
"value": object
}
],
"error": {
"message": string
}
}
]
}
paginationContextオブジェクト
パラメーター | 説明 |
---|---|
offset |
返される結果ページのオフセットです。 |
totalCount |
リクエストを満たす項目の総数です。この数字は、この応答で返される項目の数よりも多い場合があります。 |
testCaseResultオブジェクト
パラメーター | 説明 |
---|---|
name |
テストケース名です。 |
status |
評価のステータスです。有効な値は、 PASSED、FAILED、ERRORです。 |
expectedCapabilityStateオブジェクト
パラメーター | 説明 |
---|---|
namespace |
機能のカテゴリーを表す文字列です。例: Alexa.PowerController |
name |
color、brightnessなどのプロパティ名です。 |
comparison |
機能状態を比較するための処理値です。値の例は、 EQUAL_TO、GREATER_THAN、LESS_THANです。 |
value |
プロパティの値です。 |
directiveオブジェクト
パラメーター | 説明 |
---|---|
namespace |
機能のカテゴリーを表す文字列です。例: Alexa.PowerController |
name |
TurnOn、TurnOffなどのディレクティブ名です。 |
actualCapabilityStateオブジェクト
パラメーター | 説明 |
---|---|
namespace |
機能のカテゴリーを表す文字列です。例: Alexa.PowerController |
name |
color、brightnessなどのプロパティ名です。 |
comparison |
機能状態を比較するための処理値です。値の例は、 EQUAL_TO、GREATER_THAN、LESS_THANです。 |
value |
color、brightnessなどのプロパティ名です。 |
errorオブジェクト
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
200以外の応答本文
{
"message": string
}
パラメーター | 説明 |
---|---|
message |
人が読める形式でのエラーの説明です。 |
例
以下に、リクエストと応答の例を示します。
サンプルリクエスト
GET /v1/skills/amzn1.ask.skill.12345/smartHome/testing/capabilityEvaluations/213123/results?maxResults=1
Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: 123-1234567-123
応答の例
HTTP 200 Ok
Content-Type: application/json
X-Amzn-RequestId: 123-1234567-123
{
"paginationContext": {
"offset": "1",
"totalCount": 2
},
"testCaseResults": [
{
"name": "LightingTestCase1",
"status": "PASSED",
"expectedCapabilityStates": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON"
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 20
}
],
"directive": {
"header": {
"namespace": "Alexa.BrightnessController",
"name": "setBrightness"
},
"payload": {
"brightness": 20
}
},
"actualCapabilityStates": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON"
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 20
}
]
}
]
}
エラー
リクエストが失敗すると、以下のいずれかが返されます。
200以外の応答の例外
ステータスコード | 説明 |
---|---|
HTTP 400 |
検証エラーです。 |
HTTP 401 |
認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
HTTP 403 |
リクエストされた操作は許可されていません。 |
HTTP 404 |
リクエストされたリソースが見つかりません。 |
HTTP 429 |
許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientId ごと、CustomerId ごとのリクエストの合計数があります。 |
HTTP 500 |
内部サーバーエラーです。 |