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



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

参照ベースのカタログ管理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 ◯(namedescriptionのいずれか) カタログの名前です。 リクエスト本文 文字列
description ◯(namedescriptionのいずれか) カタログ定義の説明です(最大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 サービスを利用できません。