参照ベースのカタログ管理



参照ベースのカタログ管理

参照ベースのカタログ管理API（Reference-Based Catalog Management API）を使用すると、外部データソースを参照するカスタムスロットタイプを作成して、その値を利用することができます。これにより、Alexaスキルから独立した形で、スロットタイプ値のカタログを作成および管理できます。

API使用のために外部データソースのURLを指定すると、APIはカタログIDを返します。カスタムスロットタイプでは、カタログIDを指定して、スキルが外部データソースからスロットタイプ値を取得できるようにします。たとえば、レシピスキルを構築する場合、Alexaスキルのスロットタイプ値として食材を入力する代わりに、食材のリストを含む外部データソースのカタログIDを指定します。

また、ジョブを作成して、参照ベースのカタログを自動的に更新することもできます。自動更新ジョブの作成と管理については、更新ジョブの管理を参照してください。

概要

次の表に、カタログ管理に使用できるSMAPIアクションと対応するASK CLIコマンドを示します。

SMAPIアクション ASK CLIコマンド 説明
カタログを作成する create-interaction-model-catalog カタログの定義を作成します。
カタログバージョンを作成する create-interaction-model-catalog-version カタログのバージョンを作成します。
カタログステータスを取得する get-interaction-model-catalog-update-status カタログを作成または更新するための以前のリクエストのステータスを取得します。
カタログの一覧を取得する list-interaction-model-catalogs カタログの一覧を取得します。
カタログバージョンの一覧を取得する list-interaction-model-versions カタログのバージョンのリストを取得します。
カタログを取得する get-interaction-model-catalog-definition カタログの定義を取得します。
カタログバージョンを取得する get-interaction-model-catalog-version カタログの特定のバージョンを取得します。
カタログの値を取得する get-interaction-model-catalog-values カタログの値を取得します。
カタログを更新する update-interaction-model-catalog カタログの定義を更新します。
バージョン情報を更新する update-interaction-model-catalog-version カタログバージョンの説明を更新します。
カタログを削除する delete-interaction-model-catalog カタログを削除します。
カタログバージョンを削除する delete-interaction-model-catalog-version カタログのバージョンを削除します。

参照ベースのカタログ管理APIの使用方法

参照ベースのカタログ管理APIを使用するには、以下の手順を実行します。

  1. カタログの定義を作成します。
  2. 手順1のカタログIDを使用してカタログの バージョンを作成します。
  3. カタログバージョン作成のステータスを追跡します。指定できる値は、in progress（進行中）、failed（失敗）、succeeded（成功）です。
  4. 次の例のように、対話モデルでカタログIDとバージョンを使用します。

対応前：

{
    "languageModel": {
        "types": [
            {
                "name": "string",
                "samples": [
                    "string"
                ],
                "values": [
                    {
                        "id": "string",
                        "name": {
                            "value": "string",
                            "synonyms": [
                                "string"
                            ]
                        }
                    }
                ]
             }
        ]
    }
}

対応後：

{
    "languageModel": {
        "types": [
            {
                "name": "string",
                "samples": [
                    "string"
                ],
                "values": [
                    {
                        "id": "string",
                        "name": {
                            "value": "string",
                            "synonyms": [
                                "string"
                            ]
                        }
                    }
                ]
            },
            {
                "name": "string",
                "valueSupplier": {
                    "type": "CatalogValueSupplier",
                    "valueCatalog": {
                        "id": "string",
                        "version": "string"
                    }
                }
            }
        ]
    }
}

カタログを作成する

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

リクエスト

HTTPメソッドとURLパス

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

リクエスト本文の構造

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

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

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

応答

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

応答本文の構造

{
  "catalogId":"string"
}

応答本文のフィールド

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

エラー

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

応答本文の構造

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

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

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

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

リクエスト

HTTPメソッドとURLパス

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

リクエスト本文の構造

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

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

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

応答

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

応答本文のフィールド

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

エラー

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

応答本文の構造

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

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

カタログステータスを取得する

カタログを作成または更新するための以前のリクエストのステータスを取得します。ステータスの値は、in progress、failed、succeededのいずれかです。

リクエスト

HTTPメソッドとURLパス

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

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

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

エラー

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

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

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

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

リクエスト

HTTPメソッドとURLパス

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

応答本文のフィールド

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

エラー

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

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

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

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

リクエスト

HTTPメソッドとURLパス

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

応答本文のフィールド

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

エラー

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

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

カタログを取得する

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

リクエスト

HTTPメソッドとURLパス

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

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

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

応答

リクエストが成功すると、HTTP 200が返されます。次の例は、 HTTP 200 レスポンスを示しています。

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

応答本文のフィールド

パラメーター 必須 説明 位置 型
name ✕ カタログの名前です。 応答本文 文字列
description ✕ カタログの説明です（最大255文字）。 応答本文 オブジェクト

エラー

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

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

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

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

リクエスト

HTTPメソッドとURLパス

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

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

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

応答

リクエストが成功すると、HTTP 200が返されます。次の例は、 HTTP 200 レスポンスを示しています。

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

応答本文のフィールド

パラメーター 必須 説明 位置 型
type ✕ カタログの種類です。 応答本文 文字列
url ✕ カタログのURLです。 応答本文 文字列
description ✕ バージョンの説明です（最大255文字）。 応答本文 文字列
version ◯ catalogIdで識別されるカタログのバージョンを指定します。 応答本文 オブジェクト

エラー

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

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

カタログの値を取得する

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

リクエスト

HTTPメソッドとURLパス

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

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

パラメーター 必須 説明 位置 型
catalogId ◯ カタログサービスにより生成されたカタログを識別する一意のIDです。 パス 文字列
version ◯ catalogIdで識別されるカタログのバージョンを指定します。 パス 文字列
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"
        }
   }
}

応答本文のフィールド

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

エラー

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

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

カタログを更新する

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

リクエスト

HTTPメソッドとURLパス

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 404 見つかりません
HTTP 429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
HTTP 500 内部サーバーエラーです。
HTTP 503 サービスを利用できません。

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

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

リクエスト

HTTPメソッドとURLパス

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

リクエスト本文の構造

{
    "description": "string"
}

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

パラメーター 必須 説明 位置 型
catalogId ◯ 特定のカタログの一意のIDです。 リクエスト本文（任意） 文字列
version ◯ catalogIdで識別されるカタログのバージョンを指定します。 パス 文字列
description ✕ カタログの説明です（最大255文字）。 リクエスト本文（任意） 文字列

応答

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

エラー

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

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

カタログを削除する

カタログを削除します。

リクエスト

HTTPメソッドとURLパス

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 404 見つかりません
HTTP 429 許可されているリクエスト制限を超えています。制限の条件には、APIごと、ClientIdごと、CustomerIdごとのリクエストの合計数があります。
HTTP 500 内部サーバーエラーです。
HTTP 503 サービスを利用できません。

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

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

リクエスト

HTTPメソッドとURLパス

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

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

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

応答

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

エラー

リクエストが失敗すると、以下のいずれかのエラーが返されます。次の例は、 HTTP 400 検証エラーを示しています。

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