所在地情報を使用してスキルを拡張する
ユーザーがAlexaスキルを有効にすると、スキルはユーザーから、ユーザーのAlexaデバイスに関連付けられた所在地データを使用する許可を得ることができます。この所在地データを使用して、スキルの主要機能を提供したり、ユーザーエクスペリエンスを向上したりすることができます。たとえば、スキルはこの所在地情報を使って、近くの店舗の所在地一覧を提供したり、おすすめのレストランを紹介したりすることができます。
名前、Eメールアドレス、電話番号といったユーザーの連絡先情報をリクエストする方法について詳しくは、スキルで使用するためにユーザーの連絡先情報をリクエストするを参照してください。
ユーザーが音声によって、Alexaデバイスの郵便番号の共有を同意できるようにするには、Alexaスキルで音声による同意確認を使用するを参照してください。
始める前に
ユーザーのデータを保護するため、デバイスのアドレス情報を使用するスキルはすべて、次の要件を満たす必要があります。スキルがこれらの要件のいずれかに違反しているとAmazonが判断した場合、Amazonはスキル認定の申請を却下または保留にし、開発者アカウントに関連付けられたEメールアドレスに通知します。
- スキルに適用するプライバシーポリシーへのリンクをAlexa開発者コンソールの公開ページに含める必要があります。
- 子ども向けスキルでは使用できません。子ども向けスキルの詳細については、ポリシーの要件を参照してください。
- スキルで提供する機能やサービスをサポートするために必要な場合にのみ、所在地情報を受け取る権限をリクエストする必要があります。取得した個人情報は、そのユーザーの許可を得たうえで、プライバシーに関する通達および関連法令に則って利用する必要があります。
- デバイスアドレス情報を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ所在地情報を持つアカウントプールのユーザーに関連付けることは認められません。
- スキルは、ユーザーがユーザー情報を要求するリクエストを使用してスキルを呼び出すたびに、デバイスアドレスAPIを使用して最新のユーザー情報を取得する必要があります。
ユーザーからの権限とデバイスアドレス情報を取得する手順
デバイスアドレス情報は、次の手順で取得します。
- スキルが所在地情報を必要とすることを表示するようスキルを設定します。
- ユーザーがスキルを呼び出すときに、Alexa起動リクエストから
deviceIdとapiAccessTokenを取得します。 apiAccessTokenとdeviceIdが入ったメッセージを適切な所在地エンドポイントに送信します。
ステップ1： デバイスアドレスの権限をユーザーにリクエストするようスキルを設定する
デバイスアドレスの権限をユーザーにリクエストするようスキルを設定するには、開発者コンソールで次の手順を実行します。
- 開発者コンソールを使用してスキルを編集します。
- ビルド＞ツール＞アクセス権限ページに移動します。
- デバイスのアドレスを選択し、スキルがどの情報を使用するかに応じて、住所または国／地域と郵便番号のみを選択します。
これらの権限を設定した場合、Alexaアプリで、スキルの設定時に所在地情報を提供する同意を求める権限カードのプロンプトが、ユーザーに表示されます。次の画像は、Alexaアプリに権限を求めるプロンプトが出たときにユーザーに表示される画面です。この例のスキルは、完全な住所を取得する権限を求めるよう設定されています。
ステップ2： APIアクセストークンとデバイスIDを取得する
スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。このトークンとデバイスID（deviceId）の両方を取得して、ユーザーの「Full Address」または「Country/Region & Postal Code」のリクエストに含める必要があります。
apiAccessTokenとデバイスID deviceIdの値はSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。リクエストの本文全体は、リクエストの形式を参照してください。
{
"context": {
"System": {
"apiAccessToken": "12345example",
"apiEndpoint": "https://api.fe.amazonalexa.com",
"device": {
"deviceId": "string-identifying-the-device",
"supportedInterfaces": {}
},
"application": {
"applicationId": "string"
},
"user": {}
}
}
}
起動リクエストでは、deviceIdはthis.event.context.System.device.deviceIdです。
コードがユーザーから「Full Address」または「Country/Region & Postal Code」のいずれかをリクエストする場合には、次の情報をリクエストに含めてください。
-
deviceID（リクエストパスに）。 -
アクセストークン（
Authorizationヘッダーに）。BearerACCESS_TOKENの形式で指定します。このACCESS_TOKENには、AlexaリクエストメッセージのapiAccessTokenフィールドの値が入ります。以下は、アクセストークンを指定したAuthorizationヘッダーの例です。Authorization: Bearer 12345example
起動リクエストでは、accessTokenはthis.event.context.System.apiAccessTokenです。
session.user.permissionsとcontext.System.user.permissions内にconsentTokenも含まれている場合があります。このプロパティは廃止になりました。consentTokenを使用する既存のスキルは引き続き機能しますが、代わりにcontext.System.apiAccessTokenプロパティを使用してください。ステップ3： apiAccessTokenとdeviceIdが入ったメッセージを適切な所在地エンドポイントに送信する
国コードと郵便番号の取得および住所の取得操作を使用します。
権限カードの例
Alexaは、スキルに対するすべてのリクエストにapiAccessTokenを含めます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかには関係ありません。このため、apiAccessTokenが存在するかどうかで必要な権限があるかを判断することはできません。代わりにAPIを呼び出して、応答コードを確認します。403 Forbidden応答は、スキルに必要な権限がないことを表します。
その場合、スキルは権限カードを表示して、ユーザーに動的に同意を求めることができます。このセクションでは、権限カードの例を示します。
ユーザー同意をリクエストする新しい権限カード
| 新しいカード | AskForPermissionsConsentCard |
|---|---|
| インターフェース | CardRenderer |
| 定義 |
|
| アトリビュート | permissions：Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつAmazon開発者ポータルのスキルメタデータで宣言されたAlexa権限のみが含まれます。 |
権限カードありの応答のサンプル
セッション内の対話で、AskForPermissionsConsentカードを含む応答を返すことができます。
次の表の権限を使用できます。
| Full address | Country/Region and postal code |
|---|---|
| read::alexa:device:all:address | read::alexa:device:all:address:country_and_postal_code |
以下は、完全な住所をリクエストするカードの応答サンプルです。
{
"version": "1.0",
"response": {
"card": {
"type": "AskForPermissionsConsent",
"permissions": [
"read::alexa:device:all:address"
]
}
}
}
国／地域と郵便番号のリクエストの場合、この応答のpermissions値は「read::alexa:device:all:address:country_and_postal_code」となります。
permissionsの値は常に、Alexa開発者コンソールのBuild > Permissionsページでスキルに対して宣言したスコープと同じです。
スキル開発時にデバイスアドレスAPIをテストする
開発者コンソールでAlexaシミュレーターを使うと、限定的なテストを行うことができます。Alexaシミュレーターを使ったテスト時に、スキルはデバイスアドレスAPIを呼び出してエラーのない応答を受け取ることができます。ユーザーがデバイスアドレスの権限を付与しなかった場合のフローをテストすることもできます。
ただし、応答の住所フィールドはnullに設定され、郵便番号フィールドはデフォルトの米国の郵便番号が設定されることに注意してください。
テストページはAlexaアプリの完全なデバイスとして設定することができません。包括的なテストには実際のデバイスを使用することを推奨します。
ユーザーがスキルに権限を付与した場合のテストをするには、Alexaアプリでスキルのアドレスの権限を有効にしておいてください。スキルを開くと（「アレクサ、skill_nameを開いて」）、スキルにLaunchRequestが送信されます。権限が有効になっていれば、リクエストからdeviceIdとapiAccessTokenを取得できます。
ユーザーがスキルに権限を付与しなかった場合のテストをするには、Alexaアプリでスキルのアドレス権限が有効になっていないことを確認してください。スキルを開くと（「アレクサ、skill_nameを開いて」）、LaunchRequestが送信されます。このリクエストにはdeviceIdの値とapiAccessTokenの値が含まれますが、apiAccessTokenは正しい権限を指定していません。このトークンをデバイスアドレスAPIに渡すと、403 Forbidden応答コードが返されます。
テストの詳細については、スキルのテストを参照してください。
AWS Lambda関数を使用するNode.jsスキルを、シミュレーターを使用しないでデバッグする方法について詳しくは、AWS Lambdaコードをローカルでデバッグするを参照してください。
ユーザーが権限付与を承諾しない場合のフォールバックメッセージ
ユーザーがスキルを有効にすると、Alexaアプリはユーザーに所在地情報の提供に同意するよう、プロンプトを表示します。この情報は、スキルの設定によって、完全な住所、国／地域および郵便番号のいずれかになります。
ユーザーが承諾しない場合、コードに、丁寧なフォールバックメッセージを含めてください。
一部の機能は所在地情報がなくても利用できるようにスキルを作成できます。また、所在地情報がないとまったく機能しないようスキルを作成することもできます。
所在地情報がないとまったく機能しない場合のフォールバックメッセージの例
次の発話は、所在地情報がないとまったく機能しないスキルのフォールバックメッセージです。
In order to use {Skill_name}, please permit access to your address information.Go to the home screen in your Alexa app and grant the permissions to continue.
Afin d'utiliser {Skill_name}, veuillez autoriser l'accès à votre adresse.Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.
Um {Skill_name} nutzen zu können, erlaube bitte den Zugriff auf deine Adressinformationen.Gehe auf die Startseite in deiner Alexa-App und erteile die Berechtigung um Fortzufahren.
{Skill_name}का उपयोग करने के लिए, कृपया अपनी पता जानकारी तक पहुंच की अनुमति दें। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें
Per poter utilizzare {Skill_name}, consenti l'accesso alle informazioni sul tuo indirizzo.Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.
{Skill_name}を使用するには、位置情報へのアクセスを許可する必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。
Para usar {Skill_name}, por favor, permita o acesso às informações de seu endereço.Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.
Para usar {Skill_name}, por favor permita acceder a la información de su dirección.Vaya a la pantalla de inicio en su aplicación Alexa y otorgue los permisos para continuar.
所在地情報がないと一部の機能しか提供されない場合のフォールバックメッセージの例
次の発話は、所在地情報がないと一部の機能しか提供されないスキルのフォールバックメッセージです。
In order to complete this functionality, {Skill_name} needs access to your address information.Go to the home screen in your Alexa app and grant the permissions to continue.
Afin de compléter cette fonctionnalité, {Skill_name} a besoin d'accéder à votre adresse.Allez à l'écran d'accueil de votre application Alexa et accordez les autorisations pour continuer.
Um diese Funktion ausführen zu können, benötigt {Skill_name} Zugriff auf deine Adressdaten.Gehe zum Startbildschirm in deiner Alexa-App und erteile die Berechtigung um fortzufahren.
इस कार्यक्षमता को पूरा करने के लिए, {Skill_name} को आपकी पता जानकारी तक पहुंच की आवश्यकता है। अपने एलेक्सा ऐप में होम स्क्रीन पर जाएं और जारी रखने की अनुमति दें।
Per completare questa funzionalità, {Skill_name} deve accedere alle informazioni sul tuo indirizzo.Vai alla schermata iniziale della tua app Alexa e concedi le autorizzazioni per continuare.
この機能を完了するには、{Skill_name}がデバイスの位置情報にアクセスする必要があります。続行するにはAlexaアプリのホーム画面でスキルに権限を付与してください。
Para completar esta funcionalidade, {Skill_name} precisa ter acesso às informações de seu endereço.Vá para a tela inicial em seu aplicativo Alexa e conceda as permissões para continuar.
Para completar esta funcionalidad, {Skill_name} necesita acceso a la información de tu dirección.Ve a la pantalla de inicio en tu aplicación Alexa y otorga los permisos para continuar.
APIリファレンス
デバイスアドレスAPIのエンドポイントは、スキルの地理的な場所によって異なります。正しいベースURLはSystemオブジェクトのapiEndpoint値から取得できます。つまり、APIエンドポイントは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": {}
}
このページの例では、日本のエンドポイント（https://api.fe.amazonalexa.com/）を使用しています。
複数言語用にスキルを設定する詳細については、多言語に対応するスキルを開発するを参照してください。
国コードと郵便番号の取得
deviceIdで指定されたデバイスに関連付けられている国／地域と郵便番号を取得します。エンドポイントでは大文字小文字が区別されます。
エンドポイント：/v1/devices/*deviceId*/settings/address/countryAndPostalCode
リクエストメッセージの例
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer 12345example
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode
リクエストヘッダー
| ヘッダー | 説明 | 型 | 必須 |
|---|---|---|---|
Authorization |
次の形式での現在のアクセストークンです： Bearerアクセストークン |
string |
◯ |
リクエストのパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
deviceId |
国または地域と郵便番号を取得するためのdeviceIdです。 |
string |
◯ |
応答
成功応答メッセージの例
以下に「Country/Region & Postal Code」のリクエストに対する成功応答の例を示します。
Host: api.fe.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json
{
"countryCode" : "JP",
"postalCode" : "98109"
}
応答ヘッダー
| ヘッダー | 説明 |
|---|---|
Content-Type |
application/json |
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
応答のパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
countryCode | 指定のデバイスがある場所を示す、2文字の国コードです。 | string | ◯ |
postalCode | デバイスの郵便番号です。 | string | ◯ |
有効な応答
| 応答 | 説明 |
|---|---|
| 200 OK | deviceIdに関連付けられている国または地域と郵便番号が正常に取得されました。 |
| 204 No Content | クエリーが値を返しませんでした。 |
| 403 Forbidden | 認証トークンが無効か、リソースに対するアクセス権限がありません。 |
| 404 Not Found | たとえば、deviceIdが無効なために、指定されたURIがリソースを見つけられません。 |
| 405 Method Not Allowed | メソッドがサポートされていません。 |
| 429 Too Many Requests | リクエスト件数の超過によりスキルが制限されています。 |
| 500 Internal Error | 想定外のエラーが発生しました。 |
住所の取得
deviceIdで指定されたデバイスに関連付けられている完全な住所を取得します。
エンドポイント：/v1/devices/*deviceId*/settings/address
リクエストメッセージの例
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer 12345example
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address
リクエストのパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
deviceId |
住所を取得するためのdeviceIdです。 |
string |
◯ |
成功応答メッセージの例
Host: api.fe.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json
{
"stateOrRegion" : "東京都",
"city" : "神戸",
"countryCode" : "JP",
"postalCode" : "98109",
"addressLine1" : "410 Terry Ave North",
"addressLine2" : "",
"addressLine3" : "aeiou",
"districtOrCounty" : ""
}
応答ヘッダー
| ヘッダー | 説明 |
|---|---|
Content-Type |
application/json |
X-Amzn-RequestId |
リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
応答のパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
stateOrRegion |
リクエストで指定されたデバイスに関連付けられている州や地域の省略形です。米国以外の国ではこの値は空文字列になることがあります。 | string |
◯ |
city |
リクエストで指定されたデバイスの市区町村です。 | string |
◯ |
countryCode |
リクエストで指定されたデバイスの、2文字の国コードです。 | string |
◯ |
addressLine1 |
住所の1行目です。 | string |
◯ |
addressLine2 |
住所の2行目です。この値は空文字列になることがあります。 | string |
◯ |
addressLine3 |
住所の3行目です。この値は空文字列になることがあります。 | string |
◯ |
districtOrCounty |
デバイスに関連付けられている地域または郡。米国以外の国ではこの値は空文字列になることがあります。 | string |
◯ |
有効な応答
| 応答 | 説明 |
|---|---|
| 200 OK | このdeviceIdに関連付けられている住所が正常に取得されました。 |
| 204 No Content | クエリーが値を返しませんでした。 |
| 403 Forbidden | 認証トークンが無効か、リソースに対するアクセス権限がありません。 |
| 405 Method Not Allowed | メソッドがサポートされていません。 |
| 429 Too Many Requests | リクエスト件数の超過によりスキルが制限されています。 |
| 500 Internal Error | 想定外のエラーが発生しました。 |
許可されていない所在地情報をスキルが求める場合
ユーザーは、デバイスの所在地情報を求めるリクエストに応じることも拒否することもできます。
ユーザーが権限を付与していない所在地情報をスキルが求めると、スキルにはエラーが返されます。
デバイスの所在地情報に関する権限をユーザーが付与したにもかかわらず、デバイスの所在地情報が利用できない場合
スキルがユーザーのデバイスの所在地情報をリクエストし、ユーザーがそれを許可しても、所在地情報が利用できないことがあります。たとえば、ユーザーが所在地情報をAlexaに提供していない場合などです。この場合、以下のセクションで説明するように、特定のデフォルト値を受け取ることができます。
ユーザーがデバイスの所在地情報を提供していない場合、またはユーザーがサポート対象外の国または地域にいる場合のNAリージョンにおける応答
デバイスの所在地情報をユーザーが提供していない場合、または郵便番号が軍関係の場合、postalCodeのデフォルト値「98109」を返される可能性があります。
ユーザーがデバイスの所在地情報を提供していない場合のEUリージョンにおける応答
可能な場合には、ユーザーのAmazonアカウント設定からデバイスの所在地情報が取得されます。情報を取得できない場合、null値が返されます。
NAリージョン以外のサポート対象外の国における応答
null値が返されます。
デバイスの所在地情報が利用できない場合のベストプラクティス
スキル開発者は、ユーザーが所在地情報を提供しない場合の適切な応答を判断できます。
この情報がないとスキルが機能できないことを表す適切なフォールバックメッセージを提供し、セッションを終了します。
代わりに、スキルは動作を続けますが、リクエストされた所在地情報がある場合に比べて実行できる機能が限定されることを表すメッセージを提供することもできます。
スキルを使いやすくするため、目的のデバイスアドレス情報を取得できなかった場合のすべてのシナリオを網羅したスキルワークフローを作成するようにしてください。
関連トピック
最終更新日: 2023 年 05 月 30 日