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



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

開発者アカウントでスキルに使用する独自のスロットタイプを作成するには、スロットタイプ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は次の手順で使用します。

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

CreateSlotType

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

リクエスト

HTTPメソッドとURIパス

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

リクエスト本文の構造

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

GetSlotType

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

UpdateSlotType

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

リクエスト

HTTPメソッドとURIパス

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

リクエスト本文の構造

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

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

応答

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

エラー

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

ListSlotTypes

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

正常に完了すると、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"
        }
      }
    }
  ]
}

応答本文のフィールド

エラー

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

DeleteSlotType

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

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

エラー

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

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"
  }
}

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

応答

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

応答本文のフィールド

エラー

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

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

GetSlotTypeBuildStatus

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

UpdateSlotTypeVersion

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

リクエスト

HTTPメソッドとURIパス

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

リクエスト本文の構造

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

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

応答

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

エラー

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

ListSlotTypeVersions

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

DeleteSlotTypeVersion

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

リクエスト

HTTPメソッドとURIパス

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

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

応答

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

エラー

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