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



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

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

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

参照ベースのカタログ管理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"
                    }
                }
            }
        ]
    }
}

次の表に、カタログ管理の操作に対応するAPIとコマンドを示します。

操作 API CLI
カタログの定義を作成します。 カタログを作成する create-model -catalog-definition
カタログのバージョンを作成します。 カタログバージョンを作成する create-catalog-version
カタログのステータスを更新します。ステータスの値は、in progress、failed、succeededのいずれかです。 カタログステータスを更新する catalog-update-status
カタログの定義を取得します。 カタログ定義を取得する get-model-catalog
カタログの定義を更新します。 カタログ定義を更新する update-catalog
カタログバージョンの説明を更新します。 カタログバージョンを更新する update-catalog-version
カタログのバージョンを取得します。 カタログバージョンを取得する get-catalog-versions
カタログの一覧を取得します。 カタログの一覧を取得する list-catalogs
カタログのバージョン一覧を表示します。 カタログバージョンの一覧を取得する list-catalog-versions
カタログを削除します。 カタログを削除する delete-catalog
カタログのバージョンを削除します。 カタログバージョンを削除する delete-catalog-version

カタログを作成する

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

リクエスト

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/{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/?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/{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}

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

パラメーター 必須 説明 位置 型
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}/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}/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 サービスを利用できません。

カタログを削除する

カタログを削除します。

リクエスト

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 サービスを利用できません。
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment