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

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

ユーザーがAlexaスキルを有効にすると、スキルはユーザーに連絡先情報を使用する権限をリクエストできます。ユーザーが承諾すると、スキルで名前、Eメールアドレス、電話番号などの連絡先情報を使用できます。このデータを使用することで、アカウントリンクを行うことなくパーソナライズされたインテントをサポートし、ユーザーエクスペリエンスを改善することができます。たとえば、スキルはユーザーの連絡先情報を使用して近くのレストランを予約し、ユーザーに確認メッセージを送ることができます。

この機能を使うには、Alexa Customer Profile APIを照会します。Alexa Customer Profile APIは、アクティブなデフォルトのAlexaプロフィールからの情報を使用します。このプロフィールは、Alexaに話しかけている人を表している場合も表していない場合もあります。識別されたユーザーの連絡先情報にアクセスする同意を得るには、Person Profile APIを使用します。詳細については、識別されたユーザーの連絡先情報をスキルで使用するためにリクエストするを参照してください。

デバイスの住所情報をリクエストする方法の詳細は、所在地情報を使用してスキルを拡張するを参照してください。サンプルコードのデモについては、Customer Profile Demo（英語のみ）を参照してください。

ユーザーが音声によって、スキルへの連絡先情報の共有を同意できるようにするには、Alexaスキルで音声による権限許可を有効にするを参照してください。

始める前に

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

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

ユーザー名、メールアドレス、電話番号など、リクエストされた情報のいずれかが、リクエストされたときにスキルで利用できない可能性があります。このため、スキルコードでは不足した情報を適切に処理する必要があります。

ユーザーの連絡先情報をリクエストする方法

スキルでユーザーの連絡先情報をリクエストするには、以下の手順で行います。

  1. 開発者コンソールで、スキルでユーザーの連絡先情報を必要とすることを表示するよう、スキルを設定します。ユーザーがスキルを有効にすると、Alexaアプリで連絡先情報の提供に同意するよう、ユーザーにプロンプトが表示されます。ユーザーがスキルの有効化時にこれらの権限を付与しないことを選択した場合、情報が必要になったら、スキルの呼び出し中に権限カードを使ってリクエストすることができます。ユーザーがこの情報へのアクセス権限の付与に同意しなかった場合にも、適切に処理できるようにする必要があります。
  2. ユーザーがスキルを呼び出したときにAlexaがスキルに送信するLaunchRequestから、apiAccessTokenを取得します。apiAccessTokenには有効期限があるため、保存しないでください。代わりに、後続の各リクエストから新しいapiAccessTokenを取得します。
  3. ユーザーの連絡先情報を取得するの記載に従い、apiAccessTokenを含む正しいエンドポイントにリクエストしてください。

ユーザーの権限をリクエストするようスキルを設定する

開発者コンソールを使ってスキルを管理している場合、スキルを以下のように設定します。

  1. 開発者コンソールを使用してスキルを編集します。

  2. コンソールのビルド＞アクセス権限ページに移動します。

    スキルに必要なユーザーリソースに応じて、以下のいずれか（1つまたは複数）を選択します。

    • ユーザー名＞姓名
    • ユーザー名＞名前（ユーザーの名）
    • ユーザーのEメールアドレス
    • 電話番号

姓名を選択した場合、名前を選択することはできません。逆の場合も同様です。

開発者コンソールの代わりにSMAPIやAlexa Skills Kitコマンドラインインターフェース（ASK CLI）を使ってスキルを管理する場合、スキルマニフェストを編集して目的の権限をリクエストします。

APIアクセストークンを取得する

スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。このトークンを取得して、ユーザーの連絡先情報のリクエストに含める必要があります。

apiAccessTokenはSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。リクエストの本文全体は、リクエストの形式を参照してください。

{
  "context": {
    "System": {
      "apiAccessToken": "AxThk...",
      "apiEndpoint": "https://api.fe.amazonalexa.com",
	  ...
    }
  }
}

したがって、accessToken = this.event.context.System.apiAccessTokenとなります。

データをリクエストする場合、この形式の認可ヘッダーにアクセストークンを含めます。

Bearer < ACCESS_TOKEN >

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

Authorization: Bearer AxThk...6fnLok

apiAccessTokenはスキルに対するすべてのリクエストに含まれます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかには関係ありません。そのため、スキルがリクエストを完了するのに必要な正しい権限セットが、トークンに含まれていない可能性があります。スキルは特別な権限カードを表示して、ユーザーに動的に同意を求めることができます。

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

apiAccessTokenはすべてのスキルリクエストに含まれるため、apiAccessTokenが存在するかどうかで必要な権限があるかを判断することはできません。代わりにAPIを呼び出して、応答コードを確認します。403 Forbidden応答は、スキルに権限がないことを表します。スキルがAPIから403応答を受け取った場合、スキルはAlexaへの応答にAskForPermissionsConsentカードを含めることができます。Alexaは、ユーザーに話しかけてAlexaアプリのカードについて知らせ、ユーザーは権限を付与するかどうかを判断できます。

権限カードありの応答のサンプル

セッション内の対話で、新しいAskForPermissionsConsentカードを含む応答を返すことができます。

permissionsには、以下の表の値が含まれます。

姓名alexa::profile:name:read
名前alexa::profile:given_name:read
Eメールアドレスalexa::profile:email:read
電話番号alexa::profile:mobile_number:read

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

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

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

スキルでSkillPermissionAcceptedイベントを使用する

スキルでSkillPermissionAcceptedイベントを使用すると、スキルはユーザーがスキルに権限を付与したときに通知を受け取れます。

スキル作成時にAPIをテストする

開発者コンソールのテストページでは、自身がスキルユーザーとなって一部のテストを実施できます。Alexaシミュレーターを使ってスキルをテストすると、スキルでAlexa Customer Profile APIを呼び出して、独自の情報を含むエラーでない応答を受け取ることができます。ユーザーが権限を付与しない場合のフローをテストすることもできます。

ユーザーがスキルに権限を付与した場合にどうなるかをテストするには、Alexaアプリでスキルに連絡先情報への権限を付与しておくようにしてください。スキルを開くと（「アレクサ、skill_nameを開いて」）、AlexaはスキルにLaunchRequestを送信します。ユーザーが権限を付与していれば、リクエストからapiAccessTokenを取得できます。

ユーザーがスキルに権限を付与しなかった場合にどうなるかをテストするには、Alexaアプリでスキルに連絡先情報への権限を付与しないか、権限を取り消しておくようにしてください。スキルを開くと（「アレクサ、skill_nameを開いて」）、AlexaはスキルにLaunchRequestを送信します。このリクエストにはapiAccessTokenの値が含まれますが、apiAccessTokenには正しい権限が指定されていません。スキルがこのトークンをAlexa Customer Profile APIに渡した場合、APIは403 Forbidden応答コードを返します。

ユーザーがスキルを有効にすると、ユーザーにはAlexaアプリを開いて権限を付与するようプロンプトが出されます。スキルが提供する音声プロンプトは、スキルがこれらの権限を必要とする理由を説明する必要があります。ユーザーが同意しない場合、スキルはAlexaアプリに（ユーザーが画面付きのAlexa搭載デバイスを使用している場合はその画面に）権限カードを送信し、ユーザーにインテントで必要な権限付与に同意するようプロンプトを表示することができます。スキルのコードには、必要に応じて適切なフォールバックメッセージを含める必要があります。

可能であれば、一部の機能はリクエストした権限がなくても利用できるようにスキルを作成してください。ユーザーのリクエスト完了に必要な場合は、その都度ユーザーに権限付与のプロンプトを出す必要があります。

ユーザーに権限カードで権限付与プロンプトを出すサンプルメッセージ

In order to complete this request, {Skill_name} needs access to your {full name/given name/email address/phone number}.Go to the home screen in your Alexa app and grant the permissions to continue.

Afin de répondre à cette demande, {Skill_name} a besoin d'accéder à votre {nom et prénom/prénom/adresse e-mail/numéro de téléphone}.Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.

Um diese Anfrage abzuschließen, benötigt {Skill_name} Zugriff auf {(deinen Vollen Namen/Vornamen) / (deine E-Mail-Adresse/Telefonnummer)}.Um fortzufahren, gehe zum Startbildschirm deiner Alexa-App und gewähre die Berechtigungen.

इस अनुरोध को पूरा करने के लिए, {Skill_name} को आपके {पूर्ण नाम/दिए गए नाम/ईमेल पते/फोन नंबर} तक पहुंच की आवश्यकता है। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें।

Per completare questa richiesta, {Skill_name} deve accedere al tuo {nome completo/nome/indirizzo email/numero di telefono}.Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.

このリクエストを完了するには、{Skill_name}が{姓名、名前、Eメールアドレス、電話番号}にアクセスする必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。

Para completar esta solicitação, {Skill_name} precisa ter acesso a seu {nome completo/nome próprio/endereço de e-mail/número de telefone}.Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.

Para completar esta solicitud, {Skill_name} necesita acceso a tu {nombre completo/nombre de pila/dirección de correo electrónico/número de teléfono}.Ve a la pantalla de inicio en tu aplicación Alexa y otorga los permisos para continuar.

ユーザーの連絡先情報が利用できない場合のフォールバックメッセージ

スキルがユーザーの連絡先情報をリクエストしてユーザーが権限を付与しても、ユーザーがAmazonに電話番号を提供していないなどの場合はその情報を利用できません。リクエストされたユーザー情報を利用できない場合、APIは204（no content）応答を返します。

この状況で、何らかの情報がないとスキルがリクエストを完了できない場合、Amazonアカウントにこの情報を入力するようユーザーにプロンプトを出すことができます。

resource_nameが利用できない場合のサンプルメッセージ

Your resource_name was not set.You can enter these details in your Amazon account, and then invoke the skill again.

Votre nom_de_ressource n'a pas été défini.Vous pouvez saisir ces détails dans votre compte Amazon, puis lancer la skill à nouveau.

Dein resource_name wurde nicht festgelegt.Du kannst diese Details in deinem Amazon-Konto eingeben und den Skill dann erneut aufrufen.

आपका resource_name सेट नहीं किया गया था। आप इन विवरणों को अपने Amazon खाते में दर्ज कर सकते हैं, और फिर skill को शुरू कर सकते हैं।

Il tuo resource_name non è stato impostato.Puoi inserire questi dettagli nel tuo account Amazon, quindi invocare nuovamente la skill.

resource_nameが設定されていません。Amazonアカウントでこれらの詳細を入力してから、スキルをもう一度呼び出してください

Seu resource_name não foi definido.Você pode inserir estes detalhes em sua conta Amazon, e depois invocar sua skill novamente.

Su resource_name no está configurado.Puede ingresar estos detalles en su cuenta de Amazon y luego invocar la skill nuevamente.

ユーザーの連絡先情報が利用できない場合の推奨ベストプラクティス

ユーザーが連絡先情報を設定していない場合、適切な応答をスキル開発者が設定することができます。

この情報がないとスキルが機能できないことを表す適切なフォールバックメッセージを提供し、セッションを終了します。

代わりに、スキルは動作を続けても、リクエストした情報がある場合に比べて実行できる機能が限定されることを表すメッセージを提供することもできます。

スキルを使いやすくするため、目的の情報を取得できなかった場合のすべてのシナリオを網羅したスキルワークフローを作成するようにしてください。

ベースURIとスキルの地域

AlexaユーザープロフィールAPIのエンドポイントはスキルの地域によって異なります。このJSONスニペットのように、正しいベースURLはSystemオブジェクトのapiEndpoint値（context.System.apiEndpoint）から取得できます。

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

このドキュメントの例では、日本のエンドポイント（api.fe.amazonalexa.com/）を使用しています。

複数言語用にスキルを設定する詳細については、多言語に対応するスキルを開発するを参照してください。

ユーザーの連絡先情報を取得する

以下のエンドポイントを使ってユーザーの連絡先情報を取得します（これらはリテラル文字列であることに注意してください）。エンドポイントでは大文字小文字が区別されます。

姓名/v2/accounts/~current/settings/Profile.name
名前/v2/accounts/~current/settings/Profile.givenName
Eメールアドレス/v2/accounts/~current/settings/Profile.email
電話番号/v2/accounts/~current/settings/Profile.mobileNumber

リクエストの例

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

Host: api.fe.amazonalexa.com
Accept: application/json
Authorization: Bearer MQEWY...6fnLok
GET https://api.fe.amazonalexa.com/v2/accounts/~current/settings/Profile.mobileNumber

リクエストヘッダー

ヘッダー 説明 型 必須
Authorization 次の形式での現在のアクセストークンです： Bearer < ACCESS_TOKEN > 文字列 ◯

応答の例

ヘッダー

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

本文

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

以下は、戻り値の型のリストです（すべてのJSON値）。

姓名"文字列"
名前"文字列"
Eメールアドレス"文字列"
電話番号{ "countryCode": "文字列", "phoneNumber": "文字列" }

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

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

応答ヘッダー

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

有効な応答

応答 説明
200 OK リクエストした情報が正常に取得されました。
204 No Content クエリーが値を返しませんでした。
401 Unauthorized 認証トークンの形式が正しくないか、無効です。
403 Unauthorized 認証トークンにリソースに対する権限がありません。
429 Too Many Requests リクエスト件数の超過によりスキルが制限されています。
500 Internal Error 想定外のエラーが発生しました。

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

最終更新日: 2023 年 05 月 30 日