アカウントリンク管理REST APIリファレンス

アカウントリンク管理REST APIリファレンス

アカウントリンク管理REST APIを使用して、Alexaユーザーアカウントを他のOAuth IDプロバイダーにリンクする際に使用するスキル情報を管理します。アカウントリンクの詳細については、アカウントリンクの構成要素を参照してください。

アカウントリンク情報の管理には、Alexa Skills Kitコマンドラインインターフェース（ASK CLI）を使うこともできます。

APIエンドポイント

アカウントリンク管理APIのエンドポイントは、http://api.amazonalexa.comです。

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with HAQM（LWA）から取得したアクセストークンが入ります。詳細については、SMAPIで使用するアクセストークンの取得方法を参照してください。

操作

アカウントリンク管理APIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

アカウントリンク情報を削除する

DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

アカウントリンク情報を取得する

GET /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

アカウントリンク情報を更新する

PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient

アカウントリンク情報を削除する

指定されたスキルステージの指定されたスキルからアカウントリンク情報を削除します。

リクエスト

アカウントリンク情報を削除するには、accountLinkingClientリソースにDELETEリクエストを送信します。

リクエストパスとリクエストヘッダーの例

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

skillId

パス

スキルを識別します。
有効な値： 1～255文字

文字列

◯

stage

パス

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

◯

access token

ヘッダー

LWAトークン。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

アカウントリンク情報が削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラーコードとメッセージを含む応答本文の例です。

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

指定されたスキルに関連するアカウントリンク情報を取得します。

アカウントリンク情報を取得するには、 accountLinkingClientリソースにGETリクエストを送信します。

パラメーター 指定場所 説明 型 必須

skillId

パス

スキルを識別します。
有効な値： 1～255文字

文字列

◯

stage

パス

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

◯

access token

ヘッダー

LWAトークン。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

成功すると、HTTP 200 OKメッセージとアカウントリンク情報が返されます。詳細については、アカウントリンクのスキーマを参照してください。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

{
    "type": "AUTH_CODE",
    "authorizationUrl": "http://www.example.com/auth_url",
    "domains": ["www.example.com"],
    "clientId": "your.client.id.1",
    "scopes": [
        "permission.scope.a",
        "permission.scope.b"
    ],
    "accessTokenUrl": "http://www.example.com/accessToken_url",
    "accessTokenScheme": "HTTP_BASIC",
    "defaultTokenExpirationInSeconds": 20,
    "redirectUrls": [
        "http://www.example.com/redirect_url"
    ],
    "authorizationUrlsByPlatform": [{
            "platformType": "iOS",
            "platformAuthorizationUrl": "http://your.ios.url"
        },
        {
            "platformType": "Android",
            "platformAuthorizationUrl": "http://your.android.url"
        }
    ]
}

応答本文のプロパティ

プロパティ 説明 型

type

OAuth 2.0のGrant種別を識別します。詳細については、Grant種別を参照してください。有効な値： AUTH_CODE、IMPLICIT

文字列

authorizationUrl

Alexaアプリがユーザーをリダイレクトする認可サーバーのURL。ユーザーはここでシステムのログイン認証情報を入力します。

文字列

domains

認証画面のURLがデータを取得するその他のドメインのリスト。

文字列の配列

clientId

ユーザーを識別する一意の文字列。

文字列

scopes

スキルが必要とするユーザー権限のリスト。
詳細については、permissionsを参照してください。

文字列の配列

accessTokenUrl

アクセストークンと更新トークンのリクエストを受信できるトークンサーバーのURL。

文字列

accessTokenScheme

クライアントの認証方法。
有効な値： HTTP_BASIC、REQUEST_BODY_CREDENTIALS

文字列

defaultTokenExpirationInSeconds

アクセストークンが無効になるまでの秒数。

整数

redirectUrls

OAuthシステムがリンクプロセスを開始したときにリダイレクトするURLのリスト。ユーザーがシステムにログインすると、認可サーバーはこのURLを呼び出してユーザーをAlexaアプリにリダイレクトします。

文字列の配列

authorizationUrlsByPlatform

アカウントリンクの開始に使用されたURLのリスト（モバイルプラットフォーム別）。

オブジェクトの配列

authorizationUrlsByPlatform[].platformType

ユーザーがアカウントリンクに使用するモバイルプラットフォームのタイプ。
有効な値：iOS、Android

文字列

authorizationUrlsByPlatform[].platformAuthorizationUrl

アプリを開いてユーザーを認証するためのOAuth 2.0認証画面のURL。
有効な値：iOS、Android

文字列

voiceForwardAccountLinking

スキルが音声によるアカウントリンクをサポートするかどうか。
有効な値は ENABLED、DISABLEDです。

文字列

ステータス 説明

200 OK

応答本文にアカウントリンク情報が含まれます。応答ヘッダーには、指定されたスキルに関するアカウントリンク情報の現在のバージョンを識別するETagが含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラーコードとメッセージを含む応答本文の例です。

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

指定されたスキルのアカウントリンク情報を更新します。

アカウントリンク情報を更新するには、accountLinkingClientリソースにPUTリクエストを送信します。

パラメーター 指定場所 説明 型 必須

skillId

パス

スキルを識別します。
有効な値： 1～255文字

文字列

◯

stage

パス

スキルのステージを表します。
有効な値はdevelopment、liveです。

文字列

◯

etag

ヘッダー

アカウントリンク情報の現在のバージョン。現在のバージョンを取得するにはアカウントリンク情報を取得するを使用します。

文字列

◯

access token

ヘッダー

LWAトークン。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
    "accountLinkingRequest": {
        "type": "AUTH_CODE",
        "authorizationUrl": "http://www.example.com/auth_url",
        "domains": ["www.example.com"],
        "clientId": "your.client.id.1",
        "scopes": [
            "scope_a",
            "scope_b"
        ],
        "accessTokenUrl": "http://www.example.com/accessToken_url",
        "accessTokenScheme": "HTTP_BASIC",
        "defaultTokenExpirationInSeconds": 20,
        "redirectUrls": [
            "http://www.example.com/redirect_url"
        ],
        "authorizationUrlsByPlatform": [{
                "platformType": "iOS",
                "platformAuthorizationUrl": "http://your.ios.url"
            },
            {
                "platformType": "Android",
                "platformAuthorizationUrl": "http://your.android.url"
            }
        ],
        "skipOnEnablement": "true",
        "voiceForwardAccountLinking": "ENABLED"
    }
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

accountLinkingRequest

アカウントリンク情報への更新内容を定義します。

オブジェクト

◯

accountLinkingRequest.type

OAuth 2.0のGrant種別を識別します。詳細については、Grant種別を参照してください。スマートホームスキルとビデオスキルの場合、AUTH_CODEに設定する必要があります。
有効な値： AUTH_CODE、IMPLICIT

文字列

✕

accountLinkingRequest.authorizationUrl

Alexaアプリがユーザーをリダイレクトする認可サーバーのURL。ユーザーはここでシステムのログイン認証情報を入力します。

文字列

✕

accountLinkingRequest.domains

認証画面のURLがデータを取得するその他のドメインのリスト。最大15個のドメインを指定できます。

文字列の配列

✕

accountLinkingRequest.clientId

ユーザーを識別する一意の文字列。

文字列

✕

accountLinkingRequest.scopes

スキルが必要とするユーザー権限のリスト。
詳細については、permissionsを参照してください。スマートホームスキルとビデオスキルでは必須です。

文字列の配列

✕

accountLinkingRequest.accessTokenUrl

アクセストークンと更新トークンのリクエストを受信できるトークンサーバーのURL。typeがAUTH_CODEの場合は必須です。

文字列

✕

accountLinkingRequest.accessTokenScheme

クライアントの認証方法。typeがAUTH_CODEの場合は必須です。
有効な値： HTTP_BASIC、REQUEST_BODY_CREDENTIALS

文字列

✕

accountLinkingRequest.defaultTokenExpirationInSeconds

アクセストークンが無効になるまでの秒数。typeがAUTH_CODEの場合は必須です。

整数

✕

accountLinkingRequest.redirectUrls

OAuthシステムがリンクプロセスを開始したときにリダイレクトするURLのリスト。ユーザーがシステムにログインすると、認可サーバーはこのURLを呼び出してユーザーをAlexaアプリにリダイレクトします。

文字列の配列

✕

accountLinkingRequest.authorizationUrlsByPlatform

アカウントリンクの開始に使用されたURLのリスト（モバイルプラットフォーム別）。

オブジェクトの配列

✕

accountLinkingRequest.authorizationUrlsByPlatform[].platformType

ユーザーがアカウントリンクに使用するモバイルプラットフォームのタイプ。
有効な値：iOS、Android

文字列

◯

accountLinkingRequest.authorizationUrlsByPlatform[].platformAuthorizationUrl

アプリを開いてユーザーを認証するためのOAuth 2.0認証画面のURL。
有効な値：iOS、Android

文字列

◯

accountLinkingRequest.skipOnEnablement

ユーザーがスキルを有効にしたときにアカウントリンクを開始するかどうかを指定します。
ユーザーがアカウントリンクフローを開始せずにスキルを有効にできるようにする場合は、trueに設定します。ユーザーがスキルを有効にしたときに通常のアカウントリンクフローが実施されるようにする場合は、falseに設定します。

ブール値

✕

accountLinkingRequest.voiceForwardAccountLinking

スキルが音声によるアカウントリンクをサポートするかどうか。
有効な値は ENABLED、DISABLEDです。デフォルト値： DISABLED

文字列

✕

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にエラーコードと人が読める形式のメッセージが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

ステータス 説明

200 OK

アカウントリンク情報が更新されました。応答ヘッダーには、指定されたスキルに関するアカウントリンク情報の現在のバージョンを識別するETagが含まれます。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。
以下は、エラーコードとメッセージを含む応答本文の例です。

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

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

最終更新日: 2025 年 06 月 10 日