カスタムスロットタイプのカタログを参照ベースで管理する(API)



カスタムスロットタイプのカタログを参照ベースで管理する

参照ベースのカタログ管理では、既存のカタログを参照するURLを使ったカスタムスロットタイプを作成できます。カタログを作成したら、AlexaはURLからカタログを参照し、スロットタイプに値を取得することができます。

たとえば、レシピスキルの場合、この機能を使ってシェフ名のリストを取得できます。SMAPIとスキルビルダーを使って名前を個々に入力し、手動でデータソースの同期をとる必要はありません。

カタログ管理を始める

  1. カタログの定義を作成します。
  2. ステップ1のカタログIDを使ってカタログのバージョンを作成します。
  3. カタログバージョン作成のステータス(in progress、failed、succeeded)を追跡します。

カタログを作成する

カタログの定義を作成します。

リクエスト

POST /v1/skills/api/custom/interactionModel/catalogs/

リクエスト本文の構造

{
    "vendorid": "string",
      "catalog": {
          "name": "string",
          "description": "string"
      }
}

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

パラメーター 必須 説明 位置
description カタログの説明です(最大255文字)。 リクエスト本文(任意) 文字列
name カタログの名前です。 リクエスト本文 文字列
vendorid リクエスターのベンダーIDです。 リクエスト本文 文字列

応答

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

応答本文の構造

{
  "catalogId":"string"
}

エラー

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

応答本文の構造

以下は、HTTP 400検証エラーの例です。

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

応答のパラメーター

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 応答の本文 文字列

カタログバージョンデータを作成する

カタログのバージョンを作成します。

リクエスト

POST /skills/api/custom/interactionModel/catalogs/{catalogId}/versions

リクエスト本文の構造

例:

{
      "source": {
          "type": "URL",
          "url": "string"
      },
      "description": "string"
}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
source カタログを形成する入力データのソースです。 リクエスト本文 文字列
type カタログの種類です。 リクエスト本文 文字列
url 取り込むカタログへのURL参照です。 リクエスト本文 文字列

応答

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

エラー

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

応答本文の構造

以下は、HTTP 400検証エラーの例です。

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

応答のパラメーター

パラメーター 必須 説明 位置
location 追跡するカタログステータスの場所です。 応答のヘッダー 文字列

カタログの最新ステータス

カタログの最新ステータスを取得します。ステータスの値は、in progress、failed、succeededのいずれかです。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/updateRequest/{updateRequestId}`

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
updateRequested 新しいバージョンの作成プロセスを識別する一意のIDです。 リクエストのパス 文字列

応答

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

応答本文の構造

{
  "updateRequest": {
       "status": "string",
       "version": "string",
       "error":  [
           {
              "code": "string",
              "message":  "string"
           }
       ]
   }
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
status カタログのステータスです。ステータスの値は、in progress、failed、succeededのいずれかです。 応答の本文 文字列
version 返されるエンティティのバージョンIDです。 応答の本文 文字列
error FAILUREの場合、エラーにはエラーコードとメッセージが含まれます。 応答の本文 文字列

カタログバージョンの一覧を取得する

カタログバージョンの一覧を取得します。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions?maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}&sortField={sortField}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
maxResults 返されるバージョンの数です。 リクエストのパス(任意) 文字列
nextToken 結果の次のページを照会することができます。 リクエストのパス(任意) 文字列
sortDirection 並べ替え順序です。デフォルトは降順です。有効な値は、昇順の場合asc、降順の場合descです。値では大文字と小文字が区別されます。 リクエストのパス(任意) 文字列

応答

リクエストが成功すると、HTTP 200が返されます。以下は、HTTP 200応答の例です。

{
   "isTruncated": boolean,
   "nextToken": "string",
   "totalCount": integer,
   "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
   },
   "catalogVersions": [
       {
          "version": "string",
          "description": "string",
          "creationTime": "string",
          "_links": {
              "next": {
                  "href": "next_href"
              },
              "self": {
                  "href": "current_href"
              }
          }
       }
   ]
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
nextToken 結果の次のページを照会することができます。 応答の本文 文字列
isTruncated 返す結果がこれ以上ない場合、falseを返します。 応答の本文 文字列
description バージョンの説明です(最大255文字)。 応答の本文 文字列
totalCount カタログバージョンの合計数です。 応答の本文 文字列
_links APIナビゲーションのリンクです。 応答の本文 文字列

カタログの一覧を取得する

カタログの一覧を取得します。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/?vendorid={vendorid}&maxResults={maxResults}&nextToken={nextToken}&sortDirection={sortDirection}`

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

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

応答

リクエストが成功すると、HTTP 200が返されます。以下は、HTTP 200応答の例です。

{
   "isTruncated": boolean,
   "nextToken": "string",
   "totalCount": integer,
   "_links": {
        "next": {
            "href": "next_href"
        },
        "self": {
            "href": "current_href"
        }
   },
   "catalogs": [
       {
          "catalogId": "string",
          "description": "string",
          "name": "string",
          "_links": {
              "next": {
                  "href": "next_href"
              },
              "self": {
                  "href": "current_href"
              }
          }
       }
   ]
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
nextToken 結果の次のページを照会することができます。 応答の本文 文字列
isTruncated 返す結果がこれ以上ない場合、falseを返します。 応答の本文 文字列
description バージョンの説明です(最大255文字)。 応答の本文 文字列
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 応答の本文 文字列
totalCount カタログバージョンの合計数です。 応答の本文 文字列
_links APIナビゲーションのリンクです。 応答の本文 文字列

カタログバージョンを取得する

カタログバージョンを取得します。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
version カタログIDで識別されるカタログのバージョンを指定します。 リクエストのパス 文字列

応答

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

以下は、HTTP 200応答の例です。

{
       "source": {
          "type": "string",
          "url": "string"
       },
       "version": "string",
       "description": "string",
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
type カタログの種類です。 応答の本文 文字列
url 取り込むカタログへのURL参照です。 応答の本文 文字列
description バージョンの説明です(最大255文字)。 応答の本文 文字列
version カタログIDで識別されるカタログのバージョンを指定します。 応答の本文 文字列

カタログ定義を取得する

カタログの定義を取得します。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列

応答

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

以下は、HTTP 200応答の例です。

{
       "catalog": {
          "name": "string",
          "description": "string"      
       },
       "createTime": "string",
       "totalVersions": "string"
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
name カタログの名前です。 応答の本文 文字列
description カタログの説明です(最大255文字)。 応答の本文 文字列

カタログの値

カタログの値を取得します。

リクエスト

GET /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/values?nextToken={nextToken}&maxResults={maxResults}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
version カタログIDで識別されるカタログのバージョンを指定します。 リクエストのパス 文字列
maxResults 返されるバージョンの数です。 リクエストのパス(任意) 文字列
nextToken 結果の次のページを照会することができます。 リクエストのパス(任意) 文字列

応答

リクエストが成功すると、HTTP 200が返されます。以下は、HTTP 200応答の例です。

{
  "values":[
       {
            "id": "string",
            "name": {
                  "value": "string",
                  "synonyms": [
                       "string"
                  ]
            }
        }
   ],
   "isTruncated": boolean,
   "nextToken": "string",
   "totalCount": integer,
   "_links": {
        "next": {
           "href": "next_href"
        },
        "self": {
           "href": "current_href"
        }
   }
}

エラー

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

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

応答のパラメーター

パラメーター 必須 説明 位置
nextToken 結果の次のページを照会することができます。 応答の本文 文字列
isTruncated 返す結果がこれ以上ない場合、falseを返します。 応答の本文 文字列
totalCount カタログバージョンの合計数です。 応答の本文 文字列
_links APIナビゲーションのリンクです。 応答の本文 文字列

カタログ定義を更新する

カタログの定義を更新します。

リクエスト

POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/update

リクエスト本文の構造

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

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
name 〇(name、descriptionのいずれか) カタログの名前です。 リクエスト本文 文字列
description 〇(name、descriptionのいずれか) カタログ定義の説明です(最大255文字)。 リクエスト本文(任意) 文字列

応答

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

エラー

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

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

バージョン情報を更新する

カタログバージョンの定義を更新します。

リクエスト

POST /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}/update

リクエスト本文の構造

{
    "description": "string"
}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエスト本文(任意) 文字列
version カタログIDで識別されるカタログのバージョンを指定します。 リクエストのパス 文字列
description カタログの説明です(最大255文字)。 リクエスト本文(任意) 文字列

応答

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

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

カタログバージョンを削除する

カタログバージョンを削除します。

リクエスト

DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}/versions/{version}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列
version カタログIDで識別されるカタログのバージョンを指定します。 リクエストのパス 文字列

応答

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

エラー

リクエストが失敗すると、以下の表に記載したエラーのいずれかが返されます。 以下は、HTTP 400検証エラーの例です。

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

カタログを削除する

カタログを削除します。

リクエスト

DELETE /v1/skills/api/custom/interactionModel/catalogs/{catalogId}

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

パラメーター 必須 説明 位置
catalogId カタログサービスにより生成されたカタログを識別する一意のIDです。 リクエストのパス 文字列

応答

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

エラー

リクエストが失敗すると、以下の表に記載したエラーのいずれかが返されます。 以下は、HTTP 400検証エラーの例です。

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