カタログURLリファレンス



カタログURLリファレンス

Catalog URL Reference APIでは、既存のカタログを参照するURLを使ったカスタムスロットタイプを作成できます。Catalog Content Upload APIを使用してカタログを作成し、AlexaがそのURLからスロットタイプの値を参照できます。

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

Catalog URL Reference APIの使用

カタログ管理を始める

  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 404 見つかりません。
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です。 リクエストのパス 文字列
updateRequestId 新しいバージョンの作成プロセスを識別する一意のIDです。 リクエストのパス 文字列

応答

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

応答本文の構造

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

エラー

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

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