所在地情報を使用してスキルを拡張する
ユーザーがAlexaスキルを有効にすると、スキルはユーザーに、ユーザーのAlexaデバイスに関連付けられた所在地データを使用する許可を取得できます。この所在地データを使用して、スキルの主要機能を提供したり、ユーザーエクスペリエンスを向上させることができます。たとえば、スキルはこの所在地情報を使って、近くの店舗の所在地一覧を提供したり、おすすめのレストランを紹介したりすることができます。このドキュメントでは、この機能を有効にしてデバイスアドレスAPIにクエリを実行し、所在地データを調べる方法を説明します。
Alexaデバイスに入力される所在地は、デバイスの現在の物理的な所在地を表すとは限らないことに注意してください。このAPIはユーザーがAlexaアプリに手動で入力する住所を使用します。GPSや他の位置情報データをテストする機能はありません。
名前、Eメールアドレス、電話番号などのユーザーの連絡先情報をリクエストする方法については、スキルで使用するためにユーザーの連絡先情報をリクエストするを参照してください。
ユーザーが音声によって、Alexaデバイスの位置情報の共有を同意できるようにするには、Alexaスキルで音声による権限許可を有効にするを参照してください。
始める前に
ユーザーのデータを保護するため、デバイスのアドレス情報を使用するスキルはすべて、以下の要件を満たす必要があります。スキルが以下の要件のいずれかに違反しているとAmazonが判断した場合、スキル認定の申請を却下または保留にし、開発者アカウントに関連付けられたEメールアドレスに通知します。
- スキルに適用するプライバシーポリシーへのリンクを開発者コンソールの公開ページに含める必要があります。
- 子ども向けスキルは認められません。子ども向けスキルの詳細については、こちらを参照してください。
- スキルで提供する機能やサービスをサポートするために必要な場合にのみ、所在地情報を受け取る権限をリクエストする必要があります。リクエストする個人情報は、ユーザーの許可、プライバシー通知、適用される法令に従ってのみ利用するようにしてください。
- デバイスアドレス情報を使用して、バックグラウンドでユーザーのアカウントにリンクすることはできません。つまり、Alexaユーザーを同じ所在地情報を持つアカウントプールのユーザーに関連付けることは認められません。
- スキルは、ユーザーがユーザー情報を要求するリクエストを使用してスキルを呼び出すたびに、デバイスアドレスAPIを使用して最新のユーザー情報を取得する必要があります。
ユーザーからの権限とデバイスアドレス情報を取得する手順
以下の手順を使用して、デバイスアドレス情報を取得します。
-
開発者コンソールで、スキルが所在地情報を必要とすることを表示するよう設定します。その結果、ユーザーはスキルを構成するときに、Alexaアプリの権限カードにより、ユーザーの所在地情報を提供することを承諾するよう促されます。
参考として、Alexaアプリで権限を求められるときにユーザーに表示される内容を示します。この例のスキルは完全な住所を求める権限を得るように構成されているため、カードの内容もそれに合致したものになっています。
Alexaコンパニオンアプリにおける権限カード - ユーザーがスキルを呼び出すときに、Alexa起動リクエストメッセージから
deviceIdとapiAccessTokenを取得します。 - 国コードと郵便番号の取得および所在地の取得に説明されているように、
apiAccessTokenとdeviceIdが入ったメッセージを適切な所在地エンドポイントに送信します。
デバイスアドレスの権限をユーザーにリクエストするようスキルを設定する
- 開発者コンソールを使用してスキルを編集します。
- ビルド＞TOOLS＞アクセス権限ページに移動します。
- デバイスのアドレスを選択し、スキルが使用するものによって、住所または国／地域と郵便番号のみを選択します。
APIアクセストークンとデバイスIDの取得
スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。このトークンとデバイスID（deviceId）の両方を取得して、ユーザーの「Full Address」または「Country/Region & Postal Code」のリクエストに含める必要があります。
apiAccessTokenとデバイスID deviceIdの値はSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。リクエストの本文全体を見るには、リクエストの形式を参照してください。
{
"context": {
"System": {
"apiAccessToken": "AxThk...",
"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: Bearer AxThk...6fnLok
したがって、accessToken = this.event.context.System.apiAccessTokenとなります。
session.user.permissionsとcontext.System.user.permissions内にconsentTokenも含まれている場合があります。このプロパティは廃止になりました。consentTokenを使用する既存のスキルは引き続き機能しますが、代わりにcontext.System.apiAccessTokenプロパティが使用されます。ユーザー同意をリクエストする新しい権限カード
apiAccessTokenはスキルに対するすべてのリクエストに含まれます。これは、ユーザーがリクエストを完了するのに必要な権限をスキルに付与したかどうかは関係ありません。そのため、スキルがリクエストを完了するのに必要な正しい権限セットが、トークンに含まれていない可能性があります。スキルは特別な権限カードを表示して、ユーザーに動的に同意を求めることができます。
| 新しいカード | AskForPermissionsConsentCard |
|---|---|
| インターフェース | CardRenderer |
| 定義 |
|
| アトリビュート | permissions：Alexaの権限にマッピングされるスコープ文字列のリストを含みます。スキルに必要で、かつAmazon開発者ポータルのスキルメタデータで宣言されたAlexa権限のみが含まれます。 |
apiAccessTokenはすべてのスキルリクエストに含まれるため、apiAccessTokenが存在するかどうかで必要な権限があるかを判断することはできません。代わりにAPIを呼び出して、応答コードを確認します。スキルに権限がない場合は403 Forbiddenの応答が返されるため、その時点でスキルのAlexaへの応答にAskForPermissionsConsentカードを含めることができます。
権限カードありの応答のサンプル
セッション内の対話で、新しいAskForPermissionsConsentカードを含む応答を返すことができます。
permissions値には、以下の表の値が含まれます。
| 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の値は、Amazon開発者ポータルのビルド＞アクセス権限ページでスキルに対して宣言したスコープと同じです。
スキル開発時にデバイスアドレスAPIをテストする
開発者コンソールのテストページでは、一部のテストのみを実施できます。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アプリ内からユーザーに表示されます。
ユーザーが承諾しない場合、コードに、丁寧なフォールバックメッセージを含めるようお勧めします。
所在地情報が提供されなくても一部の機能を利用できるようにスキルを開発することもできますし、所在地情報が提供されないとまったく機能しないように開発することもできます。
所在地情報がないとまったく機能しない場合のフォールバックメッセージの例
「skill_nameがAlexaアプリ内の所在地情報にアクセスすることを許可していただけませんでした。skill_nameは所在地情報なしでは機能しません。所在地情報へのアクセスを許可するには、Alexaアプリ内の所在地情報を提供することを承諾してください」
所在地情報がないと一部の機能しか提供されない場合のフォールバックメッセージの例
「skill_nameがAlexaアプリ内の所在地情報にアクセスすることを許可していただけませんでした。この情報がないと、skill_nameの機能が限定されます。skill_nameに所在地情報へのアクセスを許可するには、skill_nameをもう一度有効にして、Alexaアプリで所在地情報を提供することを承諾してください」
スキルのベースURIと地理的な場所
デバイスアドレスAPIのエンドポイントは、スキルの地理的な場所によって異なります。正しいベースURLはSystemオブジェクト（context.System.apiEndpoint）の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 MQEWY...6fnLok
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode
リクエストヘッダー
| ヘッダー | 説明 | 型 | 必須 |
|---|---|---|---|
Authorization |
次の形式での現在のアクセストークンです： Bearerアクセストークン |
文字列 |
◯ |
リクエストのパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
deviceId |
国または地域と郵便番号を取得するためのdeviceIdです。 |
文字列 |
◯ |
応答
成功応答メッセージの例
「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文字の国コードです。 | 文字列 | ◯ |
postalCode | デバイスの郵便番号です。 | 文字列 | ◯ |
考えられる応答
| 応答 | 説明 |
|---|---|
| 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 MQEWY...6fnLok
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address
リクエストのパラメーター
| パラメーター | 説明 | 型 | 必須 |
|---|---|---|---|
deviceId |
住所を取得するためのdeviceIdです。 |
文字列 |
◯ |
成功応答メッセージの例
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 |
リクエストで指定されたデバイスに関連付けられている州や地域の省略形です。米国以外の国ではこの値は空文字列になることがあります。 | 文字列 |
◯ |
city |
リクエストで指定されたデバイスの市区町村です。 | 文字列 |
◯ |
countryCode |
リクエストで指定されたデバイスの、2文字の国コードです。 | 文字列 |
◯ |
addressLine1 |
住所の1行目です。 | 文字列 |
◯ |
addressLine2 |
住所の2行目です。 | 文字列 |
必須。空文字列になる場合もあります。 |
addressLine3 |
住所の3行目です。 | 文字列 |
必須。空文字列になる場合もあります。 |
districtOrCounty |
デバイスに関連付けられている地域または郡。米国以外の国ではこの値は空文字列になることがあります。 | 文字列 |
◯ |
考えられる応答
| 応答 | 説明 |
|---|---|
| 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値が返されます。
デバイスアドレス情報が利用できない場合の推奨ベストプラクティス
スキル開発者は、ユーザーが所在地情報を提供しない場合の適切な応答を判断できます。
この情報がないとスキルが機能しないことを表す適切なフォールバックメッセージを提供し、セッションを終了することもできます。
代わりに、スキルは動作を続けますが、リクエストされた所在地情報がある場合に比べて実行できる機能が限定されることを表すメッセージを提供することもできます。
スキルを使いやすくするため、目的のデバイスアドレス情報を取得できなかった場合のすべてのシナリオを網羅したスキルワークフローを作成するようにしてください。