複数のスキルで使用可能なスロットタイプを作成する



複数のスキルで使用するスロットタイプを作成する

スキルの音声対話モデルでは、ビルトインスロットタイプの使用と拡張が可能です。ビルトインスロットタイプの一覧については、スロットタイプリファレンスを参照してください。対話モデルの作成については、スキルの対話モデルの作成を参照してください。

開発者アカウントでスキルに使用する独自のスロットタイプを作成するには、スロットタイプAPIを使います。スロットタイプAPIを使って作成したスロットタイプは、参照ベースのカタログ管理、エンティティ解決の同義語とIDをサポートします。スキルの対話モデルで、ビルトインスロットタイプと同じ方法でスロットタイプを拡張できます。

たとえば、「南部料理レシピ」と「北西部の料理」というスキルを作成した場合、スロットタイプAPIを使って材料のスロットタイプを作り、このスロットタイプを両方のスキルで使うことができます。どちらかのスキルに追加の材料が必要になった場合、そのスキルで材料スロットタイプを拡張できます。たとえば、南部料理レシピに追加の材料が必要な場合は、南部料理レシピスキルで材料スロットタイプを拡張します。

APIのエンドポイントとヘッダー

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

スロットタイプ、スロットタイプバージョン、スロットタイプ定義とは

スロットタイプとは、ユーザーが話す発話を構成する単語やフレーズを表すオブジェクトです。スロットタイプAPIを使ってスロットタイプを作成すると、APIはslotTypeIdとバージョンを返します。開発者アカウント1つあたり最大100個のスロットタイプ、スロットタイプごとに最大100のバージョンを作成できます。

同じバージョンのスロットタイプを変更することはできません。別のスロットタイプ値を指定する場合は、新しいバージョンを作成してください。スロットタイプAPIによる各バージョンの定義はほかのバージョンに依存しないため、使っていないバージョンは削除できます。スロットタイプのスキーマについては、CreateSlotTypeを参照してください。

スロットタイプの作成時にスキルは必要ありません。ただし、使うときにはスキルが必要です。スキルの対話モデルでスロットタイプを使うには、slotTypeIdとバージョンでスロットタイプを参照します。対話モデルでは、ビルトインスロットタイプと同じ方法でスロットタイプを拡張することもできます。

「スロットタイプ定義」とは、スロットタイプバージョンの値、同義語、IDを表します。新しいスロットタイプバージョンを追加した場合、スロットタイプ定義を作成する必要があります。スロットタイプ定義を作成するには、指定する値を使うことも、別の場所に保存した値のリストを参照することもできます。別の場所に保存した値の参照については、参照ベースのカタログ管理を参照してください。スロットタイプのスキーマについては、CreateSlotTypeVersionを参照してください。

スロットタイプAPIの使用

スロットタイプAPIは次の手順で使用します。

  1. スロットタイプを作成します。
  2. スロットタイプバージョンを作成します。このとき、スロットタイプ定義も作成します。
  3. スロットタイプのビルドステータスをトラッキングします。
  4. スロットを使うスキルを開きます。
  5. スキルの対話モデルで、slotTypeIdとバージョンからスロットを参照します。
  6. 対話モデルでは、インラインでスロットタイプ値を追加することでスロットを拡張することもできます（任意）。

CreateSlotType

スロットタイプを作成します。スロットタイプは、スロットタイプのバージョンを保持するコンテナです。

リクエスト

HTTPメソッドとURIパス

POST /v1/skills/api/custom/interactionModel/slotTypes/

リクエスト本文の構造

{
     "vendorId": "string",
     "slotType": {
         "name": "string",
         "description": "string"
     }
  }

リクエストのパラメーター

パラメーター 必須 説明 位置 型
vendorId ◯ 一意のベンダーIDです。 本文 文字列
name ◯ スロットタイプの名前です。最大255文字で指定します。 本文 文字列
description ✕ スロットの説明です。最大255文字で指定します。 本文 文字列

応答

正常に完了すると、HTTP 200が返されます。

応答本文の構造

{
  "slotType": {
    "id": "string"
  }
}

応答本文のフィールド

フィールド 説明 位置 型
id スロットタイプの識別に使うIDです。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

GetSlotType

指定したslotTypeIdのスロットタイプを返します。

リクエスト

HTTPメソッドとURIパス

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列

応答

正常に完了すると、HTTP 200が返されます。

応答本文の構造

{
  "slotType": {
    "name": "string",
    "description": "string"      
  }
}

応答本文のフィールド

フィールド 説明 位置 型
name スロットタイプの名前です。最大255文字で指定します。 本文 文字列
description スロットの説明です。最大255文字で指定します。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

UpdateSlotType

スロットタイプの説明を更新します。説明を指定しない場合、既存の説明が削除されます。

リクエスト

HTTPメソッドとURIパス

POST /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/update

リクエスト本文の構造

{
  "slotType": {
    "description": "string"
  }
}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
description ✕ スロットの説明です。最大255文字で指定します。 本文 文字列

応答

リクエストが成功すると、HTTP 204が返されます。

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

ListSlotTypes

開発者アカウントで作成したすべてのスロットタイプのリストを返します。

リクエスト

HTTPメソッドとURIパス

GET /v1/skills/api/custom/interactionModel/slotTypes?vendorId={vendorId}&maxResults={num}&nextToken={nextToken}&sortDirection={sortDirection}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
vendorId ◯ 一意のベンダーIDです。 クエリパラメーター 文字列
maxResults ✕ 返されるバージョンの最大数です。 クエリパラメーター 文字列
nextToken ✕ ユーザーは結果の次のページを照会することができます。 クエリパラメーター 文字列
sortDirection ✕ 並べ替え順序です。デフォルトは降順です。有効な値は、昇順の場合asc、降順の場合descです。値では大文字と小文字が区別されます。 クエリパラメーター 文字列

応答

正常に完了すると、HTTP 200が返されます。

応答本文の構造

{
  "nextToken": "string",
  "_links": {
    "next": {
      "href": "next_href"
    },
    "self": {
      "href": "current_href"
    }
  },
  "slotTypes": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "_links": {
        "self": {
          "href": "current_href"
        }
      }
    }
  ]
}

応答本文のフィールド

フィールド 説明 位置 型
nextToken ユーザーは結果の次のページを照会することができます。 本文 文字列
_links Hypertext Application Languageリンクで、リソース間を移動するために使用します。 本文 オブジェクト
id 一意のスロットタイプIDです。 本文 文字列
name スロットタイプの名前です。最大255文字で指定します。 本文 文字列
description スロットの説明です。最大255文字で指定します。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

ステータスコード 説明
HTTP 400 検証エラーです。
HTTP 401 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。
HTTP 403 リクエストされた操作は許可されていません。
HTTP 429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
HTTP 500 内部サーバーエラーです。
HTTP 503 サービスを利用できません。

DeleteSlotType

スロットタイプを削除します。

リクエスト

HTTPメソッドとURIパス

DELETE /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列

応答

リクエストが成功すると、HTTP 204が返されます。

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

CreateSlotTypeVersion

スロットタイプの新しいバージョンを作成します。各スロットタイプバージョンはスロットタイプに属します。スロットタイプのバージョンにはスロットタイプの定義が含まれます。定義ではスロットタイプの値を指定するか、スロットタイプ値を格納した外部データソースを参照します。

リクエスト

HTTPメソッドとURIパス

POST /skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions

リクエスト本文の構造

以下は、definitionにスロットタイプの値と関連する同義語を指定した場合のリクエスト本文の構造です。

{
  "slotType": {
    "definition":{
      "valueSupplier": {
        "type": "InlineValueSupplier",
        "values": [
          {
            "id": "kobe",
            "name": {
              "value": "神戸市",
              "synonyms": [
                "神戸"
              ]
            }
          }
        ]
      }
    },
    "description": "string"
  }
}

以下は、definitionがスロットタイプ値を指すcatalogIdを参照する場合のリクエスト本文の構造です。詳細については、参照ベースのカタログ管理を参照してください。

{
  "slotType": {
    "definition":{
      "valueSupplier": {
        "type": "CatalogValueSupplier",
        "valueCatalog": {
          "catalogId": "amzn1.ask.interactionModel.catalog.123",
          "version": "string"
        }
      }
    },
    "description": "string"
  }
}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
definition ◯ スロットタイプ値の定義を含むJSONオブジェクトです。 本文 オブジェクト
description ✕ スロットタイプバージョンの説明です。最大255文字で指定します。 本文 文字列

応答

リクエストが成功すると、HTTP 202が返されます。

応答本文のフィールド

フィールド 説明 位置 型
location GetSlotTypeBuildStatusに渡すupdateRequestIdを示すヘッダーです。 ヘッダー 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

GetSlotTypeVersion

指定したslotTypeIdとバージョンのスロットタイプデータを返します。

リクエスト

HTTPメソッドとURIパス

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/~current

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/~latest

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
version ◯ slotTypeIdで識別されるタイプの特定バージョンです。 パス 文字列

応答

リクエストが成功すると、HTTP 200が返されます。

応答本文の構造

{
  "slotType": {
    "id": "string",
    "definition": {...},
    "version": "string",
    "description": "string"
  }
}

応答本文のフィールド

フィールド 説明 位置 型
id スロットタイプIDです。 本文 文字列
definition 値を含むスロットタイプバージョン定義のJSONオブジェクトを返します。 本文 オブジェクト
description バージョンの説明です。 本文 文字列
version スロットタイプのバージョンです。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

GetSlotTypeBuildStatus

指定したslotTypeIdのビルドステータスを返します。ビルドステータスの有効な値は、succeeded、in progress、failedのいずれかです。

リクエスト

HTTPメソッドとURIパス

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/updateRequest/{updateRequestId}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
updateRequestId ◯ CreateSlotTypeVersion応答のlocationヘッダーから取得するIDです。 パス 文字列

応答

リクエストが成功すると、HTTP 200が返されます。

応答本文の構造

{
  "updateRequest": {
    "status": "string",
    "version": "string",
  }
}

応答本文のフィールド

フィールド 説明 位置 型
status スロットタイプのステータスです。有効な値は、succeeded、in progress、failedのいずれかです。 本文 文字列
version 返されるエンティティのバージョンIDです。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

UpdateSlotTypeVersion

スロットタイプバージョンの説明を更新します。説明を指定しない場合、既存の説明が削除されます。

リクエスト

HTTPメソッドとURIパス

POST /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}/update

リクエスト本文の構造

{
  "slotType": {
    "description": "string"
  }
}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
version ◯ スロットタイプのバージョンです。 パス 文字列
description ✕ スロットの説明です。最大255文字で指定します。 本文 文字列

応答

リクエストが成功すると、HTTP 204が返されます。

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

ListSlotTypeVersions

指定したslotTypeIdのスロットタイプバージョンをすべて表示します。

リクエスト

HTTPメソッドとURIパス

GET /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions?maxResults={num}&nextToken={nextToken}&sortDirection={sortDirection}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
maxResults ✕ 返されるバージョンの最大数です。 クエリパラメーター 文字列
nextToken ✕ ユーザーは結果の次のページを照会することができます。 クエリパラメーター 文字列
sortDirection ✕ 並べ替え順序です。デフォルトは降順です。有効な値は、昇順の場合asc、降順の場合descです。値では大文字と小文字が区別されます。 クエリパラメーター 文字列

応答

リクエストが成功すると、HTTP 200が返されます。

応答本文の構造

{
  "nextToken": "string",
  "_links": {
    "next": {
      "href": "next_href"
    },
    "self": {
      "href": "current_href"
    }
  },
  "slotTypeVersions": [
    {
      "version": "string", 
      "description": "string",
      "_links": {
        "self": {
          "href": "current_href"
        }
      }
    }
  ]
}

応答本文のフィールド

フィールド 説明 位置 型
nextToken ユーザーは結果の次のページを照会することができます。 本文 文字列
totalCount リクエストされたタイプのバージョン数です。 本文 文字列
_links Hypertext Application Languageリンクで、リソース間を移動するために使用します。 本文 オブジェクト
version スロットタイプのバージョンです。 本文 文字列
description 特定のバージョンの説明です。最大255文字で指定します。 本文 文字列

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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

DeleteSlotTypeVersion

特定のスロットタイプバージョンを削除します。スキルがそのバージョンを使っている場合、リクエストは失敗します。

リクエスト

HTTPメソッドとURIパス

DELETE /v1/skills/api/custom/interactionModel/slotTypes/{slotTypeId}/versions/{version}

リクエストのパラメーター

パラメーター 必須 説明 位置 型
slotTypeId ◯ 一意のスロットタイプIDです。 パス 文字列
version ◯ スロットタイプのバージョンです。 パス 文字列

応答

リクエストが成功すると、HTTP 204が返されます。

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。

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