スキル操作(スキル管理API)

スキル操作(スキル管理API)

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

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

関連トピック:Alexa Skills KitコマンドラインインターフェースとAlexaスキル管理APIの概要

スキル情報の取得

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

リクエスト

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

パラメーター

フィールド説明パラメーターの型
skillId一意のスキルIDです。パス
stageスキルのステージを表示します。有効な値は、developmentlive(大文字小文字の区別あり)です。パス

応答

HTTP/1.1 200 OK

ヘッダー

ETag: <etag_value>

本文

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

例外

HTTP/1.1 303 See Other
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
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": {
                "en-US": {
                    "summary": "This is a sample Alexa skill.",
                    "examplePhrases": [
                        "Alexa, open sample skill.",
                        "Alexa, turn on kitchen lights.",
                        "Alexa, blink kitchen lights."
                    ],
                    "keywords": [
                        "Smart Home",
                        "Lights",
                        "Smart Devices"
                    ],
                    "name": "Sample custom skill name.",
                    "description": "This skill has basic and advanced smart devices control features."
                }
            },
            "isAvailableWorldwide": false,
            "testingInstructions": "1) Say 'Alexa, discover my devices' 2) Say 'Alexa, turn on sample lights'",
            "category": "SMART_HOME",
            "distributionCountries": [
                "US",
                "GB"
            ]
        },
        "apis": {
            "custom": {
                "endpoint": {
                    "uri": "arn:aws:lambda:us-east-1:032174894474:function:ask-custom-custome_cert"
                }
            }
        },
        "manifestVersion": "1.0",
        "privacyAndCompliance": {
            "allowsPurchases": false,
            "locales": {
                "en-US": {
                    "termsOfUseUrl": "http://www.termsofuse.sampleskill.com",
                    "privacyPolicyUrl": "http://www.myprivacypolicy.sampleskill.com"
                }
            },
            "isExportCompliant": true,
            "isChildDirected": false,
            "usesPersonalInfo": false
        }
    }
}

応答

HTTP/1.1 202 Accepted

ヘッダー

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

本文

{
  "skillId": "{skillId}"
}

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 429 Too Many Requests
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

ヘッダー

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

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
HTTP/1.1 412 Precondition Failed
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

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

指定したスキルリソースのステータスを取得し、任意でリソースごとにステータスをフィルタリングして、リソースが正常にビルドされたかどうかを確認できます。

リクエスト

GET /v1/skills/{skillId}/status?resource=name1&resource=name2

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

パラメーター

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

応答

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

HTTP/1.1 200 OK

本文

応答のサンプルは以下のようになります。

{
    "manifest": {
        "eTag": "ahsdfuhq34894hjk",
        "lastUpdateRequest": {
            "status": "FAILED",
            "errors": [
                {
                    "message": "Please provide a valid url having a valid image for small icon or large icon"
                },
                {
                    "message": "Small icon size should be 108*108. Large icon size should be 512*512."
                }
            ]
        }
    },
    "interactionModel": {
        "en-US": {
            "eTag": "agasguhq34894hjk",
            "lastUpdateRequest": {
                "status": "SUCCEEDED"
            },
        },
        "en-GB": {
            "eTag": "ahsadfahq34894hjk",
            "lastUpdateRequest": {
                "status": "IN_PROGRESS"
            },
        }
    }
}

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

スキルリストの表示

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

リクエスト

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`と同時に使用することはできません。クエリーパラメーターですuriなし
maxResultsページごとに表示するスキルの最大数です。50を超える値を入力することはできません。クエリーパラメーターですuriなし
nextToken前回のリストスキル応答で、responseオブジェクトで返された継続トークンです。このパラメーターがnullの場合、応答には最初のセットのスキルが含まれます。クエリーパラメーターですuriなし

 

応答

HTTP/1.1 200 OK
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",
                "householdList"
            ],
            "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",
            "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"
        }
    ]
}
フィールド説明
_linksHypertext Application Languageリンクで、リソース間を移動するために使用します。
isTruncatedfalse (返す結果がこれ以上ない場合)。
nextTokenisTruncatedがtrueの場合、次のページの結果を照会できます。
skills次のパラメーターの要約を含むオブジェクトのリストです:skillIdおよび stage

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

スキルの削除

スキルを削除します。

リクエスト

DELETE /v1/skills/{skillId}/

パラメーター

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

応答

HTTP/1.1 204 NoContent

例外

HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Service Error
HTTP/1.1 503 Service Unavailable