スマートホーム評価API

スマートホーム評価API

Smart Home Evaluation API（スマートホーム評価API）を使用すると、照明機能やサーモスタット機能を使用するスキルに、自動化された一連のテストを実施できます。以下のような利点があります。

  • スキル開発の全体的な所要時間が短縮されます。
  • 手動でテストする労力を軽減することで、コストが削減されます。
  • 「Works with Alexa」認定にパスする可能性が高まります。
  • スキルの質が向上します。

前提条件

  1. 使用するAlexaアカウントがアカウントリンク済みであること。
  2. 使用する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 内部サーバーエラーです。