スキルのベータテストAPI



スキルのベータテストAPI

スキルのベータテストAPIは非同期のAPIです。スキルの本番リリース前に、限定的なユーザーを対象にスキルのベータテストを設定するために使用できます。また、このAPIは、既存のスキルに加えた変更をテストするためにも使用できます。その場合、現在公開中のスキルを一般公開したままテストを行えます。スキルをテストしてフィードバックを提供するよう、友達、家族、ソーシャルネットワークの連絡先を始め、メールアドレスを知っている他のユーザーを招待できます。1つのテストにつき最大500人に招待を送信できます。テスターの追加と削除やテストの終了はいつでも行えます。テストサイクル中は常にスキルのフィードバックを得ることができ、本番リリースの前にスキルを修正できるので、コストを削減できます。スキルのベータテストは、優れたスキルを作成するのに役立ちます。

このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。

APIには、ベータテストの設定と管理に関連するものと、ベータテスターの管理に関連するものがあります。

ベータテストを作成する

ベータテストを作成します。

リクエスト

POST /skills/{skillId}/betaTest

リクエスト本文

feedbackEmailは、ベータテスターがフィードバックを送信できる宛先のEメールアドレスです。

{
  "feedbackEmail": "string"
}

応答

201 Successです。「Location」ヘッダーのリソースを追跡するURLが戻されます。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストを取得する

指定したスキルIDのベータテストに関する詳細を取得します。

リクエスト

GET /skills/{skillId}/betaTest

応答

200 Successです。

以下のように、ベータテストに関する情報を含むベータテストマニフェストが返されます。

{
  "expiryDate": "2018-09-26T07:14:13.378Z",
  "status": "IN_DRAFT",
  "feedbackEmail": "string",
  "invitationUrl": "string",
  "invitesRemaining": 0
}

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストを更新する

ベータテストの詳細を更新します。現時点では、フィードバックEメールのみを更新できます。

リクエスト

PUT /skills/{skillId}/betaTest

リクエスト本文

feedbackEmailの新しい値を含みます。ベータテスターがフィードバックを送信できる宛先のEメールアドレスです。

{
  "feedbackEmail": "string"
}

応答

204 Successです。コンテンツはありません。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストを開始する

スキルIDを指定してベータテストを開始します。テスト期間のカウントが開始されます。ベータテストを継続できる期間は90日間です。ただし、90日間を過ぎたら、新規にテストを作成できます。

リクエスト

POST /skills/{skillId}/betaTest/start

応答

202 Acceptです。「Location」ヘッダーのリソースを追跡するURLが戻されます。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストを終了する

スキルIDを指定してベータテストを終了します。デフォルトでは、90日を経過するとベータテストは終了します。このAPIを使うと、それより前に終了できます。

リクエスト

POST /skills/{skillId}/betaTest/end

応答

202 Acceptです。「Location」ヘッダーのリソースを追跡するURLが戻されます。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストのテスターリストを取得する

特定のベータテストに参加しているテスターのリストを取得します。関連トピック： 結果のページ分割とフィルタリング

リクエスト

GET /skills/{skillId}/betaTest/testers

応答

200 Successです。

以下のように、テスターのリストが戻されます。この場合、1人のテスターのみが表示されていますが、他のテスターも配列に含まれる可能性があります。ベータテストでは、最大500人までテスターを含めることができます。

{
  "testers": [
    {
      "emailId": "string",
      "associationDate": "2018-09-26T07:32:37.589Z",
      "isReminderAllowed": true,
      "invitationStatus": "ACCEPTED"
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストにテスターを追加する

既存のベータテストがある場合、500人の制限を超えない範囲でテスターを追加できます。

リクエスト

POST /skills/{skillId}/betaTest/testers/add

リクエスト本文

emailId値の配列を含みます。それぞれの値にはテスターのEメールアドレスが入ります。

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

応答

204 Successです。コンテンツはありません。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

ベータテストからテスターを削除する

テスターを既存のベータテストから削除します。

リクエスト

POST /skills/{skillId}/betaTest/testers/remove

リクエスト本文

emailId値の配列を含みます。それぞれの値にはテスターのEメールアドレスが入ります。

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

応答

204 Successです。コンテンツはありません。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

テスターにリマインダーを送信する

指定したAlexaスキルについて、ベータテストに参加しているテスターにリマインダーを送信します。システムは、各テスターに招待のEメールを送信し、承諾されると参加資格を追加します。

リクエスト

POST /skills/{skillId}/betaTest/testers/sendReminder

リクエスト本文

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

応答

204 Successです。コンテンツはありません。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

テスターにフィードバックをリクエストする

指定したAlexaスキルについて、ベータテストに参加しているテスターにフィードバックをリクエストします。システムがテスターに通知Eメールを送信し、これらのEメールでフィードバックをリクエストします。

リクエスト

POST /skills/{skillId}/betaTest/testers/requestFeedback

リクエスト本文

{
  "testers": [
    {
      "emailId": "string"
    }
  ]
}

応答

204 Successです。コンテンツはありません。

エラー

コード 説明
400 不正なリクエストです。
401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
404 リクエストされたリソースが見つかりません。
409 ターゲットリソースの現在の状態との競合が原因でリクエストを完了できませんでした。
429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
500 内部サーバーエラーです。

結果のページ分割とフィルタリング

リストを戻すAPI呼び出しについては、オプションでmaxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。このサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。リストを戻す一部のAPI呼び出しでは、フィルタリングを行う他のパラメーターも使用できます。

GET   /v1/skills/AAA-xxxx-yyyy/betaTest/testers?
     nextToken=VWB111111111
     &maxResults=5
パラメーター 説明
nextToken 文字列です。後続のAPI呼び出しでnextToken値を使い、maxResults件の結果が表示された後の次の値を取得できます。このトークンの有効期限は24時間です。
maxResults整数です。1回のAPI呼び出しで表示する結果の最大数です。デフォルトは100で、1～500までの範囲で指定できます。`nextToken`値を使って、後続のAPI呼び出しで残りの結果を取得できます。