コミュニケーション機能REST APIリファレンス

コミュニケーション機能REST APIリファレンス

Alexaコミュニケーション機能REST APIを使用すると、Alexa Smart Properties（ASP）のルーム用のコミュニケーション機能プロファイルを作成および管理できます。これらのプロファイルを使用して、施設のルーム間でAlexa搭載デバイスによる通話を行うことができます。通話アドオンの詳細については、Alexa Smart Propertiesで通話するを参照してください。

ルーム内のAlexa搭載デバイスを識別するには、ユニットIDの代わりにコミュニケーション機能プロファイルを使用します。ルーム用のコミュニケーション機能プロファイルを作成したら、それをほかのルームのアドレス帳に連絡先として追加できます。詳細については、アドレス帳REST APIリファレンスを参照してください。

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

http://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

http://api.eu.amazonalexa.com

日本

http://api.fe.amazonalexa.com

認証

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

操作

コミュニケーション機能APIでは、以下の操作タイプがサポートされています。

  • コミュニケーション機能プロファイルの管理 - 通話をサポートするには、ユニットごとにコミュニケーション機能プロファイルを作成する必要があります。
  • 通話設定の管理 - 各ユニットとコミュニケーション機能プロファイルの呼びかけ設定を構成したり、2つの施設ユニット間の通話を無効にするブロックルールを定義したりできます。

コミュニケーション機能プロファイルの管理

操作 HTTPメソッドとURI

コミュニケーション機能プロファイルを作成する

POST /v1/communications/profile

コミュニケーション機能プロファイルを一括で作成する

POST /v1/communications/profiles/batch

コミュニケーション機能プロファイルを削除する

DELETE /v1/communications/profile/{profileId}

コミュニケーション機能プロファイルを取得する

GET /v1/communications/profile/{profileId}

エンティティを使用してコミュニケーション機能プロファイルを取得する

GET /v1/communications/profile?entity.type={type}&entity.id={id}

コミュニケーション機能プロファイルを更新する

PUT /v1/communications/profile/{profileId}

相互関連付けを作成する

POST /v1/communications/profile/{profileId}/reciprocalAssociations

相互関連付けを削除する

DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}

相互関連付けを取得する

GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}&maxResults={maxResults}&nextToken={nextToken}

通話設定の管理

操作 HTTPメソッドとURI

ブロックルールを作成する

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId}

ブロックルール設定を取得する

GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}

呼びかけ設定を取得する

GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}

呼びかけ設定を設定する

PUT /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}

コミュニケーション機能プロファイルを作成する

ユニットでの通話をサポートするコミュニケーション機能プロファイルを作成します。応答には、profileIdと呼ばれるユニットの一意の識別子が含まれます。このprofileIdを、ほかのユニットのアドレス帳に連絡先として追加できます。

必要に応じてプロファイルの名前を指定できます。これはユニットの表示名として使用されます。このユニットのゲストが電話をかけると、指定した名前が連絡先のAlexa搭載デバイスとAlexaアプリに表示されます。ほかのユニットのゲストからこのユニットに着信できるようにするには、ほかのユニットのアドレス帳にこのユニットの名前を追加します。ユニットのプロファイルが既に存在する場合、この操作はユニットの既存のprofileIdを返し、既存の名前とは異なるプロファイル名が指定されていればプロファイル名を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

プロファイルを作成するには、/v1/communications/profileリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/communications/profile HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "101号室"
}

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

プロパティ 説明 型 必須

entity

コミュニケーション機能プロファイルを作成する対象のエンティティ（ユニットなど）。

オブジェクト

◯

entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

◯

entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

name

コミュニケーション機能プロファイルの表示名。
有効な値は、 次のルールを満たす1～50文字のUnicode（UTF-8）文字列です。

  • 使用できる文字は、数字、文字（漢字や非ラテン文字も使用可能）、空白、アポストロフィ、ダッシュ、アンダースコアです。その他の特殊文字は使用できません。
  • 名前には、1文字以上の数字または文字が含まれている必要があります。

文字列

✕

応答

正常に完了すると、HTTP 200 OKと共に、コミュニケーション機能プロファイルIDが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

応答本文のプロパティ

プロパティ 説明 型

entity

コミュニケーション機能プロファイルを作成する対象のエンティティ（ユニットなど）。

オブジェクト

entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

profileId

ユニットの新しいコミュニケーション機能プロファイル。

オブジェクト

profileId.profileId

コミュニケーション機能プロファイルを一意に識別します。
指定されたユニットに既にコミュニケーション機能プロファイルが存在する場合、この値は既存のprofileIdを示します。amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたエンティティのコミュニケーション機能プロファイルIDが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • unitIdが無効です。入力を確認してください。
  • profileIdが無効です。
  • nameが無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

コミュニケーション機能プロファイルを一括で作成する

最大100ユニットのコミュニケーション機能プロファイルを1回のリクエストで作成します。各ユニットに一意のprofileIdが割り当てられます。このprofileIdを、ほかのユニットのアドレス帳に連絡先として追加できます。

必要に応じてプロファイルの名前を指定できます。これはユニットの表示名として使用されます。このユニットのゲストが電話をかけると、指定した名前が連絡先のAlexa搭載デバイスとAlexaアプリに表示されます。ほかのユニットのゲストからこのユニットに着信できるようにするには、ほかのユニットのアドレス帳にこのユニットの名前を追加します。ユニットのプロファイルが既に存在する場合、この操作はユニットの既存のprofileIdを返し、既存の名前とは異なるプロファイル名が指定されていればプロファイル名を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

複数のプロファイルを作成するには、/v1/communications/profiles/batchリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/communications/profiles/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
    "items": [{
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.201"
            },
            "name": "201号室"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.202"
            },
            "name": "202号室"
        }
    ]
}

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

プロパティ 説明 型 必須

items

コミュニケーション機能プロファイルを割り当てるユニットのリスト。

オブジェクトの配列

◯

items[].itemId

割り当ての一意のID。

整数

◯

items[].entity

コミュニケーション機能プロファイルを作成する対象のエンティティ（ユニットなど）。

オブジェクト

◯

items[].entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

◯

items[].entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

items[].name

コミュニケーション機能プロファイルの表示名。
有効な値は、 次のルールを満たす1～50文字のUnicode（UTF-8）文字列です。

  • 使用できる文字は、数字、文字（漢字や非ラテン文字も使用可能）、空白、アポストロフィ、ダッシュ、アンダースコアです。その他の特殊文字は使用できません。
  • 名前には、1文字以上の数字または文字が含まれている必要があります。

文字列

✕

応答

正常に完了すると、HTTP 200 OKと共に、コミュニケーション機能プロファイルIDのリストが返されます。リクエスト全体が失敗した場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。個々の項目でエラーが発生した場合、応答本文には成功とエラーの項目が含まれます。

応答本文の例

以下の例は成功応答を示し、各ユニットにプロファイルIDが割り当てられています。

以下の例は、個々の項目レベルで成功とエラーメッセージの両方を含む応答本文を示しています。resultsプロパティとerrorsプロパティは同じ応答に共存できます。

以下の例は、すべての項目が失敗した応答本文を示しています。

以下の例は、個々の項目ではなくリクエスト全体がエラーになった応答本文を示しています。

応答本文のプロパティ

プロパティ 説明 型

results

成功した結果のリスト。

オブジェクトの配列

results[].itemId

（オプション）リクエストで指定された一意のID。リクエスト項目とレスポンス項目を関連付けるために使用できます。リクエストレベルのエラーの場合は含まれません。

整数

results[].entity

プロファイルの作成対象のエンティティ（ユニットなど）。

オブジェクト

results[].entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

results[].entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].profileId

コミュニケーション機能プロファイルを一意に識別します。
指定されたユニットに既にコミュニケーション機能プロファイルが存在する場合、この値は既存のprofileIdを示します。amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

errors

（オプション）エラーの結果のリスト。
返される可能性のあるエラーのプロパティ値の詳細については、個々の項目に対するエラーのプロパティ値を参照してください。

オブジェクトの配列

errors[].itemId

（オプション）リクエストで指定された一意のID。リクエスト項目とレスポンス項目を関連付けるために使用できます。

整数

errors[].status

失敗したリクエスト項目に対するHTTP応答コード。

整数

errors[].errorCode

発生したエラーのタイプ。

文字列

errors[].errorDescription

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

文字列

個々の項目に対するエラーのプロパティ値

status errorCode errorDescription

400

INVALID_PARAM

UnitId is not valid. Please check your Input.（unitIdが無効です。入力を確認してください。）

400

INVALID_PARAM

Given entityType in request is not supported. Currently the interface supports UNIT entityType.（リクエストに指定されたentityTypeはサポートされていません。現在、このインターフェースでサポートされているentityTypeはUNITです。）

400

INVALID_PARAM

Entity is mandatory.（entityは必須です。）

400

INVALID_PARAM

EntityType must be between 1 and 10 characters.（entityTypeは1～10文字である必要があります。）

400

INVALID_PARAM

EntityId must be between 1 and 1000 characters.（entityIdは1～1000文字である必要があります。）

400

INVALID_PARAM

Name must consist of 1 to 128 characters.（nameは1～128文字である必要があります。）

403

FORBIDDEN

Requested action cannot be performed as you don't have access over the specified resource.（指定されたリソースにアクセスする権限がないため、リクエストされたアクションを実行できません。）

500

INTERNAL_ERROR

An internal service error occurred.（内部サービスエラーが発生しました。）

HTTPステータスコード

ステータス 説明

200 OK

コミュニケーション機能プロファイルIDのリストが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

コミュニケーション機能プロファイルを削除する

指定されたコミュニケーション機能プロファイルを削除します。この操作では、以下のアクションが実行されます。

  • コミュニケーション機能を無効にする。
  • ユニットに割り当てられているprofileIdを削除する。
  • profileIDが連絡先となっているアドレス帳に含まれる連絡先をすべて削除する。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

プロファイルを削除するには、/v1/communications/profileリソースに対してDELETEリクエストを実行します。

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

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

DELETE /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

コミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

コミュニケーション機能プロファイルが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

コミュニケーション機能プロファイルを取得する

指定されたコミュニケーション機能プロファイルの詳細を取得します。これには、プロファイルに関連付けられているユニットIDが含まれます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

プロファイルを取得するには、/v1/communications/profileリソースに対してGETリクエストを実行します。

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

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

GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

コミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、コミュニケーション機能プロファイルが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "101号室",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

応答本文のプロパティ

プロパティ 説明 型

entity

コミュニケーション機能プロファイルを取得する対象のエンティティ（ユニットなど）。

オブジェクト

entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

name

コミュニケーション機能プロファイルの表示名。
有効な値は、 1～50文字のUnicode（UTF-8）文字列です。

文字列

profileId

ユニットのコミュニケーション機能プロファイル。

オブジェクト

profileId.profileId

コミュニケーション機能プロファイルを一意に識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

コミュニケーション機能プロファイルが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

エンティティを使用してコミュニケーション機能プロファイルを取得する

指定されたエンティティに関連付けられているコミュニケーション機能プロファイルを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

プロファイルを取得するには、/v1/communications/profileリソースに対してGETリクエストを実行します。

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

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

GET /v1/communications/profile?entity.type={type}&entity.id={id}&maxResults={maxResults}&nextToken={nextToken}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

type

クエリ

エンティティのタイプ。
有効な値： UNIT。

文字列

◯

id

クエリ

ユニットID。
指定されたユニットに関連付けられているプロファイルで結果をフィルタリングします。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、指定されたユニットのコミュニケーション機能プロファイルIDが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "101号室",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

応答本文のプロパティ

プロパティ 説明 型

entity

コミュニケーション機能プロファイルを取得する対象のエンティティ（ユニットなど）。

オブジェクト

entity.type

エンティティのタイプ。
有効な値： UNIT。

文字列

entity.id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

name

コミュニケーション機能プロファイルの表示名。
有効な値は、 1～50文字のUnicode（UTF-8）文字列です。

文字列

profileId

ユニットのコミュニケーション機能プロファイル。

オブジェクト

profileId.profileId

コミュニケーション機能プロファイルを一意に識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

コミュニケーション機能プロファイルが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • 指定されたエンティティタイプがサポートされていません。
  • unitIdが無効です。入力を確認してください。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

コミュニケーション機能プロファイルを更新する

コミュニケーション機能プロファイルの表示名を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

プロファイルを更新するには、/v1/communications/profile/{profileId}リソースに対してPUTリクエストを実行します。

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

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

PUT /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

コミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
  "name": "14-101号室"
}

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

プロパティ 説明 型 必須

name

コミュニケーション機能プロファイルの表示名。
有効な値は、 次のルールを満たす1～50文字のUnicode（UTF-8）文字列です。

  • 使用できる文字は、数字、文字（漢字や非ラテン文字も使用可能）、空白、アポストロフィ、ダッシュ、アンダースコアです。その他の特殊文字は使用できません。
  • 名前には、1文字以上の数字または文字が含まれている必要があります。

文字列

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

プロファイル名が正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • nameが無効です。
  • nameは必須です。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

相互関連付けを作成する

指定されたユニットと外部連絡先との相互関連付けを作成します。この関連付けにより、外部連絡先から、ユニットに関連付けられているAlexa搭載デバイスへの着信が可能になります。関連付けを作成するには、施設ユニットに関連付けられているアドレス帳に外部連絡先を追加してから、ルームとその連絡先との間に相互関連付けを作成します。

この操作は、連絡先IDで識別される外部ユーザーのアドレス帳に、ユニットのコミュニケーション機能プロファイルを連絡先として追加します。その後、外部連絡先のAlexaアプリとHAQM Echoデバイスに、新しい相互連絡先について通知するAlexaメッセージを送信します。外部連絡先に複数の電話番号がある場合、この操作は、有効な電話番号のそれぞれに対して相互関連付けの作成を試みます。少なくとも1つの電話番号との関連付けが成功すると、操作は成功します。既に相互関連付けが存在する電話番号については、重複する連絡先は作成されず、外部連絡先へのメッセージ送信も行われません。

関連付けの作成後、外部連絡先は、Alexa搭載デバイスやAlexaアプリの連絡先リストでユニットへの連絡先を表示したり、画面付きのAlexa搭載デバイスで音声や画面上のコントロールを使用してユニットに電話をかけたりできます。外部連絡先は、必要に応じてユニットの連絡先をブロックできます。着信機能では、メッセージと呼びかけ通話はサポートされません。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエスト

関連付けを作成するには、/v1/communications/profile/{profileId}/reciprocalAssociationsリソースに対してPOSTリクエストを実行します。

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

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

POST /v1/communications/profile/{profileId}/reciprocalAssociations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

ユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
    "contact": {
        "id": "amzn1.alexa.contact.did.1101"
    }
}

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

プロパティ 説明 型 必須

contact

ユニットに関連付ける外部連絡先を識別します。

オブジェクト

◯

contact.id

外部連絡先を識別します。
profileIdで指定されたユニットに関連付けられているアドレス帳に、この連絡先が存在していることを確認してください。連絡先に複数の電話番号がある場合は、この操作によってすべての番号からの着信が許可されます。amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

応答

正常に完了すると、HTTP 201 Createdと共に、関連付けが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "profileId": "amzn1.alexa.communications.profile.did.1234",
    "contactId": "amzn1.alexa.contact.did.1101"
}

応答本文のプロパティ

プロパティ 説明 型

profileId

パス

コミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

contactId

profileIdに関連付けられた外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

204 No Content

相互関連付けが正常に作成されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • Alexaアプリで連絡先のコミュニケーション機能が有効になっていません。追加できるのはAlexaコミュニケーション機能が有効になっている連絡先だけです。
  • 連絡先が作成されているアドレス帳が、profileIdのエンティティに関連付けられていません。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

相互関連付けのステータスを削除する

外部連絡先からユニットへの着信を無効にするには、ユニットと外部連絡先との相互関連付けを削除します。この操作は、指定された連絡先のアドレス帳から指定されたユニットを削除し、連絡先のAlexaアプリとHAQM EchoデバイスにAlexaメッセージを送信して、関連付けが削除されたことを連絡先に通知します。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエスト

関連付けを削除するには、/v1/communications/profile/{profileId}/reciprocalAssociationsリソースに対してDELETEリクエストを実行します。

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

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

DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

連絡先からの着信を無効にするユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

contactId

クエリ

外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

指定された連絡先の相互関連付けが正常に削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • contactIdが無効です。
  • 連作先が作成されているアドレス帳が、profileIdのエンティティに関連付けられていません。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

相互関連付けを取得する

指定されたプロファイルと連絡先との相互関連付けのステータスを取得します。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエスト

関連付けを取得するには、/v1/communications/profile/{profileId}/reciprocalAssociationsリソースに対してGETリクエストを実行します。

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

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

GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

ユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

contactId

クエリ

profileIdに関連付けられた外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、関連付けのステータスが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "results": [{
        "contact": {
            "contactId": "amzn1.alexa.contact.1101"
        },
        "status": "ENABLED"
    }],
    "paginationContext": {
        "nextToken": "null"
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

連絡先のリスト。

オブジェクトの配列

results[].contact

連絡先を定義します。

オブジェクト

results[].contact.contactId

profileIdに関連付けられた外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].status

指定された連絡先とプロファイルとの相互関連付けが存在するかどうかを示します。
外部連絡先に複数の電話番号があり、その連絡先に登録されている電話番号のいずれかにユニットとの相互関連付けが作成されている場合、ステータスはENABLEDになります。有効な値は、 ENABLED、DISABLEDです。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

関連付けのステータスが応答に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • contactIdが無効です。
  • Alexaアプリで連絡先のコミュニケーション機能が有効になっていません。追加できるのはAlexaコミュニケーション機能が有効になっている連絡先だけです。
  • 連作先が作成されているアドレス帳が、profileIdのエンティティに関連付けられていません。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

ブロックルールを作成する

2つの施設ユニット間の通話とメッセージを有効または無効にするブロックルールを作成します。

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

Healthcare Hospitality Senior Living Core

米国

米国

米国

米国

リクエスト

ブロックルールを作成するには、/v1/communications/profile/{profileId}/contacts/settings/Blockリソースに対してPUTリクエストを実行します。このルールは、ターゲットユニットから、プロファイルIDで識別される指定されたユニットへの通話をブロックします。ただし、指定されたユニットからターゲットユニットへの通話は引き続き可能です。

リクエストヘッダーの例

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

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

呼びかけ設定を更新するユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

alexaCommunicationProfileId

クエリ

profileIdへの呼びかけを有効または無効にするターゲットユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
        "value": "ENABLED"
}

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

パラメーター 説明 型 必須

value

ユニットへの通信を有効にするかブロックするかを示す設定。有効な値は、 ENABLED、DISABLEDです。

文字列

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

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

応答本文のパラメーター

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

HTTPステータスコード

ステータス 説明

204 No content

リクエストが成功しました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • 指定されたprofileIdが無効です。
  • ソース（ブロック元）とターゲット（ブロック先）のコミュニケーション機能プロファイルIDを同じにすることはできません。つまり、profileIdをalexaCommunicationProfileIdと同じにすることはできません。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

ブロックルール設定を取得する

施設ユニット間の着信とメッセージを有効または無効にするブロックルールを取得します。

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

Healthcare Hospitality Senior Living Core

米国

米国

米国

米国

リクエスト

ブロックルールを取得するには、/v1/communications/profile/{profileId}/contacts/settings/Block?value={value}リソースへのGETリクエストを行います。

リクエストヘッダーの例

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

GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}&alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

呼びかけ設定を照会するユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

alexaCommunicationProfileId

クエリ

ターゲットユニットのコミュニケーション機能プロファイルを識別します。指定されていない場合、応答には、profileIdへの通話が許可またはブロックされているすべてのターゲットのリストが返されます。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

✕

value

クエリ

ブロックルール設定のステータスでフィルタリングします。
有効な値は、 ENABLED、DISABLEDです。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～100です。デフォルト値は 10です。

整数

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。このトークンがない場合、応答には結果の先頭ページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

✕

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、各ターゲットプロファイルIDに対するブロックルール設定のリストが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

以下は、成功した応答の本文の例です。

{
    "results": [{
            "setting": "Block",
            "contactId": "amzn1.alexa.contact.did.1101",
            "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2101",
            "value": "DISABLED"
        },
        {
            "setting": "Block",
            "contactId": "amzn1.alexa.contact.did.1102",
            "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2102",
            "value": "ENABLED"
        }
    ],
    "paginationContext": {
        "nextToken": ""
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

連絡先と、関連付けられているブロック設定のリスト。

オブジェクトの配列

results[].setting

設定のタイプ。常にBlockに設定されます。

文字列

results[].contactId

alexaCommunicationProfileIdで識別されるターゲットユニットに関連付けられている外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].alexaCommunicationProfileId

ターゲットユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].value

ブロック設定の現在のステータス。有効な値は、 ENABLED、DISABLEDです。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

連絡先ごとのブロック設定のリストが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • Block設定キーで使用できる値は、ENABLED、DISABLEDです。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

呼びかけ設定を取得する

指定されたプロファイルIDの、各ターゲットユニットに対する呼びかけ設定の現在の状態を取得します。

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

Healthcare Hospitality Senior Living Core

米国

なし

なし

なし

リクエスト

設定を取得するには、/v1/communications/profile/{sourceProfileId}/contacts/settings/DropInリソースに対してGETリクエストを実行します。

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

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

GET /v1/communications/profile/{profileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}  
HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

呼びかけ設定を照会するユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

alexaCommunicationProfileId

クエリ

ターゲットユニットのコミュニケーション機能プロファイルを識別します。指定されていない場合、応答には、profileIdが呼びかけを許可または禁止しているすべてのターゲットのリストが返されます。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

✕

value

クエリ

呼びかけ設定のステータスでフィルタリングします。
有効な値は、 ENABLED、DISABLEDです。

文字列

✕

maxResults

クエリ

応答で返される結果の最大数。
有効な値は 1～100です。デフォルト値は 10です。

整数

✕

nextToken

クエリ

前回の応答で受け取ったトークン。
ページ分割された応答の反復処理を行う場合に含めます。このトークンがない場合、応答には結果の先頭ページが含められます。詳細については、クエリ結果のページ分割を処理するを参照してください。

文字列

✕

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200 OKと共に、各ターゲットプロファイルIDに対する呼びかけ設定のリストが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

{
    "results": [{
        "setting": "DropIn",
        "contactId": "amzn1.alexa.contact.did.1101",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2101",
        "value": "DISABLED"
    }],
    "paginationContext": {
        "nextToken": null
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

連絡先と、関連付けられている呼びかけ設定のリスト。

オブジェクトの配列

results[].setting

設定のタイプ。常にDropInに設定されます。

文字列

results[].contactId

alexaCommunicationProfileIdで識別されるターゲットユニットに関連付けられている外部連絡先を識別します。
amzn1.alexa.contact.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].alexaCommunicationProfileId

ターゲットユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

results[].value

呼びかけ設定の現在のステータス。有効な値は、 ENABLED、DISABLEDです。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は、後続のリクエストで、このリクエストと同じフィルターパラメーターと共に使用します。
結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

連絡先ごとの呼びかけ設定のリストが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • DropIn設定キーで使用できる値は、ENABLED、DISABLEDです。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

呼びかけ設定を設定する

指定された医療施設ユニット間の呼びかけ設定を有効または無効にします。呼びかけ設定を有効にすると、alexaCommunicationProfileIdにリンクされているターゲットユニットから、profileIdにリンクされているユニットへの呼びかけが可能になります。呼びかけでは、インターホンのように連絡先と直接つながることができます。呼びかけを設定するには、ソースユニット（病室など）とターゲットユニット（ナースステーションなど）の両方で、それぞれに関連付けられているアドレス帳に相手のユニットが連絡先として追加されている必要があります。呼びかけは、ターゲットユニットからソースユニットへの一方向です。

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

Healthcare Hospitality Senior Living Core

米国

なし

なし

なし

リクエスト

呼びかけ設定を更新するには、/v1/communications/profile/{sourceProfileId}/contacts/settings/DropInリソースに対してPUTリクエストを実行します。

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

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

PUT /v1/communications/profile/{profileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

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

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

profileId

パス

呼びかけ設定を更新するソースユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

alexaCommunicationProfileId

クエリ

profileIdへの呼びかけを有効または無効にするターゲットユニットのコミュニケーション機能プロファイルを識別します。
amzn1.alexa.communications.profile.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

{
        "value": "ENABLED"
}

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

プロパティ 説明 型 必須

value

呼びかけ設定。有効な値は、 ENABLED、DISABLEDです。

文字列

◯

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

呼びかけ設定が正常に更新されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

次のいずれかの理由により、リクエストが有効ではありません。

  • profileIdが無効です。
  • DropIn設定キーで使用できる値は、ENABLED、DISABLEDです。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

最終更新日: 2024 年 05 月 28 日