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



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

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

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

• 概要
  • 参照ベースのカタログ管理APIの使用方法
• カタログを作成する
  • リクエスト
  • 応答
• カタログバージョンを作成する
  • リクエスト
  • 応答
• カタログステータスを取得する
  • リクエスト
  • 応答
• カタログの一覧を取得する
  • リクエスト
  • 応答
• カタログバージョンの一覧を取得する
  • リクエスト
  • 応答
• カタログを取得する
  • リクエスト
  • 応答
• カタログバージョンを取得する
  • リクエスト
  • 応答
• カタログの値を取得する
  • リクエスト
  • 応答
• カタログを更新する
  • リクエスト
  • 応答
• バージョン情報を更新する
  • リクエスト
  • 応答
• カタログを削除する
  • リクエスト
  • 応答
• カタログバージョンを削除する
  • リクエスト
  • 応答

概要

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

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

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

1. カタログの定義を作成します。
2. 手順1のカタログIDを使用してカタログの バージョンを作成します。
   注： URLはHTTPS経由でアクセス可能であり、カタログはJSON形式である必要があります。カタログにスロット値の同義語を含めることもできます。カタログの形式については、GitHubのサンプルCatalog Entities Demoを参照してください。
3. カタログバージョン作成のステータスを追跡します。指定できる値は、in progress（進行中）、failed（失敗）、succeeded（成功）です。
   ヒント： catalogIdとversionを、スキルを作成するときのスロットタイプの参照に使います。
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"
      }
}

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

応答

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

応答本文の構造

{
  "catalogId":"string"
}

応答本文のフィールド

エラー

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

応答本文の構造

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

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}

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

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

リクエスト

HTTPメソッドとURLパス

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

リクエスト本文の構造

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

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

応答

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

応答本文のフィールド

エラー

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

応答本文の構造

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

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}

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

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

リクエスト

HTTPメソッドとURLパス

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

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

応答

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

応答本文の構造

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

応答本文のフィールド

エラー

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

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

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

リクエスト

HTTPメソッドとURLパス

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

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

応答

リクエストが成功すると、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メソッドとURLパス

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

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

応答

リクエストが成功すると、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メソッドとURLパス

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

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

応答

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

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

応答本文のフィールド

エラー

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

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

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

リクエスト

HTTPメソッドとURLパス

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

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

応答

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

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

応答本文のフィールド

エラー

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

カタログの値を取得する

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

リクエスト

HTTPメソッドとURLパス

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

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

応答

リクエストが成功すると、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メソッドとURLパス

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

リクエスト本文の構造

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

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

応答

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

エラー

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

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

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

リクエスト

HTTPメソッドとURLパス

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

リクエスト本文の構造

{
    "description": "string"
}

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

応答

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

エラー

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

カタログを削除する

カタログを削除します。

リクエスト

HTTPメソッドとURLパス

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

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

応答

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

エラー

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

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}

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

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

リクエスト

HTTPメソッドとURLパス

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

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

応答

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

エラー

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

{
  "error":  [
     {
        "code": "string",
        "message":  "string"
     }
  ]
}