スキルの管理

Note: Sign in to the developer console to build or publish your skill.

スキルリソース操作（スキル管理API）

このドキュメントでは、スキルリソースに関連するすべてのAPI操作について説明します。このAPIのエンドポイントは、https://api.fe.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。

The ASK CLIコマンドリファレンスもスキル管理APIを使用しますが、コマンドラインインターフェースからのみです。

スキル情報の取得
スキルの作成
既存スキルの更新
スキルのステータスの取得
スキルリストの表示
スキルの削除

スキル情報の取得

指定したスキルのマニフェストを取得します。

リクエスト

GET  /v1/skills/{skillId}/stages/{stage}/manifest

パラメーター

フィールド	説明	パラメーターの型	必須
`skillId`	一意のスキルIDです。	パス	◯
`stage`	スキルのステージを表示します。値は`development`または`live` （大文字小文字の区別あり）のいずれかです。	パス	◯

Response

HTTP/1.1 200 response contains the latest version of skill manifest.

ヘッダー

ETag: <etag_value>

本文

マニフェストオブジェクトです。

例外

HTTP/1.1 303 See Other

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 403 The operation being requested is not allowed.

HTTP/1.1 404 The resource being requested is not found.

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

スキルの作成

指定したvendorIdのスキル作成リクエストを送信します。非同期操作のため、サーバーがリクエストを処理するとエラーが発生する場合があります。このリクエストのステータスを追跡するには、Locationヘッダーを使用します。

リクエスト

POST /v1/skills

本文

本文にはvendorIdとスキルマニフェストに記述されているmanifestオブジェクトが含まれます。以下に例を示します。

{
    "vendorId": "MT25O3ZVSAXZOAX",
    "manifest": {
        "publishingInformation": {
            "locales": {
                "ja-JP": {
                    "summary": "Alexaスキルのサンプルです。",
                    "examplePhrases": [
                        "アレクサ、サンプルスキルを開いて。",
                        "アレクサ、キッチンのライトをオンにして。",
                        "アレクサ、キッチンのライトを点けて。"
                    ],
                    "keywords": [
                        "Smart Home",
                        "Lights",
                        "Smart Devices"
                    ],
                    "name": "サンプルのカスタムスキル名です。",
                    "description": "このスキルには基本および高度なスマートデバイス管理機能を提供します。"
                }
            },
            "isAvailableWorldwide": false,
            "testingInstructions": "1) 'アレクサ、デバイスを検出して'と言って 2) Say 'アレクサ、サンプルのライトをオンにして'と言って",
            "category": "SMART_HOME",
            "distributionCountries": [
                "US",
                "JP"
            ]
        },
        "apis": {
            "custom": {
                "endpoint": {
                    "uri": "arn:aws:lambda:us-east-1:032174894474:function:ask-custom-custome_cert"
                }
            }
        },
        "manifestVersion": "1.0",
        "privacyAndCompliance": {
            "allowsPurchases": false,
            "locales": {
                "ja-JP": {
                    "termsOfUseUrl": "http://www.termsofuse.sampleskill.com",
                    "privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com"
                }
            },
            "isExportCompliant": true,
            "isChildDirected": false,
            "usesPersonalInfo": false
        }
    }
}

応答

HTTP/1.1 202 Accepted; Returns a URL to track the status in `Location` header.

ヘッダー

Location: <Returns a relative URL to track the status>

本文

{
  "skillId": "{skillId}"
}

ステータス202は、処理リクエストが正常に受け付けられたことを意味します。返されたskillIdは、GET /v1/skills/{skillId}/statusの参照として使用されます。ワークフローが非同期なため、GET /v1/skills/{skillId}/statusは、スキルが正常に作成できるまで、最初のPOST /v1/skillsリクエストの後、短時間404応答を返す場合があります。

つまり、スキル作成リクエストを送信すると、次にGET /v1/skills/{skillId}/statusを使用して、スキルが正常に作成されたかどうか検証するためにスキルのステータスを確認しなければなりません。

例外

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 403 The operation being requested is not allowed.

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

既存スキルの更新

指定されたスキルIDに関連付けられたスキルマニフェストを更新します。

リクエスト

PUT /v1/skills/{skillId}/stages/{stage}/manifest

パラメーター

フィールド	説明	パラメーターの型	必須
`skillId`	一意のスキルIDです。	パス	◯
`stage`	スキルのステージです。有効な値は、`development`（大文字小文字の区別あり）です。	パス	◯

ヘッダー

If-Match: <etag_value>

本文

スキルマニフェストのmanifestオブジェクトを参照してください。

応答

HTTP/1.1 202 Accepted; Returns a URL to track the status in 'Location' header.

ヘッダー

Location: <Returns a relative URL to track the status>

例外

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 403 The operation being requested is not allowed.

HTTP/1.1 404 The resource being requested is not found.

HTTP/1.1 409 The request could not be completed due to a conflict with the current state of the target resource.

HTTP/1.1 412 Precondition failed

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

スキルのステータスの取得

指定したスキルリソースのステータスを取得し、任意でリソースごとにフィルタリングして、リソースが正常にビルドされたかどうかを確認できます。スキルが正常にビルドされたかどうかを検証するために、スキルを作成または更新した後にこのAPIを使用します。

応答で返されるビルドのステップについて詳しくは、モデルの保存とビルドを参照してください。

リクエスト

GET /v1/skills/{skillId}/status?resource={resource1}&resource={resource2}

各リソースのパラメーターは任意のフィルターです。

パラメーター

フィールド	説明	パラメーターの型	必須
`skillId`	一意のスキルIDです。	パス	◯
`resource`	有効な値は、`interactionModel`、`manifest`のいずれか、または両方です。	クエリーパラメーター	✕

応答

応答は、スキルリソースと指定されたサブリソースのステータスを返します。

HTTP/1.1 200

本文

以下の例では、応答本文の構造を示します。

{
  "manifest": {
    "eTag": "ahsdfuhq34894hjk",
    "lastUpdateRequest": {
      "status": "FAILED",
      "errors": [
        {
          "message": "小さいアイコンまたは大きいアイコンの有効な画像を含む、有効なURLを入力してください"
        },
        {
          "message": "小さいアイコンのサイズは108x108です。大きいアイコンのサイズは512x512です。"
        }
      ],
      "warnings": []
    }
  },
  "interactionModel": {
    "ja-JP": {
      "eTag": "agasguhq34894hjk",
      "lastUpdateRequest": {
        "status": "SUCCEEDED",
        "errors": [],
        "warnings": [],
        "buildDetails": {
          "steps": [
            {
              "name": "DIALOG_MODEL_BUILD | LANGUAGE_MODEL_QUICK_BUILD | LANGUAGE_MODEL_FULL_BUILD",
              "status": "IN_PROGRESS | SUCCEEDED | FAILED",
              "errors": [
                {
                  "code": "ErrorCode",
                  "message": "これはエラーメッセージです"
                }
              ]
            }
          ]
        }
      },
      "errors": [],
      "warnings": [],
      "version": "1"
    },
    "en-GB": {
      "eTag": "ahsadfahq34894hjk",
      "lastUpdateRequest": {
        "status": "IN_PROGRESS",
        "errors": [],
        "warnings": [],
        "buildDetails": {
          "steps": [
            {
              "name": "DIALOG_MODEL_BUILD | LANGUAGE_MODEL_QUICK_BUILD | LANGUAGE_MODEL_FULL_BUILD",
              "status": "IN_PROGRESS | SUCCEEDED | FAILED",
              "errors": [
                {
                  "code": "ErrorCode",
                  "message": "これはエラーメッセージです"
                }
              ]
            }
          ]
        }
      },
      "errors": [],
      "warnings": [],
      "version": "1"
    }
  }
}

例外

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 403 The operation being requested is not allowed.

HTTP/1.1 404 The resource being requested is not found.

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

スキルリストの表示

指定したvendorIdのスキルリストを表示します。オプションのmaxResultsとnextTokenの値により、結果のページ分割を指定します。複数のskillI値を以下のように使用すると、ページごとのスキルの要約を取得するのではなく、指定したスキルのみの要約を取得できます。

リクエスト

GET /v1/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}

または

GET /v1/skills?vendorId={vendorId}&skillId={skillId1}&skillId={skillId2}

パラメーター

フィールド	説明	パラメーターの型	必須
`vendorId`	一意のベンダーIDです。	クエリーパラメーター	◯
`skillId`	情報をリクエストするスキルIDです。1つのリクエストには最大10の`skillId`値を含めることができます。`maxResults`および`nextToken`のパラメーターは、`skillId`と同時に使用することはできません。	クエリーパラメーター	✕
`maxResults`	ページごとに表示するスキルの最大数です。50を超える値を指定することはできません。	クエリーパラメーター	✕
`nextToken`	前回のリストスキル応答で、responseオブジェクトで返された継続トークンです。このパラメーターがnullの場合、応答には最初のセットのスキルが含まれます。	クエリーパラメーター	✕

Response

HTTP/1.1 200 Returns list of skills for the vendor.
Content-Type: application/json+hal

本文

{
    "_links": {
            "next": {
                "href": "/v1/skills?vendorId=MA2384AJJ2NAJ&nextToken=eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ=="
            },
            "self": {
                "href": "/v1/skills?vendorId=MA2384AJJ2NAJ"
            }
    },
    "isTruncated": true,
    "nextToken": "eyJkIjoiVGFmRStsVy9YL1BWczZVaGZTMmt0WTFYajdOK3g1Z0xIS3B1aUxRUHpkQ0xtTmtxVkR6cDIxYk10cUpTTlRUU2phS3ZFK2VGclVlQmQ2NDBlK3ltUDdrRyt1UmVtazBhdmFUTlN5RVd5WXVLTjhhTzhyTERJd1p5VU9ZWXFFb1k5MnF1M3RlaUMrOStyQVY1Z1B0MVhNYkh3L0VycWZvL2k0VzhBNGFSWEwyaVRRVTl3NEJCQ0RlV1lrZ2FXMmlobGpMT2FiYitlNk1IVkVrNHBIak1PZz09IiwiaXYiOiJLN09peDd3TE5MUmxKWVFnYVEwU0R3PT0iLCJ2IjoxfQ==",
    "skills": [
        {
            "lastUpdated": "2017-07-11T19:29:57.120Z",
            "nameByLocale": {
                "en-US": "example"
            },
            "stage": "development",
            "apis": [
                "custom",
            ],
            "publicationStatus": "DEVELOPMENT",
            "_links": {
                "self": {
                    "href": "/v1/skills/amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb/stages/development/manifest"
                }
            },
            "skillId": "amzn1.ask.skill.6acdbdf8-8420-440e-823e-aaaaaaaabbbb"
        },
        {
            "lastUpdated": "2017-07-05T21:11:16.947Z",
            "asin": "ACIS-QA-xxxxxxx",
            "nameByLocale": {
                "en-US": "example1"
            },
            "stage": "live",
            "apis": [
                "video"
            ],
            "publicationStatus": "PUBLISHED",
            "_links": {
                "self": {
                    "href": "/v1/skills/amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb/stages/live/manifest"
                }
            },
            "skillId": "amzn1.ask.skill.81ded88f-0d0a-4612-aaaaaaaabbbb"
        }
    ]
}

フィールド	説明
`_links`	Hypertext Application Languageリンクで、リソース間を移動するために使用します。
`isTruncated`	返す結果がこれ以上ない場合、`false`になります。
`nextToken`	`isTruncated`がtrueの場合、次のページの結果を照会できます。
`asin`	ASIN（Amazon Standard Identification Number）、商品IDです。
`skills`	次のパラメーターの要約を含むオブジェクトのリスト：`skillId`および`stage`です

例外

HTTP/1.1 400 Server cannot process the request due to a client error.

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Server Error

HTTP/1.1 503 Service Unavailable

スキルの削除

スキルを削除します。

リクエスト

DELETE /v1/skills/{skillId}/

パラメーター

フィールド	説明	パラメーターの型	必須
`skillId`	一意のスキルIDです。	パス	◯

Response

HTTP/1.1 204 Success.コンテンツはありません。

例外

HTTP/1.1 401 The auth token is invalid/expired or doesn't have access to the resource.

HTTP/1.1 403 The operation being requested is not allowed.

HTTP/1.1 404 The resource being requested is not found.

HTTP/1.1 429 Exceed the permitted request limit.Throttling criteria includes total requests, per API, ClientId, and CustomerId.

HTTP/1.1 500 Internal Service Error

HTTP/1.1 503 Service Unavailable

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2024 年 07 月 01 日