開発者コンソール
ログイン
ログイン
開発者コンソール

SSIクライアントAPI

SSIクライアントAPI

このセクションでは、Appstore SDKに含まれるシンプルサインインAPIについて説明します。APIリファレンスの全文は、最新のAppstore SDK APIリファレンスで参照できます。

一般的なデータ型

以下は、シンプルサインイン（SSI）APIの操作中に出現する可能性のある一般的なデータ型です。

RequestStatus

RequestStatusは、SSI APIへのリクエストのステータスを示す列挙型です。リクエストの成功または失敗を示す列挙値がレスポンスに含まれます。返される可能性のあるさまざまな値とその意味は、次の表のとおりです。

名前 説明
SUCCESSFUL リクエストが正常に処理されたことを示します。
FAILURE リクエストの処理中に再試行できないエラーが発生したことを示します。
RETRYABLE_FAILURE リクエストの処理中に再試行できる一時的なエラー（タイムアウトやサービスを利用できないエラーなど）が発生したことを示します。
NOT_SUPPORTED 特定のデバイスでリクエストを処理できない場合（SSI機能を含む最新のソフトウェアにデバイスがアップグレードされていない場合など）に返されます。
NOT_AVAILABLE 機能はサポートされているものの、特定の公開停止ルールが原因で現在利用できない場合に返されます。理由は以下のとおりです。

- 機能がユーザーのマーケットプレイスで無効になっている。
- 機能が特定のアプリでブロックされている。
- 機能がサポートされていないモードでデバイスが動作している。モードの例：Fireタブレットの子ども用プロフィールモード、Fire TVのゲストユーザーモード。
DUPLICATE_REQUEST 別のリクエストが行われたときに、リクエストが重複していることを示します。
FEATURE_TURNED_OFF ユーザーが機能をオフにしました。
INVALID_LINK_SIGNING_KEY_ENCRYPTION linkUserAccount() APIリクエストで指定されたLinkSigningKeyを、Amazon側で復号化できません。
INVALID_LINK_SIGNING_KEY linkUserAccount() APIリクエストで指定されたLinkSigningKeyが、SSIトークンに署名するための有効なプライベートキーではない場合に返されます。

RequestId

RequestIdは、アプリからのリクエストごとに、SSI APIによって割り当てられた一意の識別子をラップします。

フィールド 型 必須
（Y/N）		 説明
id 文字列 Y このリクエストに割り当てられた一意のID。

トークン

トークンは、APIリクエストオブジェクトとレスポンスオブジェクトでリンクトークンとSSIトークンの両方を表す複合型です。

フィールド 型 必須
（Y/N）		 説明
token 文字列 Y エンコードされたトークンペイロード。
schema 文字列 Y トークンのスキーマ識別子。サポートされているスキーマは以下のとおりです。
- リンクトークン： LINK-TOKEN-1.0
- SSIトークン： SSI-TOKEN-1.0

リンクは、ユーザーのAmazonユーザーIDとアプリのユーザーIDのアカウントリンク関係、および関連するメタデータを表します。

フィールド 型 必須
（Y/N）		 説明
linkId 文字列 Y Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。
amazonUserId 文字列 Y アカウントリンク関係の一部であるAmazonユーザーアカウントのスコープ識別子。
partnerUserId 文字列 Y アカウントリンク設定中にユーザーIDを表すために発行する不透明な識別子。
identityProviderName 文字列 Y システムでユーザーを認証するために使用するIDプロバイダーの名前。
ssiToken トークン Y Amazonが発行するSSIトークン。
linkedTimestamp long Y アカウントリンクが設定されたときのタイムスタンプ（エポック）。

LinkUserAccount API

linkUserAccount() APIは、ユーザーのアプリアカウントのアカウントリンクを開始するために使用されます。このソリューションでは、Amazonとアプリアカウントの間の多対多マッピングが可能になります。1つのAmazonアカウントに複数のアプリアカウントをリンクさせることができ、また、1つのアプリアカウントに複数のAmazonアカウントを同時にリンクさせることもできます。

アカウントリンクを設定する前に、シンプルサインインクライアントがユーザー同意画面を表示してユーザーに同意を促します。ユーザーの同意を得る際、リンクデータとlinkTokenはシンプルサインインサーバーに保存されます。ユーザーがアカウントリンクへの同意を拒否した場合、リンクプロセスは中止され、ユーザーから受け取ったlinkTokenは破棄されます。

リクエストとレスポンス

このAPIのリクエストオブジェクトは、LinkUserAccountRequest型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
partnerUserId 文字列 Y Amazonに対してユーザーのIDを表す不透明な識別子。この識別子は、アプリアカウントが既にAmazonアカウントにリンクされている場合に、アカウントリンクリクエストの重複排除に使用されます。
identityProviderName 文字列 Y アプリにサインインしているユーザーを認証するために使用するIDプロバイダーの名前。IDプロバイダーを表す意味のある文字列値を選択できます。
userLoginName 文字列 Y ユーザー同意画面に表示される、アプリアカウントに関連付けられたログイン名。
linkToken トークン Y アカウントのリンク関係を表すリンクトークン。トークン型の定義については、トークンを参照してください。
linkSigningKey 文字列 Y LinkKeyPairのプライベートキー部分。アプリのリビジョンに対応するAppStoreKeyPairからPublicKeyを使用して暗号化されます。

レスポンスオブジェクトでは、LinkUserAccountResponse型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
requestId RequestId Y 一般的なデータ型のRequestIdを参照してください。
requestStatus RequestStatus Y 一般的なデータ型のRequestStatusを参照してください。
successCode SuccessCode N アカウントリンクリクエストが正常に処理されると、SuccessCode列挙型がより詳細なステータスを示します。

名前： LinkAlreadyExists
説明： 指定されたIDペアにアカウントリンク関係が既に存在するため、リクエストが重複排除されました。

名前： LinkEstablished
説明： ユーザーの同意が得られ、アカウントリンク関係が正常に設定されました。

名前： ConsentDenied
説明： ユーザーがアカウントリンクへの同意を拒否し、リクエストが中止されました。
linkId 文字列 N Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。

getUserAndLinks() APIは、リクエスト元のアプリを介して、デバイスで現在アクティブなAmazonユーザーのシンプルサインイン関連データを取得するために使用されます。APIレスポンスには、以下のデータが含まれます。

  • アクティブなリンク済みアカウントのリスト、および各アカウントの新しいSSIトークン。
  • AmazonユーザーのスコープID。トークン生成時にlinkTokenの範囲をAmazonユーザーに限定するためにアプリで使用されます。

リクエストとレスポンス

APIは、開発者のIDをリクエストします。

フィールド 型 必須
（Y/N）		 説明
identityProviderName 文字列 Y IDプロバイダーの名前。この名前には、意味のある文字列値を選択できます。アカウントリンク時にlinkUserAccount() APIに提供されたものと一致している必要があります。

レスポンスオブジェクトでは、GetUserAndLinksResponse型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
requestId RequestId Y 一般的なデータ型のRequestIdを参照してください。
requestStatus RequestStatus Y 一般的なデータ型のRequestStatusを参照してください。
amazonUserId 文字列 N デバイスでアクティブなAmazonユーザーアカウントのスコープ識別子。
links List<Link> N リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。

ShowLoginSelection API

showLoginSelection() APIは、ユーザーにログイン画面を表示するために使用されます。showLoginSelection()を開始する前に、getUserAndLinks()を使用して取得されるリンク済みアカウントごとに、アプリはユーザーが認識しやすい識別子（ログイン名／Eメールアドレス／プロファイル名）をアプリサーバーから取得し、このデータをリクエストに含めます。このデータは画面に表示され、リンクされたアプリアカウントをユーザーが認識しやすくするために使用されます。

リクエストとレスポンス

このAPIは、リンクされたアプリユーザーアカウントのログイン名のマップをリクエストします。

フィールド 型 必須
（Y/N）		 説明
loginNames Map<String, String> Y ユーザーが認識できるログイン名へのlinkIdのマップ。アプリがすべてのリンク済みアカウントを取得するためにgetUserAndLinks()を呼び出し、Linkオブジェクトのリストを取得すると、linkId文字列が返されます。

レスポンスオブジェクトでは、ShowLoginSelectionResponse型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
requestId RequestId Y 一般的なデータ型のRequestIdを参照してください。
requestStatus RequestStatus Y 一般的なデータ型のRequestStatusを参照してください。
userSelection UserSelection N ログイン画面でユーザーが行った選択の列挙型。使用可能な値は次のとおりです。

名前： ManualSignIn
説明： リンク済みアカウントを無視して手動でログインすることをユーザーが選択しました。

名前： LoginSelected
説明： 提供されているリンク済みアカウントのいずれかからサインインするアカウントをユーザーが選択しました。
links List<Link> N リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。

RecordMetricEvent API

recordMetricEvent() APIは、指標公開用に記録する必要があるイベントをトリガーするために使用されます。シンプルサインインのビジネス指標レポートは、開発者コンソールの [レポート] タブでダウンロードできます。これらの指標は、SSIの統合によるビジネス価値や影響を把握するためのものです。

リクエストとレスポンス

このAPIのリクエストオブジェクトは、SSIEventRequest型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
event SSIEvent Y 指標イベントの記録リクエストの場合、SSIEventは公開可能な指標を示す列挙型です。値は以下のとおりです。

名前： LOGIN_SUCCESS
説明： SSIを使用したログインに成功したことを表します。

名前： LOGIN_FAILURE
説明： SSIを使用したログインに失敗したことを表します。

名前： MANUAL_SIGNIN_SELECTED
説明： ユーザーが（2回目以降のサインイン試行時に）以前にリンクされたアカウントを無視して手動でのサインインを選択する場合を表します。
epochTimestamp 文字列 Y 特定のイベントがトリガーされたときのタイムスタンプ（エポック）
failureReason FailureReason N SSIを使用したログインが失敗した場合に、考えられる失敗の理由を表す列挙型。LOGIN_FAILUREイベントの場合は必須です。値は以下のとおりです。

名前： UNAUTHORIZED
説明： ユーザーにログインする権限がありません。

名前： BAD_REQUEST
説明： リクエストが破損しています。

名前： NOT_FOUND
説明： ユーザーが探しているログインページが見つかりません。

名前： FORBIDDEN
説明： ログイン機会がありません。

名前： INTERNAL_SERVER_ERROR
説明： ログインに何らかの問題があります。

レスポンスオブジェクトでは、RecordMetricsEventResponse型を使用します。これには以下のフィールドが含まれます。

フィールド 型 必須
（Y/N）		 説明
requestId RequestId Y 一般的なデータ型のRequestIdを参照してください。
requestStatus RequestStatus Y 一般的なデータ型のRequestStatusを参照してください。