認証情報ロッカーREST APIリファレンス

認証情報ロッカーREST APIリファレンス

スマートホームスキルで認証情報ロッカーREST APIを使用すると、ユーザーのThreadネットワーク認証情報を表示したり、Matterデバイスのセットアップ用に新しいユーザーThreadネットワークを作成したりできます。

これらの認証情報を使用して、ワイヤレスパーソナルエリアネットワーク（PAN）と呼ばれるユーザーのThreadネットワークにMatterデバイスをコミッション（接続）できます。この場合、ユーザーのAmazon EchoがThreadボーダールーターとして機能します。ユーザーは、スマートホームスキルを有効にする際にネットワーク認証情報をAlexaやスキルと共有でき、認証情報を手動で入力する手順を省略できます。Threadの詳細については、Thread Groupのサイトを参照してください。

Wi-Fiネットワークでは、Alexa.Commissionableインターフェースを使用してMatterデバイスをコミッション（接続）できます。

APIエンドポイント

認証情報ロッカーAPIのエンドポイントはhttps://credential-locker-service.amazon.comです。

認証

各APIリクエストでは、認証ヘッダーを使用して、スキルがAlexaイベントゲートウェイへのイベントの送信に使用するアクセストークンを指定する必要があります。詳細については、Alexaイベントゲートウェイにイベントを送信するを参照してください。

認証情報にアクセスするには、スキルの権限スコープを有効にする必要があります。詳細については、Threadネットワーク認証情報への権限の追加を参照してください。

操作

認証情報ロッカーAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

Threadネットワークを作成する

PUT /credentiallocker/v2/threadNetworks

Threadネットワークを取得する

GET /credentiallocker/v2/threadNetworks?extendedPanId={extendedPanId}&networkName={networkName}&maxResults={maxResults}&nextToken={nextToken}

Threadネットワークを作成する

新しいユーザーThreadネットワークを作成します。接続可能なThreadネットワークがスキャンで見つからない場合、このAPIを使用します。

リクエスト

Threadネットワークを作成するには、credentiallocker/v2/threadNetworksリソースに対してPUTリクエストを実行します。

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

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

PUT /credentiallocker/v2/threadNetworks
Host: credential-locker-service.amazon.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

リクエスト本文の例

{
    "threadNetwork": {
        "extendedPanId": "extended.pan.id.1",
        "networkName": "MyThreadNetwork",
        "networkKey": "network.key.1"
    }
}

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

プロパティ 説明 型 必須

threadNetworks

作成するThreadネットワーク。

オブジェクト

◯

threadNetworks.extendedPanId

Threadネットワークの拡張PAN ID。
有効な値： UTF-8でエンコードされた8バイトの16進文字列。

文字列

◯

threadNetworks.networkName

Threadネットワークの人が読める形式の名前。

文字列

◯

threadNetworks.networkKey

ネットワークへのアクセスに使用する16バイトのキー。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

◯

threadNetworks[].pskc

デバイスがThreadネットワークに接続するためのコミッショニングキー。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

✕

threadNetworks[].panId

2バイトのPAN ID。

文字列

✕

threadNetworks[].channelNumber

Threadネットワークが使用する802.15.4の無線チャンネル。
有効な値： 11～26。

整数

✕

threadNetworks[].defaultBorderAgentId

Threadボーダーエージェント（Echoなど）の一意のID。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

✕

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

Threadネットワークが正常に作成されました。

422 Unprocessable Content

Threadネットワークは既に存在します。

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

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

Threadネットワークを取得する

指定したフィルター条件に一致する、ユーザーのThreadネットワークを取得します。

リクエスト

Threadネットワークを取得するには、credentiallocker/v2/threadNetworksリソースに対してGETリクエストを実行します。

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

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

GET /credentiallocker/v2/threadNetworks?extendedPanId={extendedPanId}&networkName={networkName}&maxResults={maxResults}&nextToken={nextToken}
Host: credential-locker-service.amazon.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

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

パラメーター 位置 説明 型 必須

extendedPanId

クエリ

Threadネットワークの拡張PAN ID。DNS-SDなどのサービス検出時に取得します。
有効な値： UTF-8でエンコードされた8バイトの16進文字列。

文字列

◯

networkName

クエリ

Threadネットワークの人が読める形式の名前。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
デフォルト値は 100です。

整数

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。

文字列

✕

access token

ヘッダー

Alexaイベントゲートウェイへのアクセストークン。

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

{
    "threadNetworks": [{
        "extendedPanId": "extended.pan.id.1",
        "networkName": "myThreadNetwork",
        "networkKey": "network.key.1",
        "pskc": "pskc.1",
        "panId": "pan.id",
        "channelNumber": 16,
        "defaultBorderAgentId": "border.agent.id"
    }],
    "nextToken": "someToken.1"
}

応答本文のプロパティ

プロパティ 説明 型

threadNetworks

フィルター条件に一致するThreadネットワークのリスト。

オブジェクトの配列

threadNetworks[].extendedPanId

Threadネットワークの拡張PAN ID。
有効な値： UTF-8でエンコードされた8バイトの16進文字列。

文字列

threadNetworks[].networkName

Threadネットワークの人が読める形式の名前。最大サイズ： 16バイト。

文字列

threadNetworks[].networkKey

ネットワーク内のトラフィックの暗号化/復号に使用される16バイトのキー。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

threadNetworks[].pskc

デバイスがThreadネットワークに接続するためのコミッショニングキー。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

threadNetworks[].panId

（オプション）2バイトのPAN ID。

文字列

threadNetworks[].channelNumber

（オプション）Threadネットワークが使用する802.15.4の無線チャンネル。
有効な値： 11～26。

整数

threadNetworks[].defaultBorderAgentId

（オプション）Threadボーダーエージェント（Echoなど）の一意のID。
有効な値： UTF-8でエンコードされた16バイトの16進文字列。

文字列

nextToken

次に返す結果セットを識別します。トークンの有効期限は24時間です。
この値を次のThreadネットワークを取得するリクエストのnextTokenパラメーターに使用します。
条件に一致する結果がなくなると、nextTokenは応答に含まれなくなります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

応答本文にAlexaが認識するThreadネットワークのリストが含まれています。

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 年 03 月 07 日