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

所在地情報を使用してスキルを拡張する

作成したAlexaスキルをユーザーが有効にするとき、スキルはユーザーのAlexa端末に関連付けられている所在地データを使用するパーミッションをユーザーから得ることができます。 すると、スキルの主要な機能のため、あるいはユーザーエクスペリエンスを向上させるために、この所在地データを使用できるようになります。 たとえば、スキルはこの所在地情報を使って、近くの店舗の所在地一覧を提供したり、おすすめのレストランを紹介したりすることができます。 このドキュメントでは、この機能を有効にして端末の所在地APIにクエリを実行し、所在地データを調べる方法を説明します。

Alexa端末に入力する所在地は、端末の現在の物理的な所在地を表すとは限らないことに注意してください。 このAPIはユーザーがAlexaアプリに手動で入力する住所を使用します。 GPSや他の位置情報データをテストする機能はありません。

ユーザーからのパーミッションと端末所在地情報を取得する手順

以下の手順を使用して、端末の所在地情報を取得します。

  1. Amazon開発者ポータルでスキルを構成し、スキルが所在地情報を必要としていることを指定します。その結果、ユーザーはスキルを構成するときに、Alexaアプリのパーミッションカードにより、ユーザーの所在地情報を提供することを承諾するよう促されます。

    参考として、Alexaアプリでパーミッションを求められるときにユーザーに表示される内容を示します。この例のスキルは完全な住所を求めるパーミッションを得るように構成されているため、カードの内容もそれに合致したものになっています。

    Permissions card in the Alexa companion app
    Alexaコンパニオンアプリにおけるパーミッションカード
  2. ユーザーがスキルを有効にするときに、Alexa起動リクエストメッセージからdeviceIdconsentTokenを取得してください。
  3. 国コードと郵便番号の取得および所在地の取得に説明されているように、consentTokendeviceIdが入ったメッセージを適切な所在地エンドポイントに送信します。

端末の所在地のパーミッションをユーザーに要求するようスキルを構成する

  • Amazon開発者ポータルでスキルを開き、「Configuration」タブをクリックします。

    Permissions」セクションで「Device Address」を選択し、スキルが使用する内容に応じて「Full Address」または「Country & Postal Code Only」を選択します。「Save」をクリックします。

Dev Portal Permissions

参照:開発者ポータルでスキルを登録および管理する

ユーザーの承諾を得ると、Alexaからスキルへのリクエストには、 consentTokenが入ったuserオブジェクト、及び、 deviceIdが入ったdeviceオブジェクトが含まれます。 これらの値を取り出して、ユーザーの「Full Address」 または「Country & Postal Code」を求めるリクエストに含めなければなりません。 userオブジェクトとdeviceオブジェクトの例を次に示します。 userオブジェクトとdeviceオブジェクトはSystemオブジェクトの中で入れ子になり、それがさらにcontextオブジェクトの中で入れ子になります。リクエスト本文全体については、「リクエストフォーマット」を参照してください。

{
  "user": {
    "userId": "amzn1.ask.account.<userId_value>",
    "permissions": {
      "consentToken": "Atza|MQEWY...6fnLok"
    }
  },
  "device": {
    "deviceId": <device_id>,
    "supportedInterfaces": {}
  }
}

したがって、次のようになります。

deviceId = this.event.context.System.device.deviceId

コードがユーザーに「Full Address」または「Country & Postal Code」のいずれかを要求する場合には、次を含めてください。

  • deviceID(リクエストパスに)

  • 承諾トークン(Authorizationヘッダーに)。次の形式で含めます。Bearer CONSENT_TOKEN。ここでCONSENT_TOKENは、AlexaリクエストメッセージのconsentTokenフィールドの値です。以下に例を示します。

Authorization: Bearer Atc|MQEWY...6fnLok

したがって、次のようになります。 consentToken = this.event.context.System.user.permissions.consentToken

参照:Alexaから送信されたリクエストを処理する

ユーザーの承諾を要求するための新しいパーミッションカード

対話中、スキルに提供されるconsentTokenには、スキルがリクエストを実現するだけの十分なパーミッションがない場合があります。たとえば、有効化(音声による有効化)の際にユーザーがパーミッションを承諾しない場合や、スキルが更新されたために前のバージョンにはなかった新しいパーミッションが必要になる場合があります。こうした場合、スキルは特別なパーミッションカードを表示して、ユーザーに動的に承諾を求めることができます。

新しいカードAskForPermissionsConsentCard
インターフェースCardRenderer
定義
{
    "type": "AskForPermissionsConsent",
    "permissions": << list of scope strings >>
}
属性`permissions`: Alexaパーミッションに対応するスコープ文字列のリストが入ります。含めるのは、スキルに必要なAlexaパーミッションのうち、Amazon開発者ポータルでスキルメタデータの中に宣言されているものだけにします。

パーミッションカードの応答例

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

パーミッションの値は、次の表のようになります。

完全な住所国コードと郵便番号
read::alexa:device:all:addressread::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となります。

パーミッションの値は、Amazon開発者ポータルの「Configuration」ページで宣言したスキルのスコープと必ず対応します。

スキル開発時に端末の所在地APIをテストする

サービスシミュレーターは端末ではなく、deviceIdを提供することができないため、端末の所在地APIのテストには使用できません。それでも、リクエストと応答を調べてスキルをデバッグできます。

ユーザーがスキルにパーミッションを提供したケースをテストするには、Alexaコンパニオンアプリでスキルの所在地パーミッションを有効にしたことを確認してください。スキルを開くと(「Alexa、skill_nameを開いて」)、LaunchRequestが送信されます。パーミッションが有効になっている場合には、リクエストからdeviceIdconsentTokenを取得できます。

ユーザーがスキルに対してパーミッションを提供しなかったケースをテストするには、Alexaコンパニオンアプリでスキルの所在地パーミッションが有効でないことを確認します。スキルを開くと(「Alexa、skill_nameを開いて」)、LaunchRequestが送信されます。このリクエストにはdeviceId値が含まれますが、consentToken値は含まれません。

端末を使用したテストの詳細については、次を参照してください。カスタムスキルをテストする

AWS Lambda関数を使用するNode.jsスキルを、シミュレーターを使用しないでデバッグする方法について詳しくは、次を参照してください。AWS Lambdaコードをローカルでデバッグする

ユーザーがスキルを有効にした後、完全な住所であるか、国コードと郵便番号であるかを問わず、所在地情報を提供することを承諾するよう求めるプロンプトがAlexaアプリ内からユーザーに表示されます。

ユーザーが承諾しない場合、コードに、丁寧な代替メッセージを含めるようお勧めします。

所在地情報が提供されなくても一部の機能を利用できるようにスキルを開発することもできますし、所在地情報が提供されないとまったく機能しないように開発することもできます。

所在地情報がないとまったく機能しない場合の代替メッセージの例

skill_nameがAlexaアプリ内の所在地情報にアクセスすることを許可していただけませんでした。skill_nameは所在地情報なしでは機能しません。所在地情報へのアクセスを許可するには、skill_nameをもう一度有効にして、Alexaアプリ内の所在地情報を提供することを承諾してください」

所在地情報がないと一部の機能しか提供されない場合の代替メッセージの例

skill_nameがAlexaアプリ内の所在地情報にアクセスすることを許可していただけませんでした。この情報がないと、skill_nameの機能が限定されます。skill_nameに所在地情報へのアクセスを許可するには、skill_nameをもう一度有効にして、Alexaアプリで所在地情報を提供することを承諾してください」

スキルのベースURIと地理的な場所

ベースURIは、スキルの地理的な場所(ユーザーのAlexa端末の端末の所在地とは別の値)によって異なります。適切なベースURIを取得するには、apiEndpoint値をSystemオブジェクトに設定できます。

  • 端末の所在地データを呼び出すUS用のベースURI: https://api.amazonalexa.com/
  • 端末の所在地データを呼び出すUKおよびDE用のベースURI: https://api.eu.amazonalexa.com
  • 端末の所在地データを呼び出すJP用のベースURI: https://api.fe.amazonalexa.com

このページの例ではUS URIを使用しています。

国コードと郵便番号の取得

deviceIdで指定された端末に関連付けられている国コードと郵便番号を取得します。エンドポイントでは大文字小文字が区別されます。

  • エンドポイント: /v1/devices/*deviceId*/settings/address/countryAndPostalCode

リクエストメッセージの例

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer Atc|MQEWY...6fnLok
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address/countryAndPostalCode

リクエストのヘッダー

ヘッダー説明必須
Authorization現在の承諾トークン。フォーマットは次のとおりです。Bearer Atc|承諾トークン| string必須

リクエストのパラメーター

パラメーター 説明 必須
deviceId 国コードと郵便番号を取得するためのdeviceId string 必須

応答

成功応答メッセージの例

Country & Postal Code」のリクエストに対する成功応答の例を示します。

Host: api.amazonalexa.com
X-Amzn-RequestId: xxxx-xxx-xxx
Content-Type: application/json
{
  "countryCode" : "US",
  "postalCode" : "98109"
}

応答のヘッダー

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

応答パラメーター

パラメーター説明必須
countryCode指定の端末がある場所を示す、2文字の国コード。string必須
postalCode端末の郵便番号string必須

考えられる応答

応答 説明
200 OK deviceIdに関連付けられている国コードと郵便番号が正常に取得されました。
204 コンテンツなし クエリが何も結果を返しませんでした。
403 アクセス不可 認証トークンが無効、またはリソースに対するアクセス権がありません。
405 許可されていないメソッド このメソッドはサポートされていません。
429 リクエストが多すぎます リクエスト数が多すぎるため、スキルが制限されています。
500 内部エラー 予期しないエラーが発生しました。

住所の取得

deviceIdで指定された端末と関連付けられている完全な住所を取得します。

エンドポイント: /v1/devices/*deviceId*/settings/address

リクエストメッセージの例

Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer Atc|MQEWY...6fnLok
GET https://api.amazonalexa.com/v1/devices/{deviceId}/settings/address

リクエストのパラメーター

パラメーター 説明 必須
deviceId 住所を取得する対象のdeviceId string 必須

成功応答メッセージの例

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

{
  "stateOrRegion" : "WA",
  "city" : "Seattle",
  "countryCode" : "US",
  "postalCode" : "98109",
  "addressLine1" : "410 Terry Ave North",
  "addressLine2" : "",
  "addressLine3" : "aeiou",
  "districtOrCounty" : ""
}

応答のヘッダー

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

応答パラメーター

パラメーター 説明 必須
stateOrRegion リクエストで指定された端末に関連付けられている州や地域の省略形。米国以外の国ではこの値は空文字列になることがあります。 string 必須
city リクエストで指定された端末の市区町村。 string 必須
countryCode リクエストで指定された端末の、2文字の国コード。 string 必須
addressLine1 住所の1行目。 string 必須
addressLine2 住所の2行目。 string 必須。空文字列になる場合もあります
addressLine3 住所の3行目。 string 必須。空文字列になる場合もあります
districtOrCounty 端末に関連付けられている地域または郡。米国以外の国ではこの値は空文字列になることがあります。 string 必須

考えられる応答

応答 説明
200 OK このdeviceIdに関連付けられている住所が正常に取得されました。
204 コンテンツなし クエリが何も結果を返しませんでした。
403 アクセス不可 認証トークンが無効、またはリソースに対するアクセス権がありません。
405 許可されていないメソッド このメソッドはサポートされていません。
429 リクエストが多すぎます リクエスト数が多すぎるため、スキルが制限されています。
500 内部エラー 予期しないエラーが発生しました。

許可されていない所在地情報をスキルが求める場合

ユーザーは、端末の所在地情報を求めるリクエストに応じることも拒否することもできます。

ユーザーがパーミッションを付与していない所在地情報をスキルが求めると、スキルにはエラーが返されます。

端末の所在地情報に関するパーミッションをユーザーが付与したものの、端末の所在地情報が利用できない場合

スキルがユーザーの端末の所在地情報をリクエストし、ユーザーがそれを許可しても、所在地情報が利用できないことがあります。たとえば、ユーザーが所在地情報をAlexaに提供していない場合などです。この場合、以下に説明するように、特定のデフォルト値を受け取ることができます。

ユーザーが端末の所在地情報を提供していない場合、またはユーザーがサポート対象外の国にいる場合のNAリージョンにおける応答

端末の所在地情報をユーザーが提供していない場合、または郵便番号が軍関係の場合、postalCodeのデフォルト値「98109」を返される可能性があります。

ユーザーが端末の所在地情報を提供しない場合のEUリージョンにおける応答

可能な場合には、ユーザーのAmazonアカウント設定から端末の所在地情報が取得されます。情報を取得できない場合、null値が返されます。

NAリージョン以外のサポート対象外の国における応答

null値が返されます。

端末の所在地情報を利用できない場合に提案されているベストプラクティス

スキル開発者は、ユーザーが所在地情報を提供しない場合の適切な応答を判断できます。

この情報がないとスキルが機能しないことを記した丁寧な代替メッセージを提供してから、セッションを終了できます。

または、スキルは継続して動作するものの、リクエストされた所在地情報がある場合と比べて機能が限られることを記したメッセージを提供できます。

良好なユーザーエクスペリエンスのため、希望する端末の所在地情報が得られないあらゆる状況を念頭に置いてスキルワークフローを十分ご検討ください。

次のステップ

コーディングに関するトピック

その他のトピック:

リファレンス: