SMAPIで使用するアクセストークンの取得方法



SMAPIで使用するアクセストークンの取得方法

Alexaスキル管理API(SMAPI)へのリクエストを行う場合、リクエストのヘッダーにアクセストークンを指定する必要があります。SMAPIを使用するには、アクセストークンとは何か、リクエストでの指定場所、アクセストークンの取得方法を理解する必要があります。アクセストークンの取得方法は、スキル開発プロセスにおけるロールによって異なります。

アクセストークンとは

アクセストークンは、リソースオーナーがクライアントに、リソースのセットに対して一連の操作を行う権限を与えたことを表します。SMAPIには、次のようなロールがあります。

  • リソース – リソースは、スキルか、スキルが使用するもの(対話モデル、スキル内商品、アカウントリンク情報など)です。
  • リソースオーナー – リソースオーナーは、そのリソースが属するAmazon開発者アカウントのことです。すべてのAmazon開発者アカウントには、ベンダーIDがあります。ベンダーIDを確認するには、Amazon開発者アカウントにログインし、カスタマーIDとベンダーIDに移動します。
  • クライアント – クライアントは、SMAPIを使ってスキル上で一連の操作を実行するための権限を必要とする開発者、ツール、組織を指します。Alexa Skills Kitコマンドラインインターフェース(ASK CLI)(内部でSMAPIを使用)、スキル開発ツール、スキルへのアクセスにSMAPIを使用する開発者のことです。クライアントは、セキュリティプロファイルのクライアントIDとクライアントシークレットにより識別されます。クライアントは、Amazon開発者アカウントを使い、Login with Amazon(LWA)コンソールでIDとシークレットを設定します。
  • 操作 – 操作とは、クライアントがスキルで実行する権限を取得するアクションのことです。操作には、作成、読み取り、更新、削除などがあります。この文脈では、スコープによって操作を特定します。

アクセストークンを取得した後は、アクセストークンを最新の状態に保つ必要があります。アクセストークンを最新に保つには、アクセストークンの期限が1時間で切れたときに更新トークンを使って新しいアクセストークンをリクエストします。

アクセストークンの指定場所

SMAPIにHTTPSリクエストを行う場合、リクエストのAuthenticationヘッダーにベアラートークンとしてアクセストークンを指定します。以下は、スキルマニフェストを取得するリクエストの例です。リクエスト内のアクセストークンを指定する場所を示しています。

GET /v1/skills/{skillId}/stages/{stage}/manifest
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: "Bearer {LWA Access Token}"

アクセストークンの取得方法

スキル開発プロセスでのロールに応じて、次の方法でアクセストークンを取得できます。

  • 自分がリソースオーナーでありクライアントでもある場合 – たとえば、個人の開発者が、自分で作成したスキルをSMAPIを使って操作するとします。アクセストークンを生成するには、ASK CLIを使用します。手順については、自分がリソースオーナーでありクライアントでもある場合にアクセストークンを取得するを参照してください。
  • 自分がクライアントであり、リソースオーナーは別にいる場合 – たとえば、自分が属する組織として開発を依頼していたり、または自分は開発者向けのスキル開発ツールの開発元であり、別の開発者が各自のAmazon開発者アカウントを使ってスキルを作成しているとします。アクセストークンを生成するには、まずリソースオーナーに認証画面のURLを送信します。リソースオーナーはそのURLを使ってLWAにログインします。リソースオーナーがログインすると、LWAは認可コードを返します。クライアントはこのコードとASK CLIを使ってアクセストークンを生成します。手順については、自分がクライアントであり、リソースオーナーは別にいる場合にアクセストークンを取得するを参照してください。
  • 自分がリソースオーナーであり、クライアントは別にいる場合 – たとえば、自分はスキル開発ツールを使ってスキルを作成する開発者であり、または組織からの依頼を受けて自分のAmazon開発者アカウントを使ってスキルを作成しているとします。アクセストークンを生成するには、まず、クライアントから送られた認証画面のURLを使ってログインする必要があります。ログインすると、クライアントからアクセストークンが送信されます。手順については、自分がリソースオーナーであり、クライアントは別にいる場合にアクセストークンを取得するを参照してください。

自分がリソースオーナーでありクライアントでもある場合にアクセストークンを取得する

このケースは最もシンプルです。SMAPIを使い、自分のAmazon開発者アカウントで作成したスキルを操作します。

自分が使用するアクセストークンを取得する

  1. LWAでセキュリティプロファイルを設定します。
  2. LWAコンソールから、セキュリティプロファイルのクライアントIDとクライアントシークレットを取得します。
  3. SMAPIで実行の権限をリクエストする操作(スコープとも呼ぶ)を選択します。
  4. LWAのクライアントID、クライアントシークレット、スコープを使い、ASK CLIでアクセストークンを生成します。

自分がクライアントであり、リソースオーナーは別にいる場合にアクセストークンを取得する

この場合、リソースオーナーが自らのAmazon開発者アカウントで作成したスキルに、クライアントとしてアクセスします。たとえば、自分はスキル開発ツールを作成している場合や、組織として開発者にスキルの作成を依頼している場合などです。次の手順では、開発者(リソースオーナー)がスキルにアクセスする権限をツールに付与し、ツールがアクセストークンを生成します。

リソースオーナーのためにアクセストークンを取得する

  1. LWAでセキュリティプロファイルを設定します。
  2. LWAコンソールから、セキュリティプロファイルのクライアントIDとクライアントシークレットを取得します。
  3. SMAPIで実行の権限をリクエストする操作(スコープとも呼ぶ)を選択します。
  4. 次のように、ASK CLIのutil generate-lwa-tokensコマンドに--no-browserオプションを指定して実行します。
    ask util generate-lwa-tokens --no-browser <スコープ>
    このコマンドの詳細については、ASK CLIコマンドリファレンスのgenerate-lwa-tokensを参照してください。
  5. ASK CLIで表示された認証画面のURLをコピーして、リソースオーナーに送信します。
    リソースオーナーがURLをクリックし、それぞれのAmazon開発者アカウントの認証情報でログインし、リクエストされた権限の付与に同意したら、ウィンドウに認可コードが表示されます。
  6. 開発者に、表示された認可コードをツールに入力するよう指示します。
  7. 認可コードと独自のLWAクライアントIDおよびクライアントシークレットを使い、ASK CLIでアクセストークンを生成します。
  8. アクセストークンをリソースオーナーに渡し、リソースオーナーがSMAPIへのリクエストヘッダーにアクセストークンを指定できるようにします。

自分がリソースオーナーであり、クライアントは別にいる場合にアクセストークンを取得する

この場合、自分はリソースオーナーとして、クライアントである組織からの依頼を受けて、またはクライアントが開発したスキル開発ツールを使ってスキルを作成しています。つまり、スキルはリソースオーナーである開発者(自分)のAmazon開発者アカウントで作成され、組織やツールはリソースオーナーに付与された権限を使ってスキルにアクセスします。

クライアントである組織またはツールからアクセストークンを取得する

  1. 組織からLWA URLが送信されていない場合は、リクエストします。
  2. 組織から送信されたLWA URLをクリックします。
  3. 自分のAmazon開発者アカウントのユーザー名とパスワードを入力します。
    ログインできたら組織からアクセストークンが送信されますので、このアクセストークンをSMAPIで使用します。

アクセストークンを準備し、生成するには、次の手順を実行します。アクセストークンは、リソースオーナーでありクライアントでもある開発者本人、クライアントのかわりにスキルを作成した開発者、クライアントが開発したツールを使ってスキルを作成した開発者のいずれかが使用します。

SMAPIで使用するLWAセキュリティプロファイルの設定

ASK CLIを使用してアクセストークンを生成する前に、まず、LWAセキュリティプロファイルを設定する必要があります。

SMAPIで使用するLWAプロファイルを設定する

  1. LWAコンソールを開き、Amazon開発者アカウントの認証情報でログインします。
  2. まだセキュリティプロファイルを作成していない場合(ページに1つ以上のセキュリティプロファイルが表示されない場合)は、セキュリティプロファイルを新規作成をクリックし、必要な情報を入力してから、保存をクリックします。
  3. 「Login with Amazon」の設定の一覧で、セキュリティプロファイルを探し、歯車アイコンをクリックして、ウェブ設定を選択します。
  4. 右下の編集をクリックします。
  5. 許可された返信URLフィールドに、次のURLを貼り付けます。
    http://127.0.0.1:9090/cb
    https://s3.amazonaws.com/ask-cli/response_parser.html
    これらのURLは、許可されたオリジンではなく許可された返信URLに追加してください。
  6. ページ下部にある保存をクリックします。

セキュリティプロファイルのLWAクライアントIDとクライアントシークレットの取得

ASK CLIを実行してアクセストークンを生成する際、LWAで作成したセキュリティプロファイルのクライアントIDとクライアントシークレットの入力を求められます。以下の手順を実行して、LWAコンソールからこれらの認証情報を取得してください。

LWAセキュリティプロファイルのクライアントIDとクライアントシークレットを取得する

  1. LWAコンソールを開き、Amazon開発者アカウントの認証情報でログインします。
  2. 「Login with Amazon」の設定の一覧で、セキュリティプロファイルを探し、歯車アイコンをクリックして、ウェブ設定を選択します。
  3. クライアントIDクライアントシークレットをコピーします。
    これらは、ASK CLIを実行してアクセストークンを生成する際に必要です。

アクセストークンの生成

LWAセキュリティプロファイルからコピーしたLWAクライアントIDとクライアントシークレット、およびアクセストークンで権限を取得するスコープのリスト(任意)を使い、ASK CLIでアクセストークンを生成できます。

ASK CLIを使ってアクセストークンを生成する

  1. ASK CLIをインストールしたコンピューターで、コマンドラインを起動し、ask util generate-lwa-tokensと入力します。
    このコマンドの詳細については、ASK CLIコマンドリファレンスのgenerate-lwa-tokensを参照してください。
  2. プロンプトで、LWAセキュリティプロファイルからコピーしたLWAクライアントIDとクライアントシークレットを入力します。
  3. 開いたブラウザで、Amazon開発者アカウントのユーザー名とパスワードを使ってサインインします。
    多くの場合、Amazonアカウントに使用しているユーザー名およびパスワードと同じです。
  4. アクセスページが表示されたら、許可をクリックします。

リクエストされた操作(スコープ)の選択

ASK CLIのask util generate-lwa-tokensコマンドを使ってアクセストークンを作成する際、任意でアクセストークンがアクセスを許可する操作(スコープ)を指定できます。SMAPIでは、次の表にある1つ以上のスコープを選択できます。

スコープ 関連付けられる操作

alexa::ask:skills:read

  • Amazon開発者アカウントに関連付けられたベンダーIDのリストの表示
  • スキル詳細の読み取り(対話モデルを除く)
  • スキルステータスの取得
  • スキル一覧の取得

alexa::ask:skills:readwrite

alexa::ask:skills:readのすべてのアクセス権限および

  • スキルの作成
  • スキルの更新
  • スキルの有効化
  • スキルのアカウントリンク情報の読み取りと更新
  • スキル認定の申請と取り下げ

alexa::ask:models:read

  • 対話モデルの読み取り
  • 対話モデルのビルドステータスの取得

alexa::ask:models:readwrite

alexa::ask:models:readのすべてのアクセス権限および

  • 対話モデルの更新

alexa::ask:skills:test

次のスキルテスト操作:

  • スキルの呼び出し
  • シミュレーションリクエストの送信
  • シミュレーションステータスの取得
alexa::ask:catalogs:read

カタログリストの取得

alexa::ask:catalogs:readwrite

既存カタログの更新、または新規カタログの作成

alexa::ask:subscriptions

スキル開発通知APIの使用