複数のスキルで使用可能なスロットタイプを作成する
スキルの音声対話モデルでは、ビルトインスロットタイプの使用と拡張が可能です。ビルトインスロットタイプの一覧については、スロットタイプリファレンスを参照してください。対話モデルの作成については、スキルの対話モデルの作成を参照してください。
開発者アカウントでスキルに使用する独自のスロットタイプを作成するには、スロットタイプAPIを使います。スロットタイプAPIを使って作成したスロットタイプは、参照ベースのカタログ管理、エンティティ解決の同義語とIDをサポートします。スキルの対話モデルで、ビルトインスロットタイプと同じ方法でスロットタイプを拡張できます。
たとえば、「南部料理レシピ」と「北西部の料理」というスキルを作成した場合、スロットタイプAPIを使って材料のスロットタイプを作り、このスロットタイプを両方のスキルで使うことができます。どちらかのスキルに追加の材料が必要になった場合、そのスキルで材料スロットタイプを拡張できます。たとえば、南部料理レシピに追加の材料が必要な場合は、南部料理レシピスキルで材料スロットタイプを拡張します。
- APIのエンドポイントとヘッダー
- スロットタイプ、スロットタイプバージョン、スロットタイプ定義とは
- スロットタイプAPIの使用
- CreateSlotType
- GetSlotType
- UpdateSlotType
- ListSlotTypes
- DeleteSlotType
- CreateSlotTypeVersion
- GetSlotTypeVersion
- GetSlotTypeBuildStatus
- UpdateSlotTypeVersion
- ListSlotTypeVersions
- DeleteSlotTypeVersion
APIのエンドポイントとヘッダー
このAPIのエンドポイントは、https://api.amazonalexa.com
です。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。
スロットタイプ、スロットタイプバージョン、スロットタイプ定義とは
スロットタイプとは、ユーザーが話す発話を構成する単語やフレーズを表すオブジェクトです。スロットタイプAPIを使ってスロットタイプを作成すると、APIはslotTypeId
とバージョンを返します。開発者アカウント1つあたり最大100個のスロットタイプ、スロットタイプごとに最大100のバージョンを作成できます。
同じバージョンのスロットタイプを変更することはできません。別のスロットタイプ値を指定する場合は、新しいバージョンを作成してください。スロットタイプAPIによる各バージョンの定義はほかのバージョンに依存しないため、使っていないバージョンは削除できます。スロットタイプのスキーマについては、CreateSlotTypeを参照してください。
スロットタイプの作成時にスキルは必要ありません。ただし、使うときにはスキルが必要です。スキルの対話モデルでスロットタイプを使うには、slotTypeId
とバージョンでスロットタイプを参照します。対話モデルでは、ビルトインスロットタイプと同じ方法でスロットタイプを拡張することもできます。
「スロットタイプ定義」とは、スロットタイプバージョンの値、同義語、IDを表します。新しいスロットタイプバージョンを追加した場合、スロットタイプ定義を作成する必要があります。スロットタイプ定義を作成するには、指定する値を使うことも、別の場所に保存した値のリストを参照することもできます。別の場所に保存した値の参照については、参照ベースのカタログ管理を参照してください。スロットタイプのスキーマについては、CreateSlotTypeVersionを参照してください。
スロットタイプAPIの使用
スロットタイプAPIは次の手順で使用します。
- スロットタイプを作成します。
- スロットタイプバージョンを作成します。このとき、スロットタイプ定義も作成します。
- スロットタイプのビルドステータスをトラッキングします。
- スロットを使うスキルを開きます。
- スキルの対話モデルで、
slotTypeId
とバージョンからスロットを参照します。 - 対話モデルでは、インラインでスロットタイプ値を追加することでスロットを拡張することもできます(任意)。
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 |
サービスを利用できません。 |