識別されたユーザーの連絡先情報をスキルで使用するためにリクエストする

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

識別されたユーザー向けのパーソナライズをスキルで実装しており、Alexaユーザーが音声プロファイルを持つ識別されたユーザーであり、Alexaアプリでスキルをパーソナライズが有効になっている場合、スキルはユーザーの音声プロファイルに関連付けられた連絡先情報にアクセスするためにユーザーの権限をリクエストできます。連絡先情報には、姓名または名前と、携帯電話番号が含まれます。

ユーザーの同意を得ると、スキルは連絡先情報を使用して、次のような便利なエクスペリエンスを実現できます。

「お帰りなさい、＜名前＞さん」など、ユーザーに対する応答をパーソナライズします。
ユーザーに代わってサービスを予約します。
ショートメッセージでユーザーに詳細情報またはフォローアップ情報を送信します。

この連絡先情報には、Person Profile APIを使用してアクセスします。

パーソナライズの詳細については、Alexaスキルのパーソナライズを参照してください。

Person Profile APIとユーザープロフィールAPI（Customer Profile API）の違い
始める前に
識別されたユーザーの連絡先情報を使用するスキルを作成する手順
識別されたユーザーの連絡先情報が利用できない場合のベストプラクティス
Person Profile APIリファレンス

Person Profile APIとユーザープロフィールAPI（Customer Profile API）の違い

1台のAlexaデバイスは1つのAmazonアカウントにのみ登録されますが、複数のユーザーがそのデバイスと対話する場合があります。デフォルトの場合、スキルは個々のユーザーを区別しないため、パーソナライズされた応答を返すことができるのはアカウントレベルのみです。

スキルがパーソナライズ機能をサポートしている場合、スキルは識別されたユーザーを区別できます。識別されたユーザーになるためには、そのユーザーの音声プロファイルがあり、Alexaアプリでスキルをパーソナライズが有効になっている必要があります。Alexaユーザーがパーソナライズ機能を有効または無効にする方法の詳細については、スキルのパーソナライズをユーザーとして管理するを参照してください。

Alexa Skills Kitには、Person Profile APIとユーザープロフィールAPIという、Alexaユーザーの連絡先情報へのアクセスに関連する2つのAPIがあります。この2つのAPIの違いは次のとおりです。

Person Profile APIは、Alexaデバイスに話しかけている個人（識別されたユーザー）の連絡先情報を返します。詳細については、このページで後ほど説明します。
ユーザープロフィールAPIは、Alexaデバイスが登録されているAmazonアカウントに関連付けられた連絡先情報を返します。ユーザープロフィールAPIとPerson Profile APIにはもう1つ違いがあります。ユーザープロフィールAPIの場合、連絡先情報と共にEメールアドレスが返されますが、Person Profile APIの場合、Eメールアドレスは含まれません。ユーザープロフィールAPIの詳細については、スキルで使用するためにユーザーの連絡先情報をリクエストするを参照してください。

つまり、「個人（person）」とはAlexaに話しかけている識別されたユーザーで、「ユーザー」とはAlexaデバイスが登録されているAmazonアカウントです。そのため、Person Profile APIは最も高度なパーソナライズ機能を提供します。

始める前に

ユーザーのデータを保護するために、識別されたユーザーの連絡先情報を使用するスキルはすべて、以下の要件を満たす必要があります。スキルが以下の要件のいずれかに違反しているとAmazonが判断した場合、スキル認定の申請を却下または保留し、開発者アカウントに関連付けられたEメールアドレスに通知します。

スキルに適用するプライバシーポリシーへのリンクを開発者コンソールの公開ページに含める必要があります。
子ども向けスキルでは使用できません。子ども向けスキルの詳細については、子ども向けAlexaスキルを参照してください。
スキルで提供する機能やサービスをサポートするために必要な場合にのみ、識別されたユーザーの連絡先情報を受け取る権限をリクエストする必要があります。取得した個人情報は、そのユーザーの許可を得たうえで、プライバシーに関する通達および関連法令に則って利用する必要があります。
個人情報（姓名、名前、電話番号）を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ連絡先情報を持つアカウントプールのユーザーに関連付けることは認められません。
スキルは、ユーザーがユーザー情報を要求するリクエストを使用してスキルを呼び出すたびに、Person Profile APIを使用して最新のユーザー情報を取得する必要があります。

識別されたユーザーの連絡先情報を使用するスキルを作成する手順

識別されたユーザーの連絡先情報を使用するスキルを設定および実装するための全体的な流れは次のとおりです。

開発者コンソールで、スキルがパーソナライズと識別されたユーザーの連絡先情報をサポートしていることを表示するよう設定します。詳細については、スキルを設定するを参照してください。
ユーザーがスキルを有効にすると、Alexaアプリは連絡先情報の提供に同意するようユーザーにプロンプトを出します。ユーザーがスキルを有効にするときにこれらの権限を付与しないことを選択した場合、ユーザーがスキルと対話し、スキルで情報が必要になった時点で、スキルは権限カードを使用してこの同意をリクエストできます。ユーザーがこの情報へのアクセス権限の付与に同意しなかった場合にも、スキルで適切に処理できるようにする必要があります。
ユーザーがスキルを起動したときに、LaunchRequestからapiAccessTokenを取得します。詳細については、起動リクエストからAPIアクセストークンを取得するを参照してください。
Person Profile APIエンドポイントにリクエストを行うときに、apiAccessTokenを認証トークンとして使用します。詳細については、Person Profile APIへのリクエストでAPIアクセストークンを使用するを参照してください。APIリファレンスについては、Person Profile APIリファレンスを参照してください。ユーザーがスキルを有効にしたときに連絡先データへのアクセス権限を付与することに同意しなかった場合は、権限カードを使用して再度権限を求めることができます。
スキルを開発するときに、Person Profile APIの呼び出しをテストします。詳細については、Person Profile APIの呼び出しをテストするを参照してください。

注：このエクスペリエンスが一貫して機能するには、ユーザーが音声プロファイルを持っている必要があります。音声プロファイルの詳細については、スキルのパーソナライズをユーザーとして管理するを参照してください。

ステップ1：スキルを設定する

スキルでPerson Profile APIを使用するには、まずパーソナライズおよび識別されたユーザーの連絡先情報をサポートするようスキルを設定する必要があります。

ステップ2：ユーザーにプロンプトを出す

前のステップでスキルを設定したことにより、ユーザーがスキルを有効にすると、Alexaアプリは連絡先情報にアクセスすることに同意するようユーザーにプロンプトを出します。

ユーザーがスキルを有効にするときにこれらの権限を付与しないことを選択した場合、ユーザーがスキルと対話し、スキルで情報が必要になった時点で、スキルは権限カードを使用してこの同意をリクエストできます。詳細については、ステップ3を参照してください。

ステップ3：起動リクエストからAPIアクセストークンを取得する

Alexaがスキルに送信する各リクエストには、スキルに与えられた権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。このトークンを取得して、ユーザーの連絡先情報のリクエストに含める必要があります。apiAccessTokenには有効期限があるため、保存しないでください。代わりに、後続の各リクエストから新しいトークンを取得します。

ステップ4： Person Profile APIへのリクエストでAPIアクセストークンを使用する

識別されたユーザーの連絡先情報を取得するには、Person Profile APIにリクエストを行うときに、apiAccessTokenを認証トークンとして使用します。APIリファレンスについては、Person Profile APIリファレンスを参照してください。

Person Profile APIを呼び出すときに、次の形式でAuthorizationヘッダーにapiAccessTokenを含めます。

Bearer < ACCESS_TOKEN >

ここで、< ACCESS_TOKEN >は、この例のようにAlexaリクエストメッセージのapiAccessTokenフィールドの値になります。

Authorization: Bearer AxThk...6fnLok

AlexaはapiAccessTokenをスキルに対するすべてのリクエストに含めます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかは関係ありません。このため、apiAccessTokenの有無によって、必要な権限があるかどうかを判断することはできません。403 Forbiddenという応答を受け取った場合、必要な権限がスキルにありません。この場合、次に説明するように、権限をリクエストするカードを表示できます。

ユーザーの同意をリクエストする権限カード

実行中にユーザーに権限を求めるために、スキルはAlexaへの応答にAskForPermissionsConsentカードを含めることができます。Alexaは、ユーザーに話しかけて、Alexaアプリ内のカードについて通知します。ユーザーはこのときに権限を付与するかどうかを決定できます。カードの表示の詳細については、スキルの応答にカードを追加するを参照してください。

カードを表示するための応答を返すときは、permissionsフィールドに1つ以上の値を指定します。

リクエストする情報	permissionsに含める値
姓名	`alexa::profile:name:read`
名前	`alexa::profile:given_name:read`
電話番号	`alexa::profile:mobile_number:read`

permissionsの値は、開発者コンソールのビルド＞アクセス権限ページでスキルに対して宣言したスコープと常に同じになります。

カードについては、以下のオプションを使用します。

設定	値
新しいカード	`AskForPermissionsConsentCard`
インターフェース	`CardRenderer`
定義	`{ "type": "AskForPermissionsConsent", "permissions": << list of scope strings >> }`
アトリビュート	`permissions`：Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつ開発者コンソールのスキルメタデータで宣言されているAlexa権限のみを含めます。

以下は、名前と電話番号をリクエストするカードの応答の例です。

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::profile:name:read",
        "alexa::profile:mobile_number:read"
      ]
    }
  }
}

権限イベント

Alexaでスキルに権限について通知する場合、以下のスキルイベントのサブスクリプションを行います。

スキル権限付与イベント（v1.1）- このイベントはユーザーまたは個人が初めて権限を承認したか、すべての権限を取り消した後に権限を付与した場合に送信されます。スキルの権限を変更したり、付与したりするイベントの場合、直近で承認された権限がペイロードに常に含まれます。このイベントのバージョン1.1を使用するのは、パーソナライズ（personオブジェクト）がサポートされているためです。
スキル権限変更イベント（v1.1）- このイベントは、ユーザーまたは個人がスキルに追加の権限を付与したか、スキルの既存の権限を取り消した場合に送信されます。スキルの権限を変更したり、付与したりするイベントの場合、直近で承認された権限がペイロードに常に含まれます。このイベントのバージョン1.1を使用するのは、パーソナライズ（personオブジェクト）がサポートされているためです。

スキルイベントの使用の詳細については、Alexaスキルのスキルイベントを参照してください。

ステップ5： Person Profile APIの呼び出しをテストする

スキルをテストする前に、スキルのパーソナライズのテストとトラブルシューティングを読んでください。また、音声プロファイルが設定されていることを確認してください。詳細については、スキルのパーソナライズをユーザーとして管理するを参照してください。

開発者コンソールでAlexaシミュレーターを使用することで、Person Profile APIを呼び出し、独自の情報を含むエラー以外の応答を受け取ることができます。ユーザーが権限を付与しなかった場合のフローをテストすることもできます。

識別されたユーザーの連絡先情報が利用できない場合のベストプラクティス

前に説明したように、ユーザーがスキルを有効にすると、Alexaアプリは、識別されたユーザーの連絡先情報にアクセスすることに同意するようユーザーにプロンプトを出します。ユーザーがスキルを有効にするときにこれらの権限を付与しないことを選択した場合、スキルは、ユーザーがスキルを使用するときに権限カードを使用することで、必要に応じてこの同意をリクエストできます。

認識されたユーザーの連絡先情報が利用できない場合は、以下のベストプラクティスに留意してください。

可能であれば、リクエストした権限がなくても一部の機能が利用できるスキルを作成します。
ユーザーのリクエストを完了するために必要な場合にのみ、ユーザーに権限付与のプロンプトを出します。
ユーザーが情報の共有に同意せず、この情報なしではスキルが続行できない場合は、この情報がないとスキルが機能できないことを表す適切なフォールバックメッセージを提供し、セッションを終了します。代わりに、スキルは動作を続けるが、リクエストした情報がある場合に比べて実行できる機能が限定されることを表すメッセージを提供することもできます。
ユーザーが同意したが、必要な情報が利用できない状況に備えます。たとえば、ユーザーがAmazonに携帯電話番号を提供していないような場合です。リクエストしたユーザー情報が利用できない場合、APIは204 No Content応答を返します。この状況で、何らかの情報がないとスキルがリクエストを完了できない場合、Alexaアプリでこの情報を入力するようユーザーにプロンプトを出すことができます。次に例を示します。「＜リソース名＞が設定されていません。Alexaアプリの設定＞マイプロフィールでこれらの詳細情報を入力した後、再度このスキルを開始できます。」
スキルを使いやすくするため、目的の情報を取得できなかった場合のすべてのシナリオを網羅したスキルワークフローを作成するようにしてください。

Person Profile APIリファレンス

Person Profile APIは、識別されたユーザーの連絡先情報にアクセスするために使用するREST APIです。リクエストは、対応する権限をユーザーがスキルに付与している場合にのみ成功します。

Person Profile APIのエンドポイントはスキルの地域によって異なります。次のJSONの例に示すように、SystemオブジェクトのapiEndpoint値から正しいベースURLを取得します。

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.<skill-id>"
      },
      "user": {},
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.fe.amazonalexa.com"
    }
  },
  "request": {}
}

HTTPメソッドとURIパス

次のパスを使用して、識別されたユーザーの連絡先情報を取得します。これらはリテラルで、大文字と小文字が区別される文字列です。

リクエストする情報	パス
姓名	`GET /v2/persons/~current/profile/name`
名前	`GET /v2/persons/~current/profile/givenName`
携帯電話番号	`GET /v2/persons/~current/profile/mobileNumber`

リクエスト

リクエストヘッダー

ヘッダー	説明	型	必須
`Authorization`	次の形式での現在のアクセストークンです。 `Bearer {アクセストークン}`	文字列	◯

リクエストの例

Host: api.fe.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.fe.amazonalexa.com/v2/persons/~current/profile/name

応答

応答ヘッダー

ヘッダー	説明
`Content-Type`	値は`application/json`になります。
`X-Amzn-RequestId`	リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

応答の例

ヘッダー

Host: api.fe.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json

本文

{
   "countryCode" : "+1",
   "phoneNumber" : "999-999-9999"
}

戻り値の型

以下は、JSON形式の戻り値の型のリストです。

情報	型
姓名	`文字列`
名前	`文字列`
携帯電話番号	`{ "countryCode": "文字列", "phoneNumber": "文字列" }`

携帯電話番号は、countryCodeとphoneNumberの組み合わせです。phoneNumberにはcountryCodeも含まれる場合があり、国内の電話番号のみであることは保証されません。phoneNumberの値は、それ自体でダイヤルできる有効な番号である必要があります。

そのため、電話番号はさまざまな形式となる可能性があります。例としては、+917799827710、7799827710、+91 7799 82 77 11、+91 7799-82-77-11などがあります。国コードだけでも、+1、001、1などの形式が考えられます。

有効な応答

応答	説明
200 OK	リクエストした情報が正常に取得されました。
204 No Content	クエリーが値を返しませんでした。
401 Unauthorized	認証トークンの形式が正しくないか、無効です。
403 Unauthorized	リソースに対するアクセス権限が認証トークンにありません。原因として、ユーザーが以下の必要な手順を実行しなかったことが考えられます。音声プロファイルを作成します。 Alexaアプリでスキルをパーソナライズを有効にします。スキルの詳細ページに移動し、適切なユーザー（音声プロファイル）の権限を付与します。スキルを呼び出して`apiAccessToken`を受け取ります。
429 Too Many Requests	リクエスト件数の超過によりスキルが制限されています。
500 Internal Error	予期しないエラーが発生しました。

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

フィードバックを送信

最終更新日: 2020 年 08 月 23 日

識別されたユーザーの連絡先情報をスキルで使用するためにリクエストする

Person Profile APIとユーザープロフィールAPI（Customer Profile API）の違い

始める前に

識別されたユーザーの連絡先情報を使用するスキルを作成する手順

ステップ1： スキルを設定する

ステップ2： ユーザーにプロンプトを出す

ステップ3： 起動リクエストからAPIアクセストークンを取得する

ステップ4： Person Profile APIへのリクエストでAPIアクセストークンを使用する

ユーザーの同意をリクエストする権限カード

権限イベント

ステップ5： Person Profile APIの呼び出しをテストする

識別されたユーザーの連絡先情報が利用できない場合のベストプラクティス

Person Profile APIリファレンス

HTTPメソッドとURIパス

リクエスト

応答

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

ステップ1：スキルを設定する

ステップ2：ユーザーにプロンプトを出す

ステップ3：起動リクエストからAPIアクセストークンを取得する