あなたのAlexaダッシュボード 設定

Alexaユーザーとシステムユーザーを関連付ける

概要

一部のスキルでは、エンドユーザーのIDを別のシステムのユーザーに接続できるようにする必要があります。これを実現するための仕組みを、アカウントリンクと呼び、Alexaに設定されているユーザーと、スキルのシステム(開発者のシステム)のユーザーアカウントを結び付けることを実現します。スマートホームスキルAPIを使用するスキルは、デバイス制御クラウドのアカウントにAlexaユーザーを接続するために、アカウントリンク(Authorization Code Grantフロー)を使用する必要があります。カスタムスキルは必要に応じて、アカウントのリンクを使用できます。

たとえば、ユーザーがウェブベースのタクシー呼び出しサービス「Car-Fu」を所有しているとします。音声でCar-Fuにアクセスできるようにするカスタムスキル(「アレクサ、Car-Fuでタクシーを呼んで」)が非常に役立ちます。このリクエストを完了するには、スキルが特定のCar-FuユーザーとしてCar-Fuサービスにアクセスする必要があります。よって、Alexaデバイスで使用するAmazonアカウントと、ユーザーのCar-Fuアカウントの間にリンクが必要になります。

この文書では、Alexaユーザーとシステム内のユーザーとの間にこのようなリンクを確立する方法について説明します。

スキルが認証を要するシステムに接続する必要がある場合、アカウントリンクが必要であることに注意してください。カスタムスキルが、単にセッション間の属性を保存するためにユーザーを追跡する必要がある場合は、アカウントリンクを使用する必要はありません。代わりに、各リクエストで提供されるuserIdを使用してユーザーを識別できます。ユーザーがAlexaアプリでスキルを有効にすると、そのユーザーのuserIdが生成されます。このユーザーからのスキルに対するその後のすべてのリクエストには、ユーザーがスキルを無効にしない限り同じuserIdが含まれます。

アカウントリンクの仕組み

お使いのシステムのアカウントとAlexaユーザーを接続するには、システム内でユーザーを個別に識別するアクセストークンを提供する必要があります。Alexaサービスはこのトークンを保存し、スキルのサービスにリクエストを送信する際にこの情報を含めます。スキルはこのトークンを使用し、ユーザーの代わりにシステムで認証を行います。

Alexa Skills Kitでアカウントリンクを使用するためには、OAuth 2.0認証フレームワークにある程度精通している必要があります。2つのOAuth認証グラントタイプに対応します。

これら2つのタイプの主な違いは、システムからアクセストークンを取得する方法です。エンドユーザーの視点からの違いはありません。

OAuthのロールとAlexa Skills Kit

OAuth 2.0は、リソースオーナー、リソースサーバー、クライアント、認可サーバーの4つのロールを規定しています。Alexa Skills KitでOAuthを使用する場合、これらのロールは次のように考えることができます。

  • リソースオーナー: 開発者のシステムのユーザーアカウントとスキルとの連携を必要としているエンドユーザー。
  • リソースサーバー: ユーザーがアクセスしたいリソースをホストするサーバー。このサーバーは開発者のシステムの一部で、アクセストークンを使用したリクエストの受付や応答ができる必要があります。Car-Fuの例では、Car-Fuサービスの一部がこれにあたります。保護されたリソースはユーザーのCar-Fuアカウントプロフィールです。
  • クライアント: リソースの所有者に代わってリソースサーバーにリクエストを行うアプリケーションです。この場合、Alexaサービスがこれにあたります。
  • 認可サーバー: リソースオーナーの身元を認証し、アクセストークンを発行するサーバーです。Car-Fuの例では、これもCar-Fuサービス全般の一部にあたります。

リソースサーバーと認可サーバーが同一のサーバーである場合があります。

エンドユーザーによるスキルのアカウントリンク

ユーザーは、Amazon Alexaアプリを使用して自分のアカウントにリンクします。ユーザーは必ずそのアプリを使用する必要があります。音声のみでリンクを確立するためのサポートはありません。ユーザーがプロセスを開始できるのは、

  • Amazon Alexaアプリからスキルが有効にされたとき、
  • スキルに対して認証を必要とするリクエストが送信された後。この場合、スキルからAlexaアプリにLinkAccountカードが返され、ユーザーはそのカードからプロセスを開始できます。このシナリオは、カスタムスキルのみに有効で、スマートホームスキルには当てはまりません。

具体的な流れは、Implicit GrantまたはAuthorization Code Grantを使用しているかどうかによって異なりますが、どちらの場合もエンドユーザーの手順は同じです。

Authorization Code Grantにおけるアカウントのリンクの流れ(スマートホームスキルまたはカスタムスキルで使用):

  1. ユーザーはAlexaアプリでスキルを有効にします。
  2. アプリは、開発者ポータルでスキルを登録した際に提供した認証URLを使用し、アプリ内にログインページを表示します。コンパニオンアプリは、このURLを呼び出す際、クエリ文字列パラメーターとしてstateclient_idresponse_typescoperedirect_uriを含めます。
    • stateはアカウントリンク処理中にAlexaサービスによって使用されます。後ほどこの値を返す必要があるため、ページではこの値を追跡する必要があります。
    • client_idは、開発者ポータルでスキルにアカウントリンクを設定する際に定義される値です。
    • response_typeは常に、コードグラントフローのcodeになります。
    • scopeは、リクエストされたアクセスレベルを示す任意のアクセス範囲のリストです。スキルにアカウントリンクを設定する際、サポートする一連の範囲を定義します。
    • redirect_uriは、開発者のサービスがユーザー認証後にユーザーをリダイレクトするURLです。
  3. ユーザーはサイトに通常の認証情報でログインします。
  4. サービスはユーザーを認証し、codeを生成します。
  5. サービスはユーザーを指定されたredirect_uriにリダイレクトし、URLのクエリパラメーターでstatecodeを転送します。
  6. Alexaサービスは、返された情報を確認し、codeを使用してアクセストークンリフレッシュトークンのペアを認可サーバー(開発者ポータルの「アクセストークンURI(Access Token URI)」フィールドで指定)からリクエストします。これらのアイテムは両方ともAlexaユーザーのために保存されます。
  7. ユーザーのAlexaアカウントはこれでサービスのアカウントにリンクされ、スキルが使用できるようになります。

Implicit Grantにおけるアカウントリンクの流れ(カスタムスキルでのみ使用可能):

  1. ユーザーはAlexaアプリでスキルを有効にします。
  2. アプリは、開発者ポータルでスキルを登録した際に提供した認証URLを使用し、アプリ内にログインページを表示します。コンパニオンアプリは、このURLを呼び出す際、クエリ文字列パラメーターとしてstateclient_idresponse_typescopeを含めます。
    • stateはアカウントリンク処理中にAlexaサービスによって使用されます。後ほどこの値を返す必要があるため、ページではこの値を追跡する必要があります。
    • client_idは、開発者ポータルでスキルにアカウントリンクを設定する際に定義される値です。
    • Implicit Grantフローでは、response_typeが常にtokenになります。
    • scopeは、リクエストされたアクセスレベルを示す任意のアクセス範囲のリストです。スキルにアカウントリンクを設定する際、サポートする一連の範囲を定義します。
    • redirect_uriは、開発者のサービスがユーザー認証後にユーザーをリダイレクトするURLです。
  3. ユーザーはサイトに通常の認証情報でログインします。
  4. サービスはユーザーを認証し、システムでユーザーを個別に認識するアクセストークンを生成します。
  5. サービスはユーザーを指定されたredirect_uriにリダイレクトし、URLフラグメントでstateaccess_tokentoken_typeを転送します。
  6. Alexaサービスは返された情報を確認し、このAlexaユーザーのaccess_tokenとして保存します。
  7. ユーザーのAlexaアカウントはこれでサービスのアカウントにリンクされ、スキルが使用できるようになります。

ユーザーがアカウントリンクでスキルを呼び出す場合

ユーザーがアカウントのリンクで設定されているカスタムスキルとの対話を開始すると、次の処理が行われます。

  1. ユーザーは、通常通りにスキルを呼び出します。「アレクサ、Car-Fuでタクシーを呼んで。」
  2. Authorization Code Grantを使用する場合、Alexaサービスはユーザーの既存のアクセストークンが有効であることを確認します。有効期限が切れている場合、Alexaサービスはリフレッシュトークンを使い、認可サーバーから新しいアクセストークンを要求します。
  3. スキルのサービスに送信されるLaunchRequestIntentRequestには、そのユーザーの保存済みアクセストークンが含まれます。
  4. サービスはトークンがシステムのユーザーと一致していることを確認します。

    • トークンが有効であれば、サービスは必要に応じてユーザーの情報にアクセスし、リクエストを完了し、適切な応答(音声によるユーザーへの応答を含む)を返し、必要に応じてAlexaアプリにカードを表示します。

      たとえば、Car-Fuの例では、Car-Fuスキルは、与えられたトークンが有効なCar-Fuユーザーに一致することを確認します。一致すると、サービスはそのユーザーのCar-Fuプロフィールにアクセスし、その情報を使い、ユーザーの配車リクエストに対応します。

    • トークンが無効である場合、サービスはアカウントリンクを行うことを促すテキストと、アカウントの連携を行わせるためのLinkAccountカードの表示要求を返します。ユーザーはこのカードのリンクをクリックしてアカウントリンク処理を開始できます。

      LinkAccountカードの例
      LinkAccountカードの例

プロセスはスマートホームスキルについてもほぼ同じです。

  1. ユーザーは、通常通りにスキルを呼び出します。例: 「アレクサ、リビングルームの照明をつけて。」
  2. Alexaサービスは、ユーザー用に保存されているアクセストークンがまだ有効であることを確認します。有効期限が切れている場合、Alexaサービスはリフレッシュトークンを使い、認可サーバーから新しいアクセストークンを要求します。
  3. スキルアダプターは端末を制御するためのディレクティブを受け取ります。このディレクティブは、payloadの中にアクセストークンを含んでいます。
  4. スキルアダプターはデバイス制御クラウドにトークンを転送し、ユーザーのリクエストを完了します。
    • トークンが有効な場合、デバイス制御クラウドは、通常通りにリクエストを完了し、要求された照明を点灯します。
    • トークンが無効な場合、スキルアダプターはDependentServiceUnavailableErrorを返します。その後Alexaはユーザーにリクエストに対応できなかったことを伝えます。

デバイスディレクティブについて詳しくは、スマートホームスキルAPIのリファレンスをご覧ください。

ユーザーがアカウントリンクを使うスキルを無効にする場合

ユーザーがAlexaアプリでスキルを無効にすると、Alexaサービスは、そのユーザーとスキルに関連付けられたアクセストークン(および該当する場合はリフレッシュトークン)を削除します。これにより、ユーザーのAlexaアカウントとサービスのアカウント間のリンクは基本的に削除されます。

ユーザーが後にスキルを再び有効にする場合は、新しいユーザーとしてアカウントリンクの処理を完了させる必要があります。

スキルにアカウントリンクを追加する際に必要なもの

スキルにアカウントリンクを実装するには、次が必要です。

Authorization Code Grant Implicit Grant
ユーザーを認証するウェブベースのサービス。 ユーザーを認証するウェブベースのサービス。
ユーザーの認証情報を収集し、ユーザーを認証して、認可コードを生成するログインページを表示できる認可サーバー。 ユーザーの認証情報を収集し、ユーザーを認証して、そのユーザーを個別に識別するアクセストークンを生成するログインページを表示できる認可サーバー。
認可コードとAlexaのクライアント認証情報を受理し、そのユーザーを個別に識別するアクセストークンを生成できる認可サーバー。 該当なし

スキルにアカウントリンクを追加するには、次を実行する必要があります。

  1. サービスのログインページへアカウントリンクサポートを追加する
  2. スキルのクラウドベースのサービス(ウェブサービスまたはLambda関数)にアカウントリンクロジックを追加する
  3. 開発者ポータルでスキルのアカウントリンクを有効にする

手順の詳細については以下のセクションをご覧ください。

ログインページ(認証URL)にアカウントのリンクのサポートを追加する

ユーザーがアカウントリンクの処理を開始すると、Alexaアプリはリソースサーバーのログインページを表示します。この目的に適したページを設計し、コーディングする必要があります。このページは、ユーザーの認証情報を確認し、アクセストークンか認可コードのいずれかを返す必要があります。

開発者ポータルでスキルのアカウントリンクを有効にする際、「認証URL(Authorization URL)」フィールドでこのページのURLを設定します。

ユーザーの言語でログインページを提供する

Alexaアプリは、ユーザーのブラウザが対応言語(ja-jpen-usen-gbde-de)のいずれかに設定されている場合、ユーザーのブラウザの言語設定を使ってローカライズ版アプリの表示を試みます。その他の言語の場合、アプリのデフォルト言語はen-usになります。

一貫したユーザーサービスのために、ログインページもAlexaアプリと同じ言語で表示する必要があります。言語を取得するには、まずAccept-Languageヘッダーを確認してください。Alexaアプリは、認証URLを呼び出す際に言語の設定を試みます。

ヘッダーが設定されていない場合、navigator.languagenavigator.browserLanguageを確認して、ユーザーのブラウザに定義された言語を使用できます。ナビゲーター言語のプロパティをご覧ください。

ユーザーのブラウザの言語と、Alexa搭載端末の言語は、別々に設定されることに注意してください。たとえば、ユーザーは端末の言語をドイツ語に設定し、ブラウザではイギリス英語を使用するように設定できます。この場合、Alexaアプリは英語で表示されAccept-Languageヘッダーは英語(en-gb)に設定されます。

認証URLに渡されたパラメーター

Alexaアプリは、認証URLを呼び出す際にURLクエリ文字列に次のパラメーターを含めます。

  • state は、アカウントリンクの処理を追跡するためにAlexaサービスが内部で使用します。
    • ページはリダイレクトURLを呼び出す際、この値を(未変更で)返す必要があります。
    • この値は、5分後に期限が切れます。ユーザーのログインと、サービスでのユーザーのリダイレクトに5分以上かかる場合、stateは無効となり、アカウントリンクの処理は失敗します。この場合、ユーザーはAlexaアプリ内のリンクをクリックして、最初からやり直す必要があります。
  • client_idはスキル開発者が任意に定義する識別子です。認可URLでリクエストを受け取るサーバーはこの値によって、どのスキルからのリクエストなのかなどの識別をすることができます。開発者ポータルでスキルのアカウントリンクを有効にする際に、client_idで定義される値です。
  • response_type値にはAuthorization Code GrantかImplicit Grantかを識別する値が入ります。
    • code はAuthorization Code Grant用です。
    • token はImplicit Grant用です。
  • scopeは、Alexaユーザーが必要とするアクセスを示す任意の範囲のリストです。開発者ポータルでスキルのアカウントリンクを有効にする際に、範囲を定義します。
    • アクセストークンを生成する際にこの情報を使用できます。たとえば、リソースサーバーで基本的なプロファイル情報へのアクセスは許可し、支払い情報へのアクセスは許可しないトークンを作成できます。
    • 複数の範囲が使用できます。このリストは、URLエンコードされたスペースで区切られています。
    • また、アカウントをリンクすることにより、どのアクセスを許可しているのかをユーザーに伝えるのもよいでしょう。たとえば、ログインページに、「これにより、Car-Fuスキルがあなたの代わりにタクシーを呼び、アカウントに料金を請求できるようになります」などのメッセージを表示します。
  • redirect_uriは、ユーザー認証後にサービスがユーザーをリダイレクトする、Amazon固有のリダイレクトURL(OAuthリダイレクションエンドポイント)です。このパラメーターで与えられる値の候補は、アカウントリンクを設定する際に開発者ポータルに表示されています。認可サーバーは、このあらかじめ与えられた候補の値と、実際与えられた値が一致するかを確認することで、URLが有効かどうかを確認することができます。

たとえば、ページの認証URLがhttps://www.carfu.com/loginの場合、Alexaアプリが呼び出すURLは次のようになります(Authorization Code Grant)。

https://www.carfu.com/login?state=abc&client_id=alexa-skill&scope=order_car%20basic_profile&response_type=code&redirect_uri=https%3A%2F%2Fpitangui.amazon.com%2Fspa%2Fskill%2Faccount-linking-status.html%3FvendorId%3DAAAAAAAAAAAAAA

ログインページの要件

ログインページは、次の要件を満たす必要があります。

  • HTTPS経由で提供されること。
  • Alexaアプリ内で表示されることになるため、モバイルフレンドリーであること。
  • ポップアップウィンドウを開かないこと。ポップアップウィンドウは開くことはできない。
  • ユーザーの認証情報を受理し、ユーザーを認証すること。
  • 次のいずれかができること。
    • アクセストークンを生成する。これを使ってリソースサーバーにユーザーを個別に識別させることができる。
    • アクセストークンを取得するために、認可サーバーに渡すことができる認証コードを生成する。
  • クエリ文字列で渡されるstate値を追跡できること。
  • ユーザーを認証した後、ページはAmazonが提供する2つのリダイレクトURLのうちのいずれかにユーザーをリダイレクトすること。
    • 使用するリダイレクトURLは、redirect_uriパラメーターとして認証リクエストに含まれる。
    • 2つのリダイレクトURLは、スキルのアカウントリンクオプションをオンにすると、開発者ポータルにも表示されます。これがログインページがredirect_uriパラメーターを受け取る可能性のある値です。
    • Authorization Code Grantでは、URLクエリ文字列にstatecodeを含める。
    • Implicit Grantでは、URLフラグメントにstateaccess_tokentoken_typeを含める。token_typeBearerである必要がある。

たとえば、Amazonが提供するリダイレクトURLが次であるとします。

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA 

Authorization Code Grantでは、リダイレクトURLはこのようになります。

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA&state=xyz&code=SplxlOBeZQQYbYS6WxSbIA 

返す必要があるパラメーター(statecode)はURLのクエリ文字列にあります。

Implicit Grantでは、リダイレクトURLはこのようになります。

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz&access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer

返す必要があるパラメーター(stateaccess_tokentoken_type)はURLのフラグメントにあります。ハッシュタグの後の部分です(#)。

アクセストークンとリフレッシュトークンについて

認可サーバーは、システムでユーザーを個別に識別するアクセストークンを提供する必要があります。

Authorization Code Grantでは、Alexaサービスは認可サーバー(開発者ポータルの「アクセストークンURI(Access Token URI)」として指定)を呼び出し、codeとクライアントの認証情報を渡します。認可サーバーはアクセストークンと任意でリフレッシュトークンを返す必要があります。リフレッシュトークンは任意ですが、アクセストークンの期限が切れる場合に推奨されます。Alexaサービスは、前のトークンの期限が切れると、更新トークンを使い、エンドユーザーをわずらわせることなく、新しいアクセストークンを取得します。

Implicit Grantでは、上記のリダイレクトURIの例のように、リダイレクトURLを呼び出す際にアクセストークンが含まれます。Implicit Grantは更新トークンをサポートしていないため、トークンの期限が切れると、エンドユーザーはアカウントを再びリンクする必要があります。期限が切れるトークンを使用する場合は、Authorization Code Grantを使ってください。

どちらのタイプでも、アクセストークンを生成する場合、リソースサーバーに固有のトークンを提供してください。GoogleやFacebookなど他のOAuthプロバイダーによって提供されたアクセストークンは使用しないでください。セキュリティのため、トークンは、推測できないが、ユーザーを識別できる値にしてください。

スキルのサービスにアカウントリンクロジックを追加する

スキルにアカウントリンクの機能を追加するには、スキルに送信されたリクエストに含まれるアクセストークンを確認し、使用するためのロジックをコーディングする必要があります。

リクエストからアクセストークンを取得する(カスタムスキル)

Javaライブラリを使用している場合、アクセストークンは、onIntent()onLaunch()onSessionEnded()メソッドに渡されるSessionオブジェクトで取得できます。Session.getUser()メソッドを使用してUserオブジェクトを取り込み、このオブジェクトに対してUser.getAccessToken()を呼び出すことでトークンを取得することができます。

JSONでは、アクセストークンは、リクエストのuserオブジェクトのaccessTokenプロパティで取得できます。

{
  "version": "string",
  "session": {
    "new": boolean,
    "sessionId": "string",
    "application": {
      "applicationId": "string"
    },
    "attributes": {
      "string": object
    },
    "user": {
      "userId": "string",
      "accessToken": "string"
    }
  },
  "request": object
}

リクエストからアクセストークンを取得する(スマートホームスキル)

アクセストークンは、payloadオブジェクトのaccessTokenプロパティで、端末ディレクティブの一部としてスキルアダプターに送信されます。

たとえば、これはDiscoverAppliancesRequestディレクティブの例です。

{
  "header": {
    "namespace": "Alexa.ConnectedHome.Discovery",
    "name": "DiscoverAppliancesRequest",
    "payloadVersion": "2",
    "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2"
  },
  "payload": {
    "accessToken": "string"
  }
}

アクセストークンの確認

認証が必要なリクエストでは、コードで少なくとも次の2つの確認を行う必要があります。

  1. accessTokenが存在していることを確認する(カスタムスキルのみ)

    Javaライブラリで、ユーザーがアカウントリンクに失敗した場合、User.getAccessToken()nullを返します。

    JSONでは、ユーザーがアカウントをリンクしていなければ、accessTokenプロパティは存在しません。

    この確認はスマートホームスキルには適用されません。アカウントリンクが正常にできていなければ、スマートホームスキルを有効にすることはできません。

  2. accessTokenが存在する場合、それが有効であり、リソースサーバーでユーザーを識別することができることを確認する。トークンは、次の例のようにさまざまな理由で無効になることがあります。

    • ユーザーがサービスのアカウントを削除またはキャンセルした場合。たとえば、AlexaユーザーはCar-Fuとのアカウントリンクを設定し、その後Car-Fuアカウントをキャンセルしたとします。この時点で、Alexaサービスに保存されたトークンは存在しないユーザーを参照していることになります。
    • トークンの有効期限が切れており、Alexaサービスが新しいトークンを取得できなかった場合。これは、認可サーバーで更新トークンが提供されていない場合で、Authorization Code Grantを使用する場合に発生します。また、これは、リフレッシュトークンをサポートしていないImplicit Grantの認証を使用する場合にも発生します。

トークンが有効であれば、スキルは、必要に応じてリソースサーバーを通してユーザーデータにアクセスし、リクエストを正常に処理することができます。Car-Fuの例では、スキルはCar-Fuサービスからユーザーのプロフィールと支払い情報を取得し、タクシーを呼んで、ユーザーに確認を促します。応答を返す処理については、Alexaが送信したリクエストを処理するの「応答を返す」セクションをご覧ください。

無効なアクセストークンへの対応(スマートホームスキル)

スマートホームスキルのスキルアダプターに送信されたアクセストークンが無効な場合、DependentServiceUnavailableErrorを返します。その後Alexaはユーザーにリクエストに対応できなかったことを伝えます。

無効または存在しないアクセストークンへの対応(カスタムスキル)

カスタムスキルに送信されたアクセストークンが存在しない場合や無効な場合、スキルは次を含む応答を返します。

  • この機能を使用するためにアカウントリンクする必要があることをユーザーに説明する音声出力テキスト。
  • リンクアカウントカード。これは、アカウントリンクするようにユーザーに伝える特殊なカードです。Alexaアプリで表示されると、このカードはログインページのURLへのリンクを表示します。ユーザーはこのカードからアカウントリンクの処理を開始できます。

リンクアカウントカードを送信するには

  • Javaライブラリを使用する場合、LinkAccountCardクラスのインスタンスを作成し、カードとして応答に含めます。
  • JSONを使用する場合、カードtypeLinkAccountに設定します。

     {
         "version": "1.0",
         "sessionAttributes": {
           ...(session attributes not shown)
         },
         "response": {
           "outputSpeech": {
             "type": "PlainText",
             "text": "You must have a Car-Fu account to use this skill. Please use the Alexa app to link your Amazon account with your Car-Fu Account."
           },
           "card": {
             "type": "LinkAccount"
           },
           "shouldEndSession": true
         }
     }
    

ユーザーはアカウントリンクするまでリクエストを続行することができないため、ほとんどの場合、この応答でセッションが終了します。スキルに認証を必要としないインテントが含まれる場合は、ユーザーに異なる質問をしてセッションをオープンにしておくこともできます。

有効なアクセストークンが必要になる場合

サービスは、ウェブサイトでユーザーの認証を必要とするすべてのリクエストでaccessTokenを確認する必要があります。

スマートホームスキルでは、すべてのディレクティブがこれにあたります。

カスタムスキルでは、これには、通常ほとんどのインテントが含まれますが、認証を必要としないインテントを持つことができます。たとえば、Car-Fuカスタムスキルの例では、タクシーを手配する際にはユーザーの認証を必要とし、どの地域でサービスを利用できるか質問する場合は認証を必要としません。したがって、このスキルのコードは次のいずれかを実行します。

  • OrderTaxiインテントのハンドラーは、有効なaccessTokenを確認し、そのトークンを使用してユーザーのCar-Fuプロフィールを取得し、タクシーを手配します。
  • 汎用的に利用可能なTaxiAvailabilityByCityインテントのハンドラーはaccessTokenを確認する必要はなく、Car-Fuサービスの公開情報を検索し、応答を返します。

開発者ポータルでスキルのアカウントリンクを有効にする

アカウントリンクをAmazon開発者ポータルの「コンフィギュレーション(Configuration)」ページで有効にします。

通常、ポータルでスキルを登録した後、「コンフィギュレーション(Configuration)」ページに移動し、「アカウントリンクまたは作成(Account Linking or Creation)」で「はい(Yes)」を選択します。スマートホームスキルではアカウントリンクは常に必要なため、このオプションはスマートホームスキルでは表示されません。

アカウントリンクを有効にするには、少なくとも次を入力する必要があります。

  • 認証URL(Authorization URL): ウェブサイトのログインページのURL。ユーザーがアカウントをリンクする場合に、このページがどのように使用されるのかについては、ログインページにアカウントリンク機能を追加するをご覧ください。
  • クライアントID(Client Id): ログインページでは、このIDによって、リクエストを送信したスキルが特定されます。この値は、client_idパラメーターで認証URLに渡されます。Authorization Code Grantを使用する場合、この値はアクセストークンURIからアクセストークンを要求する際にAlexaサービスに含まれるクライアントの資格情報の一部でもあります。
  • 認証の承諾タイプ: アクセストークンを取得するために使用するOAuth 2.0の認証の承諾タイプです。Alexa Skills Kitは2つの承諾タイプをサポートしています。
  • Authorization Code Grant」では、次の情報も入力する必要があります。
    • アクセストークンURI: アクセストークンを提供する認可サーバーのURL。
    • クライアントシークレット(Client Secret): AlexaサービスがアクセストークンURIで認証できるようにするために提供する資格情報。これは、Alexaからのリクエストを識別するためにクライアントIDと組み合わされます。
    • クライアント認証スキームは、アクセストークンURIからトークンを要求する場合にAlexaが使用する認証のタイプを識別します。
  • プライバシーポリシーのURL(Privacy Policy URL): プライバシーポリシーのページのURLです。このリンクは、Alexaアプリに表示されます。これは、アカウントリンクを使用するスキルには必須です。入力するURLは「プライバシーおよびコンプライアンス(Privacy & Compliance)」ページの「プライバシーポリシーのURL(Privacy Policy URL)」フィールドでも表示されます。

ログインページが別のドメインからコンテンツを取得する場合は、それらをドメインリストに入力してください。これは認証URLの他のドメインにのみ必要になります。たとえば、認証URLがhttps://www.carfu.com/loginとします。ページがwww.carfu.com以外のドメインからコンテンツ(画像など)を取り込む場合は、それらを「ドメインリスト(Domain List)」に追加します。

リソースサーバーがアプリケーションやスキルの種類に応じてユーザーリソースに異なるアクセス範囲を提供する場合は、それらの範囲を「範囲(Scope)」リストに入力します。ここに入力するすべての範囲は、Alexaアプリが認証URLを呼び出す際にscopeパラメーターに含まれます。

URL値をリダイレクトする

アカウントリンクを有効にすると、リダイレクトURLが表示されます。認証された後にユーザーをリダイレクトする必要のあるURLです。この値は、「認証URL(Authorization URL)」に含まれるredirect_uriパラメーターとしてログインページにも渡されます。

複数のリダイレクトURL値があります。Alexaアプリは、ユーザーがデバイスを登録した場所に基づき使用する値を認証URLに渡します。

認証後にユーザーをリダイレクトする際にページに含める必要があるパラメーターは、Authorization Code GrantまたはImplicit Grantのどちらを使用しているかによって異なります。ログインページの要件をご覧ください。

次のステップ

コーディングのトピック(カスタムスキル):

その他のトピック:

リファレンス: