ユニット設定API


ユニット設定API

ルームのようなAlexa Smart Properties in Senior Livingのユニットに対するユニット設定を管理するには、ユニットAPIを使用します。

APIエンドポイント

ユニット設定APIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。

操作

ユニット設定APIには、以下の操作があります。

操作 HTTPメソッドとURI

デフォルトの音楽ステーション設定を取得する

GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences

デフォルトの音楽ステーションを設定する

PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences

1つのユニットのすべてのアラームを削除する

DELETE /v1/alerts/alarms?unitId={unitId}

1つのユニットのすべてのリマインダーを削除する

DELETE /v1/alerts/reminders?unitId={unitId}

デフォルトの音楽ステーション設定を取得する

指定ユニットのデフォルトの音楽ステーション詳細設定を取得するには、GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferencesを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality Residential Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ

なし

米国、英国、フランス、カナダ、イタリア、ドイツ

米国

リクエストの形式

GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列

リクエスト本文

なし。

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 必須
X-Amzn-RequestId リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 文字列

応答本文の例

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

応答本文のパラメーター

フィールド 説明 必須
providerId ラジオステーションプロバイダーID。サポートされる値については、プロバイダーIDとステーションIDのリファレンスを参照してください。 文字列
stationId ステーションID。サポートされる値については、プロバイダーIDとステーションIDのリファレンスを参照してください。 文字列

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 必須
type エラータイプ。 文字列
message エラーのエラーメッセージです。注: エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 文字列

HTTP応答コード

ステータスコード 名前 説明
200 OK リクエストが成功しました。
204 No Content 設定は存在していますが、値が含まれていません。
401 Unauthorized アクセストークンがないか、期限切れか、無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests リクエストが制限されています。

デフォルトの音楽ステーションを設定する

指定ユニットのデフォルトの音楽ステーションを設定するには、PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferencesを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality Residential Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ

なし

米国、英国、フランス、カナダ、イタリア、ドイツ

米国

リクエストの形式

PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列

リクエスト本文の例

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

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

フィールド 説明 必須
providerId ラジオステーションプロバイダーID。サポートされる値については、プロバイダーIDとステーションIDのリファレンスを参照してください。 文字列
stationId ステーションID。サポートされる値については、プロバイダーIDとステーションIDのリファレンスを参照してください。 文字列

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 必須
X-Amzn-RequestId リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 文字列

応答本文

なし。

エラー応答

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

エラー応答のパラメーター

フィールド 説明 必須
type エラータイプ。 文字列
message エラーのエラーメッセージです。注: エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。 文字列

HTTP応答コード

ステータスコード 名前 説明
204 No Content 設定は適用されました。
400 Bad Request リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests リクエストが制限されています。

1つのユニットのすべてのアラームを削除する

1つのユニットのすべてのエンドポイント上のすべてのアラームを削除するには、DELETE /v1/alerts/alarms?unitId={unitId}を呼び出します。このAPI呼び出しは、AVSのアラームREST APIの拡張機能です。

この操作は以下の国で使用できます。

Healthcare Hospitality Residential Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ

なし

米国、英国、フランス、カナダ、イタリア、ドイツ

米国

リクエストの形式

DELETE /v1/alerts/alarms?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

リクエスト本文

なし。

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

フィールド 説明 必須

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。

文字列

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 必須

X-Amzn-RequestId

リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答

削除に成功したら、サーバーはHTTP 204 No Contentステータスを返します。成功ペイロードに本文は含まれません。

HTTP/1.1 204 No Content
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json

エラー応答

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "code": "{Code}",
        "endpointId": "{EndpointId}",
        "description": "{ErrorMessage}"
    }]
}

エラー応答のパラメーター

フィールド 説明 必須

code

エラー名(たとえばDEVICE_UNREACHABLE)。

文字列

endpointId

エンドポイントID。"amzn1.alexa.endpoint.{id}"というAmazon Common Identifier(ACI)形式で指定します。

文字列

description

エラーのエラーメッセージです。注: エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

複数のデバイス障害に対するエラー処理

ユニット内の特定のデバイスでエラーが発生した場合、APIはその障害を記録し、残りのデバイスのアラームの削除を続行します。応答では、以下の例のように、各デバイスの障害ごとにエンドポイントIDと理由が返されます。

  • 同じエラー理由で複数の障害が発生した場合は、最も正確なHTTPステータスコード(たとえば、すべてのエラーがデバイスへの到達不能によるものであれば504 DEVICE_NOT_REACHABLE)が返されます。
  • エラー理由が異なる複数の障害が発生した場合は、500 INTERNAL_SERVER_ERRORというステータスコードが返され、各障害のより詳細な情報がエラーの配列に列挙されます。
HTTP/1.1 500 INTERNAL SERVER ERROR
Content-Type: application/json

{
    "errors": [{
            "code": "DEVICE_NOT_REACHABLE",
            "endpointId": "{ENDPOINT_ID_1}",
            "description": "Device not reachable / offline"
        },
        {
            "code": "INTERNAL_SERVER_ERROR",
            "endpointId": "{ENDPOINT_ID_2}",
            "description": "Unexpected Error"
        }
    ]
}

HTTP応答コード

ステータスコード 名前 説明

204

No Content

ユニットのすべてのエンドポイント上でアラームが正常に削除されました。ユニットに削除するアラームがない場合でも、このステータスコードが返されます。

400

BAD_REQUEST

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

401

UNAUTHORIZED

認証トークンが無効か、リソースに対するアクセス権限がありません。

401

FORBIDDEN

操作を実行する権限がユーザーにないか、ユニットが存在しません。

500

INTERNAL_SERVER_ERROR

内部サービスエラーのためリクエストを処理できませんでした。

504

DEVICE_NOT_REACHABLE

デバイスがオフラインか到達不能です。

1つのユニットのすべてのリマインダーを削除する

1つのユニットのすべてのエンドポイント上のすべてのリマインダーを削除するには、DELETE /v1/alerts/reminders?unitId={unitId}を呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality Residential Senior Living Core

米国

米国、カナダ、イタリア、ドイツ

なし

米国、英国、フランス、カナダ、イタリア、ドイツ

米国

リクエストの形式

DELETE /v1/alerts/reminders?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

リクエスト本文

なし。

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

フィールド 説明 必須

unitId

ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。

文字列

応答ヘッダー

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 必須

X-Amzn-RequestId

リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答

削除に成功したら、サーバーはHTTP 204 No Contentステータスを返します。成功ペイロードに本文は含まれません。

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

エラー応答

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "type": "{ErrorType}",
        "endpointId": "{EndpointId}",
        "message": "{ErrorMessage}"
    }]
}

エラー応答のパラメーター

フィールド 説明 必須

type

エラー名(たとえばDEVICE_UNREACHABLE)。

文字列

endpointId

エンドポイントID。"amzn1.alexa.endpoint.{id}"というAmazon Common Identifier(ACI)形式で指定します。

文字列

message

エラーのエラーメッセージです。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

HTTP応答コード

ステータスコード 名前 説明

204

No Content

ユニットのすべてのエンドポイント上でリマインダーが正常に削除されました。ユニットに削除するリマインダーがない場合でも、このステータスコードが返されます。

400

BAD_REQUEST

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

401

UNAUTHORIZED

認証トークンが無効か、リソースに対するアクセス権限がありません。

403

FORBIDDEN

操作を実行する権限がユーザーにないか、ユニットが存在しません。

500

INTERNAL_SERVER_ERROR

内部サービスエラーのためリクエストを処理できませんでした。

504

DEVICE_NOT_REACHABLE

デバイスがオフラインか到達不能です。

プロバイダーIDとステーションIDのリファレンス

以下の表に、サポートされるproviderId値とstationId値を示します。国/地域文字列はISO 3166-1 alpha-2コードです。

国/地域文字列 プロバイダーID ステーションID 説明

米国

I_HEART_RADIO

4802

American Top 40

米国

I_HEART_RADIO

4426

クラシックロック(IHR_CLASSIC_ROCK)

米国

I_HEART_RADIO

4429

ヒップホップ(IHR_HIPHOP)

米国

I_HEART_RADIO

4422

ポップ(IHR_POP)

米国

I_HEART_RADIO

4418

カントリー(IHR_COUNTRY)

米国

I_HEART_RADIO

7193

ラテン(IHR_LATIN)

米国

I_HEART_RADIO

5953

ダンス(IHR_DANCE)

米国

I_HEART_RADIO

5162

ゴスペル(IHR_GOSPEL)

米国

I_HEART_RADIO

4242

ジャズ(IHR_JAZZ)

米国

I_HEART_RADIO

6377

クラシック(IHR_CLASSICAL)

米国

I_HEART_RADIO

4409

ミックス(IHR_MIX)

米国

I_HEART_RADIO

4717

オールディーズ(IHR_OLDIES)

米国

I_HEART_RADIO

4447

オルタナティブ(IHR_ALTERNATIVE)

米国

I_HEART_RADIO

7312

Wynn's Station(IHR_WYNN_MUSIC)


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

最終更新日: 2023 年 03 月 06 日