コミュニケーション機能API

コミュニケーション機能API

Alexaコミュニケーション機能REST APIを使用すると、コミュニケーション機能プロファイル、アドレス帳、連絡先を作成および管理できます。

APIエンドポイント

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを以下のいずれかに設定してください。

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

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

操作

コミュニケーション機能APIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

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

POST /v1/communications/profile

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

POST /v1/communications/profiles/batch

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

PUT /v1/communications/profile/{profileId}

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

GET /v1/communications/profile/{profileId}

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

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

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

DELETE /v1/communications/profile/{profileId}

アドレス帳を作成する

POST /v1/addressBooks

アドレス帳のリストを取得する

GET /v1/addressBooks

アドレス帳を取得する

GET /v1/addressBooks/{addressBookId}

アドレス帳を更新する

PUT /v1/addressBooks/{addressBookId}

アドレス帳を削除する

DELETE /v1/addressBooks/{addressBookId}

連絡先を作成する

POST /v1/addressBooks/{addressBookId}/contacts

連絡先を一括で作成する

POST /v1/addressBooks/{addressBookId}/contacts/batch

連絡先のリストを取得する

GET /v1/addressBooks/{addressBookId}/contacts

連絡先を取得する

GET /v1/addressBooks/{addressBookId}/contacts/{contactId}

連絡先を更新する

PUT /v1/addressBooks/{addressBookId}/contacts/{contactId}

連絡先を削除する

DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId}

アドレス帳との関連付けを作成する

POST /v1/addressBooks/{addressBookId}/unitAssociations

アドレス帳との関連付けを一括で作成する

POST /v1/addressBooks/{addressBookId}/unitAssociations/batch

ユニットに対するアドレス帳の関連付けのリストを取得する

GET /v1/addressBooks/unitAssociations

アドレス帳との関連付けを取得する

GET /v1/addressBooks/{addressBookId}/unitAssociations

アドレス帳との関連付けを削除する

DELETE /v1/addressBooks/{addressBookId}/unitAssociations

呼びかけ設定を設定する

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

呼びかけ設定を取得する

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

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

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

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

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

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

通話をサポートするには、ユニットがコミュニケーション機能プロファイルを作成する必要があります。コミュニケーション機能プロファイルは自動では作成されません。ユニットのコミュニケーション機能プロファイルを作成すると、profileIdという一意のIDが割り当てられます。このprofileIdを、ほかのユニットのアドレス帳に連絡先として追加できます。

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

POST /v1/communications/profileを呼び出すと、コミュニケーション機能プロファイルを作成できます。コミュニケーション機能プロファイルを作成すると、コミュニケーション機能が有効になり、ユニットのprofileIdが作成されます。プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。オプションで、プロファイルの名前を指定できます。指定された名前は、そのプロファイルが属するユニット（ルームなど）の表示名として表示されます。ユニットのプロファイルが既に存在する場合、APIは201を返し、以前とは異なるプロファイル表示名が適用されていればプロファイル表示名を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

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

なし。

リクエスト本文の形式

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name"
}

リクエスト本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKYQJ4REIHURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Example Name"
}

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

フィールド 説明 型 必須
entity コミュニケーション機能プロファイルの作成対象となるエンティティ。 オブジェクト ◯
entity.type コミュニケーション機能プロファイルの作成に使用しているIDのタイプ。
有効な値： UNIT		 文字列 ◯
entity.id コミュニケーション機能プロファイルの作成に使用しているユニットID。"amzn1.alexa.unit.did.{UnitId}"形式で指定します。 文字列 ◯
name コミュニケーション機能プロファイルの表示名。この名前がユニット（ルームなど）の表示名として外部連絡先のアドレス帳に表示され、そのユニットが着信先となる通話に使用できます。また、ユニット（ルームなど）にいるユーザーが発信する場合には、外部連絡先のAlexa搭載デバイスやAlexaアプリにこの名前が表示されます。

名前の文字列は1～50文字のUnicode（UTF-8）文字とし、以下のルールに従っている必要があります。 1）使用できるのは数字、文字（漢字や非ローマ文字も許容）、空白文字、アポストロフィ、ダッシュ、アンダースコアです。ほかの特殊文字は使用できません。2）名前には数字または文字が少なくとも1文字含まれている必要があります。		 文字列 ✕

応答ヘッダー

HTTP/1.1 201 Created

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

応答本文の形式

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

応答本文の例

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

応答本文のパラメーター

フィールド 説明 型
type コミュニケーション機能プロファイルの作成に使用されるIDのタイプ。
指定できる値： UNIT		 文字列
Id コミュニケーション機能プロファイルの作成に使用されるユニットID。 文字列
profileId コミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されます。コミュニケーション機能プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。 文字列

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "UnitId is not valid.Please check your Input."
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request unitIdが無効です。入力を確認してください。
400 Bad Request profileIdが無効です。
400 Bad Request nameが無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Limit exceeded このリクエストにより、組織が所有できるアドレス帳の数の上限を超過します。ユーザーごとのソフト制限およびソフト設定が制御されます。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

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

POST /v1/communications/profiles/batchを呼び出すと、コミュニケーション機能プロファイルを一括で作成できます。1回のリクエストで最大100ユニットのプロファイルを作成できます（1ユニットあたり1プロファイル）。各ユニットが一意のprofileIdを取得します。このprofileIdを、ほかのユニットのアドレス帳に連絡先として追加できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

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

なし。

リクエスト本文の形式

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId-1}"
            },
            "name": "{optionalProfileDisplayName1}"
        },
        {
            "itemId": {uniqueRequestItemId2},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId-2}"
            },
            "name": "{optionalProfileDisplayName2}"
        }
    ]
}

リクエスト本文の例

{
    "items": [
        {
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
            },
            "name": "Example name 1"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
            },
            "name": "Example name 2"
        }
    ]
}

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

フィールド 説明 型 必須
items 操作の実行対象項目のリスト。 リスト ◯
itemId リクエスト項目の一意のID。一般に、項目のIDは1から始まる連番です。 整数 ◯
type コミュニケーション機能プロファイルの作成に使用しているIDのタイプ。
有効な値： UNIT		 文字列 ◯
id コミュニケーション機能プロファイルの作成に使用しているユニットID。"amzn1.alexa.unit.did.{UnitId}"形式で指定します。 文字列 ◯
name コミュニケーション機能プロファイルのプロファイル表示名。ゲストが発信すると、発信先となるAlexaデバイスやAlexaアプリにこの名前が表示されます。また、同じ施設にある別のユニットのAlexaデバイスで、連絡先がこのユニット用に作成された場合にも表示されます。 文字列 ✕

応答ヘッダー

HTTP/1.1 200 OK

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

個々の項目の応答本文

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

応答本文の形式

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId},
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.{unitId}"
            },
            "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId},
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

応答本文の例

{
    "successfulResults": [
        {
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.FG2A43WS5ED6RF7TG8Y9HJS6D57F687GY"
            },
            "profileId": "amzn1.alexa.communications.profile.did.XDTYU7678IJ3DT4EDFT4WSDFT776REWER"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 500,
            "errorCode": "INTERNAL_ERROR",
            "errorDescription": "Something went wrong."
        }
    ]
}

個々の項目の応答本文のパラメーター

フィールド 説明 型 必須
successfulResults このオブジェクトには、リクエストのitemsについて正常に作成されたコミュニケーション機能プロファイルが含まれています。 オブジェクト ◯
itemId コミュニケーション機能プロファイルの作成に成功または失敗したリクエスト項目の一意のID。 整数 ◯
type コミュニケーション機能プロファイルのIDのタイプ。
有効な値： UNIT		 文字列 ◯
id コミュニケーション機能プロファイルのユニットID。 文字列 ◯
profileId コミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されます。コミュニケーション機能プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。 文字列 ◯
errors このオブジェクトには、リクエストのitemsについて失敗したコミュニケーション機能プロファイル作成の情報が含まれています。 オブジェクト ◯
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

個々の項目のHTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "UnitId is not valid.Please check your Input."
400 INVALID_PARAM "Given entityType in request is not supported.Currently we only support UNIT entityType."
400 INVALID_PARAM "Entity is mandatory."
400 INVALID_PARAM "EntityType must be between 1 and 10 characters."
400 INVALID_PARAM "EntityId must be between 1 and 1000 characters."
400 INVALID_PARAM "Name must consist of 1 to 128 characters."
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ステータスコードが401、429、503の場合）

{
    "message": "{ErrorMessage}"
}

エラー応答本文の例（HTTPステータスコードが401、429、503の場合）

{
    "message": "Invalid access token"
}

リクエスト全体の失敗を示す応答本文のパラメーター（エラーコードが401、429、503の場合）

フィールド 説明 型 必須
message HTTPステータスコードが401、429、503の場合のエラーメッセージ。 文字列 ◯

エラー応答本文の形式（HTTPステータスコードがその他の4xx、5xxの場合）

{
    "errors": [
        {
            "itemId": {uniqueRequestItemId}, // エラーがリクエストレベルの場合、これはオプション        
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdあり）

{
    "errors": [
        {
            "itemId": 0,
            "status": 400,
            "errorCode": "",
            "errorDescription": "Given entityType in request is not supported.Currently we only support UNIT entityType."
        },
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "",
            "errorDescription": "UnitId is not valid.Please check your Input"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdなし）

{
    "errors": [
        {
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Request item list size must be between 1 to 100"
        }
    ]
}

リクエスト全体の失敗を示す応答本文のパラメーター（HTTPステータスコードがその他の4xx、5xxの場合）

フィールド 説明 型 必須
errors このオブジェクトには、リクエストのitemsについて失敗したコミュニケーション機能プロファイル作成の情報が含まれています。 オブジェクト ◯
itemId プロファイルの作成に失敗したリクエスト項目の一意のID。 整数 ✕
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

リクエスト全体の失敗を示すHTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "ItemId should be unique for each request item.Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout.Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

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

PUT /v1/communications/profile/{profileId}を呼び出すと、コミュニケーション機能プロファイルの表示名を更新できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

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

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

フィールド 説明 型 必須
profileId 更新対象のコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの作成時に生成されます。 文字列 ◯

リクエスト本文の形式

{
    "name": "<profile display name>"
 }

リクエスト本文の例

{
    "name": "Example Name"
 }

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

フィールド 説明 型 必須
name コミュニケーション機能プロファイルの表示名。相互連絡先の場合、この名前がユニット（ルームなど）の表示名として外部連絡先のアドレス帳に表示され、そのユニットが着信先となる通話に使用できます。また、ユニット（ルームなど）にいるユーザーが発信する場合には、外部連絡先のAlexa搭載デバイスやAlexaアプリにこの名前が表示されます。

名前の文字列は1～50文字のUnicode（UTF-8）文字とし、以下のルールに従っている必要があります。 1）使用できるのは数字、文字（漢字や非ローマ文字も許容）、空白文字、アポストロフィ、ダッシュ、アンダースコアです。ほかの特殊文字は使用できません。2）名前には数字または文字が少なくとも1文字含まれている必要があります。		 文字列 ✕

応答ヘッダー

HTTP/1.1 204 No Content

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

応答本文の形式

なし。

応答本文の例

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "profileId is not valid.Please check your Input."
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
400 Bad Request nameが無効です。
400 Bad Request nameは必須です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

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

GET /v1/communications/profile/{profileId}を呼び出すと、コミュニケーション機能プロファイルに関連付けられているユニットIDを取得できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

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

フィールド 説明 型 必須
profileId 取得対象のコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文の形式

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

応答本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Example Name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

応答本文のパラメーター

フィールド 説明 型
entity.type コミュニケーション機能プロファイルの作成に使用されるIDのタイプ。
有効な値： UNIT		 文字列
entity.Id コミュニケーション機能プロファイルの作成に使用されるユニットID。 文字列
name コミュニケーション機能プロファイルの表示名。 文字列
profileId.profileId コミュニケーション機能プロファイルの一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。コミュニケーション機能プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。 文字列

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "ProfileId is not valid.Please check your Input"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

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

GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.id}を呼び出すと、コミュニケーション機能プロファイルに関連付けられているユニットIDを取得できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

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

フィールド 説明 型 必須
entity.type 取得対象のコミュニケーション機能プロファイルのIDのタイプ。
有効な値： UNIT		 文字列 ◯
entity.id 取得対象のコミュニケーション機能プロファイルのユニットID。"amzn1.alexa.unit.did.{UnitId}"形式で指定します。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文の形式

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "name": "profile display name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.{profileId}"
    }
}

応答本文の例

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.AFOVR3XKY2EZPRXZ7HURGMCRN7CQKHO45MBSNTYYB2YHD3L7I2C32SI2OLKYZJUQL"
    },
    "name": "Example Name",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.AFVGO3S7IQ33Z35E6372SFS7EKFGOFIWIOOFNII7DJQIG"
    }
}

応答本文のパラメーター

フィールド 説明 型
entity.type コミュニケーション機能プロファイルの作成に使用されるIDのタイプ。
有効な値： UNIT		 文字列
entity.id コミュニケーション機能プロファイルの作成に使用されるユニットID。 文字列
name コミュニケーション機能プロファイルの表示名。 文字列
profileId.profileId コミュニケーション機能プロファイルの一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。コミュニケーション機能プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。 文字列

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profile does not exist for the given entity"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request 指定されたエンティティタイプはサポートされていません。
有効な値： UNIT。
400 Bad Request unitIdが無効です。入力を確認してください。
400 Bad Request profileIdが無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

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

DELETE /v1/communications/profile/{profileId}を呼び出すと、コミュニケーション機能プロファイルを削除できます。この呼び出しにより、以下のアクションが実行されます。

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

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

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

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

フィールド 説明 型 必須
profileId 削除対象のコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 204 No Content

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

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profile does not exist"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found コミュニケーション機能プロファイルが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳を管理する

アドレス帳を作成する

POST /v1/addressBooksを呼び出すと、アドレス帳を作成できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

POST /v1/addressBooks HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

なし。

リクエスト本文の形式

{
    "name": "{addressbookName}"
}

リクエスト本文の例

{
    "name": "Example Property Name"
}

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

フィールド 説明 型 必須
name アドレス帳の名前。文字数は1～50文字である必要があります。 文字列 ◯

応答ヘッダー

HTTP/1.1 201 Created

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

応答本文の形式

{
    "addressBookId": "amzn1.alexa.addressbook.did.{id}"
}

応答本文の例

{
    "addressBookId": "amzn1.alexa.addressbook.did.AFFIZRSWWLHI24RAVPYBTH435G63MEAVPYGFCCP3MR4DEGEE35CEX6I2KVU2PWNJG6FEZARP3B5NRWFJDJPTHAMAV35XSNW24NHRYNXEL4VY3P5ROWZGH7P2RE654AOX4E"
}

応答本文のパラメーター

フィールド 説明 型 必須
addressBookId 新しいアドレス帳のアドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Name must be between 1 and 50 characters"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Limit exceeded このリクエストにより、組織が所有できるアドレス帳の数の上限を超過します。ユーザーごとのソフト制限およびソフト設定が制御されます。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳のリストを取得する

GET /v1/addressBooksを呼び出すと、アドレス帳のリストを取得できます。オプションのmaxResultsとnextTokenの値を使用すると、結果のページ分割を指定できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
maxResults 1回の呼び出しで取得する結果の最大数。値は1～1000の間で指定します。デフォルト値は100です。 整数 ✕
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

リクエスト本文

なし。

応答ヘッダー

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

成功応答本文の形式

{
    "results": [
        {
            "addressBookId": "amzn1.alexa.addressbook.did.{id}",
            "name": "{addressBookName}"
        },
    ],
    "paginationContext": {
     "nextToken": "{nextToken}"
    }
}

成功応答本文の例

{
    "results": [
        {
            "addressBookId": "amzn1.alexa.addressbook.did.AEIDIDYHLJGARHFICBJKJFPOQF67CUTIU6QZA7DYPV5JEMPOQY4XVY323UUT7GWCXMAMRODWU55GLVRKWS4UTUJLFGVDCZ2DBVPOFUUCCHKW2J4557K56VLMJPVBNECJBE",
            "name": "Example Name"
        }

    ],
    "paginationContext": {
     "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAF-ACXJUajwy_DQYFKIIKNHt9CS5EUCimxqdvXoJOiEoGUJ1oxvFCfj1lAy8bJ47fK85FjBF0j5Z95HyaxgqDPXsxHkHx7kuZ0ybI7r7N716qI0IxFM_XOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

応答本文のパラメーター

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
name アドレス帳の名前。 文字列 ◯

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Received invalid pagination token.Please check the pagination value passed"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳を取得する

GET /v1/addressBooks/{addressBookId}を呼び出すと、アドレス帳のメタデータを取得できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

成功応答本文の形式

{
    "addressBookId": "amzn1.alexa.addressbook.did.{id}",
    "name": "{addressbookName}"
}

成功応答本文の例

{
    "addressBookId": "amzn1.alexa.addressbook.did.AEWEYSYTUWWISWGD32TNVUP67Z2KEI3XGOTDTEYHWKFL2QB55D7IV2O3CAYIGO4PEEL3UUFOBPMHK6FWWZMBJUT4EY4WLJHY63HA7GATUOC3K7CH4EK3QHXEXOKGDGEJBQ",
    "name": "Example Property Name"
}

応答本文のパラメーター

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
name アドレス帳の名前。 文字列 ◯

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "AddressBookId does not exist"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳を更新する

PUT /v1/addressBooks/{addressBookId}を呼び出すと、アドレス帳名を更新できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

PUT /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の形式

{
    "name": "{addressbookName}"
}

リクエスト本文の例

{
    "name": "Example Name"
}

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

フィールド 説明 型 必須
name 新しいアドレス帳の名前。文字数は1～50文字である必要があります。 文字列 ◯

応答ヘッダー

HTTP/1.1 200 OK

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

成功応答本文

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Address book name is mandatory"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳を削除する

DELETE /v1/addressBooks/{addressBookId}を呼び出すと、アドレス帳を削除できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

DELETE /v1/addressBooks/{addressBookId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 204 No Content

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

成功応答本文

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Address book ID must be between 10 and 1000 characters"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDが見つかりませんでした。
409 Conflict アドレス帳を削除できません。ユニットに関連付けられています。ユーザーは関連付けを先に削除してからアドレス帳を削除する必要があります。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

連絡先を管理する

連絡先を作成する

POST /v1/addressBooks/{addressBookId}/contactsを呼び出すと、アドレス帳に連絡先を追加できます。連絡先には、通話可能なAlexaデバイスまたはPSTN番号を表すアドレス帳エントリを使用できます。また、WebRTCエンドポイントを使用することもできます。連絡先は、電話番号、コミュニケーション機能プロファイル、プロバイダーの連絡先ID（WebRTC実装の場合）を使用して作成できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

POST /v1/addressBooks/{addressBookId}/contacts HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の形式（単一の電話番号を使用）

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    }
}

リクエスト本文の例（単一の電話番号を使用）

{
    "contact": {
        "name": "Example Contact Name",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    }
}

リクエスト本文の例（複数の電話番号を使用）

{
    "contact": {
        "name": "Example Contact Name",
        "phoneNumbers": [
            {
                "number": "+12055551233"
            },
            {
                "number": "+12055551244"
            }
        ]
    }
}

リクエスト本文の形式（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    }
}

リクエスト本文の例（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "Example Contact Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

リクエスト本文の形式（プロバイダーの連絡先IDを使用）

スキルベースのWebRTC通話をサポートする場合は、プロバイダーの連絡先IDを使用して連絡先を作成できます。


{
    "contact": {
        "name": "{contactName}",
        "providerContact": 
            {
                "id": "{providerID}"
            }
    }
}

リクエスト本文の例（プロバイダーの連絡先IDを使用）


{
    "contact": {
        "name": "Example Contact Name",
        "providerContact": 
            {
                "id": "123f4567-f89b-14e3-a456-426614174322"
            }
    }
}

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

フィールド 説明 型 必須
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
number 連絡先の電話番号。E.164形式の米国、英国、カナダ（CA）の電話番号である必要があります。1つの連絡先に電話番号を3つまで指定できます。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。注： フランス（fr-FR）では、電話番号はサポートされません。 文字列 ◯
alexaCommunicationProfileId コミュニケーション機能プロファイルのID。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。この値は、コミュニケーション機能プロファイルを管理するセクションで挙げられているprofileIdと同じです。 文字列 ◯
providerContact.id 作成および所有する一意のネットワークアドレスID。 文字列 ◯

応答ヘッダー

HTTP/1.1 201 Created

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

応答本文の形式

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

応答本文の例

{
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request 連絡先にはnumberオブジェクトが少なくとも1つ、またはalexaCommunicationProfileIdが必要です。
400 Bad Request 連絡先にnumberとalexaCommunicationProfileIdの両方を含めることはできません。
400 Bad Request alexaCommunicationProfileIdの文字数は40～200文字である必要があります。
400 Bad Request profileIdが無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Limit exceeded このリクエストにより、ユニットあたりの連絡先の数の上限を超過します。ユーザーごとのソフト制限およびソフト設定が制御されます。
403 Forbidden 操作を実行する権限がユーザーにありません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

連絡先を一括で作成する

POST /v1/addressBooks/{addressBookId}/contacts/batchを呼び出すと、アドレス帳の連絡先を一括で作成できます。単一のリクエストで最大100件の連絡先を作成できます。連絡先は、通話可能なAlexaデバイスまたはPSTN番号を表すアドレス帳エントリです。連絡先の作成には、電話番号とコミュニケーション機能プロファイルのどちらかを使用できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

POST /v1/addressBooks/{addressBookId}/contacts/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

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

なし。

リクエスト本文の形式（電話番号とコミュニケーション機能プロファイルを両方使用）

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
            "contact": {
                "name": "{contactName}",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": {uniqueRequestItemId2},
            "contact": {
              "name": "{contactName}",
              "alexaCommunicationProfileId": "{communicationProfile}"
            }
        }
    ]
}

リクエスト本文の例（電話番号とコミュニケーション機能プロファイルを両方使用）

{
    "items": [
        {
            "itemId": 1,
            "contact": {
                "name": "Example Name 1",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
              "name": "Example Name 1",
              "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.XER5678IJHYTREW45678I9OLKI876REDS"
            }
        }
    ]
}

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

フィールド 説明 型 必須
items 操作の実行対象項目のリスト。 リスト ◯
itemId リクエスト項目の一意のID。一般に、項目のIDは1から始まる連番です。 整数 ◯
number 連絡先の電話番号。E.164形式である必要があります。電話番号は3つまで追加できます。注： 同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。 文字列 ◯
alexaCommunicationProfileId コミュニケーション機能プロファイルのID。注： 同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。この値は、コミュニケーション機能プロファイルを管理するセクションで挙げられているprofileIdと同じです。 文字列 ◯
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯

応答ヘッダー

HTTP/1.1 200 OK

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

個々の項目の応答本文

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

応答本文の形式

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId1},
            "contactId": "amzn1.alexa.contact.did.{contactId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId2},
            "status": {StatusCode},
            "errorCode": {ErrorCode},
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

応答本文の例

{
    "successfulResults": [
        {
            "itemId": 1,
            "contactId": "amzn1.alexa.contact.did.XDFTYHUJKKMIUT56E45DER5678IJJRF"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 500,
            "errorCode": "INTERNAL_ERROR",
            "errorDescription": "Something went wrong."
        }
    ]
}

個々の項目の応答本文のパラメーター

フィールド 説明 型 必須
successfulResults このオブジェクトには、リクエストのitemsについて正常に作成された連絡先が含まれています。 オブジェクト ◯
itemId 連絡先の作成に成功したリクエスト項目の一意のID。 整数 ◯
contactId 連絡先を指定する一意の連絡先ID。連絡先の初回作成時に生成されます。 文字列 ◯
errors このオブジェクトには、リクエストのitemsについて失敗した連絡先作成の情報が含まれています。 オブジェクト ◯
itemId 連絡先の作成に失敗したリクエスト項目の一意のID。 整数 ◯
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

個々の項目のHTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "Contact must have atleast one PhoneNumber or a CommunicationProfileId"
400 INVALID_PARAM "A Contact cannot contain both PhoneNumber and a CommunicationProfileId.You must add either one."
400 INVALID_PARAM "AlexaCommunicationProfileId 'amzn1.AESAS5HB7E4RMTCQHMOHA2' is not in standard format"
400 INVALID_PARAM "Given phone number is not per E.164 format"
400 INVALID_PARAM "Contact is mandatory"
400 INVALID_PARAM "Contact Name must be between 1 and 50 characters"
400 INVALID_PARAM "Number of phonenumbers has to be between 1 and 3"
400 INVALID_PARAM "Contact Name must be between 1 and 50 characters"
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ステータスコードが401、429、503の場合）

{
    "message": "{ErrorMessage}"
}

エラー応答本文の例（HTTPステータスコードが401、429、503の場合）

{
    "message": "Invalid access token"
}

リクエスト全体の失敗を示す応答本文のパラメーター

フィールド 説明 型 必須
message HTTPステータスコードが401、429、503の場合のエラーメッセージ。 文字列 ◯

エラー応答本文の形式（HTTPステータスコードがその他の4xx、5xxの場合）

{
    "errors": [
        {
            "itemId": {uniqueRequestItemId}, // エラーがリクエストレベルの場合、これはオプション        
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdあり）

{
    "errors": [
        {
            "itemId": 1,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "AlexaCommunicationProfileId 'xyz' is not in standard format"
        },
        {
            "itemId": 2,
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "Given phone number is not per E.164 format"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdなし）

{
    "errors": [
        {
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "ItemId is mandatory for all request items"
        }
    ]
}

応答本文のパラメーター（HTTPステータスコードがその他の4xx、5xxの場合）

フィールド 説明 型 必須
errors このオブジェクトには、リクエストのitemsについて失敗した連絡先作成の情報が含まれています。 オブジェクト ◯
itemId 連絡先の作成に成功または失敗したリクエスト項目の一意のID。 整数 ✕
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

HTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "ItemId should be unique for each request item.Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout.Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

連絡先のリストを取得する

GET /v1/addressBooks/{addressBookId}/contactsを呼び出すと、指定されたアドレス帳の連絡先を取得できます。オプションのmaxResultsとnextTokenの値を使用すると、結果のページ分割を指定できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks/{addressBookId}/contacts?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

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

フィールド 説明 型 必須
maxResults 1回の呼び出しで取得する結果の最大数。値は1～1000の間で指定します。デフォルト値は100です。 整数 ✕
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

リクエスト本文

なし。

応答ヘッダー

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

応答本文の形式

{
    "results": [
        {
            "contactName": "{contactName}",
            "contactId": "amzn1.alexa.contacts.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

応答本文の例

{
    "results": [
        {
            "contactName": "Example Contact Name 1",
            "contactId": "amzn1.alexa.contact.did.AGNA6I63RJBIV7EFEL73AJEIUZ7XGKDCB7VYRO6JTLMHX72F2P4YX4ZVZNCWB3SZR5ZS5ETPJTCCHCTV2NV2XU66GCKSNGF54PZCBCUE"
        },
        {
            "contactName": "Example Contact Name 2",
            "contactId": "amzn1.alexa.contact.did.AEWC6RQGHIKFWT6UMMWWLHCS5Y6HBJACWEF35Y2FB7FO2QACH6MV7VEFE3CKLJZDFENFKAEQKFW6C4SCWO6ERFZ4KGGCXTKC2HXUYQMC"
        }
    ],
    "paginationContext": {
        "nextToken": "AAEAAcpUKRGBVjzoVWM6lljL35vnWNJEqQmscd4Zm6oRLWl8AAAAAF-D0_sNXPigGsCK9AvcWkfVahZ0RTA0tTLrTBFRL81qFM2lGK0ZZ8erl47sqVEMPBRxIvSjNaQrmBIS8UjNvHDck-fQJHFkm-r27-0lylTI_oMPC1h4MIo6bAEeGZqWbq0JxmMUdRvTpRgoImeEW5GUccVq-2Zf21YFOaHIkvXmBkaFdBDP2T1i5WD5OxiAwd1PEBTRZ"
    }
}

応答本文のパラメーター

フィールド 説明 型 必須
contactId 連絡先ID。"amzn1.alexa.contacts.did.{id}"形式で指定します。 文字列 ◯
contactName 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

連絡先を取得する

GET /v1/addressBooks/{addressBookId}/contacts/{contactId}を呼び出すと、連絡先のメタデータを取得できます。

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

Healthcare Hospitality Senior Living Core

米国

サポートされている電話番号： 米国、英国、カナダ、日本

サポートされていない電話番号： フランス、イタリア、ドイツ、スペイン

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
contactId 連絡先ID。"amzn1.alexa.contacts.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文の形式（電話番号を使用）

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    },
    "contactId": "amzn1.alexa.contacts.did.{contactIdid}"
}

応答本文の例（電話番号を使用）

{
    "contact": {
        "name": "Example Contact Name",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

応答本文の形式（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    },
    "contactId": "amzn1.alexa.contact.did.{contactId}"
}

応答本文の例（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "Example Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

応答本文のパラメーター

フィールド 説明 型 必須
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
number 連絡先の電話番号。E.164形式である必要があります。電話番号は3つまで追加できます。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。注： フランス（fr-FR）のアカウントのリクエストでは、phoneNumbersオブジェクトは返されません。 文字列 ◯
alexaCommunicationProfileId コミュニケーション機能プロファイルのID。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。この値は、コミュニケーション機能プロファイルを管理するセクションで挙げられているprofileIdと同じです。 文字列 ◯
contactId 連絡先ID。"amzn1.alexa.contacts.did.{id}"形式で指定します。 文字列 ◯

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたは連絡先IDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

連絡先を更新する

PUT /v1/addressBooks/{addressBookId}/contacts/{contactId}を呼び出すと、連絡先のメタデータを更新できます。

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

Healthcare Hospitality Senior Living Core

米国

サポートされている電話番号： 米国、英国、カナダ、日本

サポートされていない電話番号： フランス、イタリア、ドイツ、スペイン

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

PUT /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
contactId 連絡先ID。"amzn1.alexa.contacts.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の形式（電話番号を使用）

{
    "contact": {
        "name": "{contactName}",
        "phoneNumbers": [
            {
                "number": "{phoneNumber}"
            }
        ]
    }
}

リクエスト本文の例（電話番号を使用）

{
    "contact": {
        "name": "Example Contact Name",
        "phoneNumbers": [
            {
                "number": "+16055554412"
            }
        ]
    }
}

リクエスト本文の形式（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "{contactName}",
        "alexaCommunicationProfileId": "{communicationProfile}"
    }
}

リクエスト本文の例（コミュニケーション機能プロファイルを使用）

{
    "contact": {
        "name": "Example Contact Name",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

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

フィールド 説明 型 必須
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
number 連絡先の電話番号。E.164形式の米国、英国、カナダ（CA）の電話番号である必要があります。1つの連絡先に電話番号を3つまで指定できます。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。注： フランス（fr-FR）では、電話番号はサポートされません。 文字列 ◯
alexaCommunicationProfileId コミュニケーション機能プロファイルのID。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。この値は、コミュニケーション機能プロファイルを管理するセクションで挙げられているprofileIdと同じです。 文字列 ◯

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文

なし。

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたは連絡先IDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

連絡先を削除する

DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId}を呼び出すと、アドレス帳から連絡先を削除できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

DELETE /v1/addressBooks/{addressBookId}/contacts/{contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
contactId 連絡先ID。"amzn1.alexa.contacts.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 204 No Content

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

成功応答本文

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Contact ID is not valid.Please check your input"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたは連絡先IDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳との関連付けを管理する

アドレス帳との関連付けを作成する

POST /v1/addressBooks/{addressBookId}/unitAssociationsを呼び出すと、アドレス帳にユニットを関連付けることができます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

POST /v1/addressBooks/{addressBookId}/unitAssociations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の形式

{
    "unitId": "amzn1.alexa.unit.did.{id}"
}

リクエスト本文の例

{
    "unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU"
}

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

フィールド 説明 型 必須
unitId アドレス帳と関連付けるユニットのID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯

応答ヘッダー

HTTP/1.1 201 Created

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

応答本文の形式

{
    "unitId": "amzn1.alexa.unit.did.{id}",
    "addressBookId": "amzn1.alexa.addressbook.did.{id}"
}

応答本文の例

{
    "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
    "addressBookId": "amzn1.alexa.addressbook.did.AFWNDND4TUBMMIU4P7HHXI2TY27FGYRODJVSYQUENRKSI4FTWTSJB3UUGI5WSH2LMQOYPSDDIJUG6NN336JKARWGXM2POYAB3LVOLVZ5XBO2WZX32SU5D54NF3RSEDGIPU"
}

応答本文のパラメーター

フィールド 説明 型 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯
addressBookId 新しいアドレス帳のアドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "You have reached maximum allowed limit of AddressBooks that can be associated per Unit: 3"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Limit exceeded このリクエストにより、1つのアドレス帳に関連付けることができるユニットの数または1つのユニットに関連付けることができるアドレス帳の数の上限を超過します。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたはユニットIDが見つかりませんでした。
409 Conflict このアドレスはこのユニットと既に関連付けられています。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳との関連付けを一括で作成する

POST /v1/addressBooks/{addressBookId}/unitAssociations/batchを呼び出すと、アドレス帳に最大100ユニットを関連付けることができます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

POST /v1/addressBooks/{addressBookId}/unitAssociations/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

リクエスト本文の形式

{
    "items": [
        {
            "itemId": {uniqueRequestItemId1},
             "unitId": "amzn1.alexa.unit.did.{unitId-1}"
        },
        {
            "itemId": {uniqueRequestItemId2},
             "unitId": "amzn1.alexa.unit.did.{unitId-2}"
        }
    ]
}

リクエスト本文の例

{
    "items": [
        {
            "itemId": 1,
             "unitId": "amzn1.alexa.unit.did.XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ "

        },
        {
            "itemId": 2,
             "unitId": "amzn1.alexa.unit.did.DRR56T7UIOLKI76TREDFTY998TYGDFGT4DFR "
        }
    ]
}

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

フィールド 説明 型 必須
items 操作の実行対象項目のリスト。 リスト ◯
itemId リクエスト項目の一意のID。一般に、項目のIDは1から始まる連番です。 整数 ◯
unitId アドレス帳との関連付けの作成に使用しているユニットID。"amzn1.alexa.unit.did.{UnitId}"形式で指定します。 文字列 ◯

応答ヘッダー

HTTP/1.1 200 OK

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

個々の項目の応答本文

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

応答本文の形式

{
    "successfulResults": [
        {
            "itemId": {uniqueRequestItemId1},
             "unitId": "amzn1.alexa.unit.did.{unitId-1}",
             "addressBookId": "amzn1.alexa.addressbook.did.{addressBookId}"
        }
    ],
    "errors": [
        {
            "itemId": {uniqueRequestItemId2}
            "status": {StatusCode},
            "errorCode": {ErrorCode},
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

応答本文の例

{
    "successfulResults": [
        {
            "itemId": 1,
             "unitId": "amzn1.alexa.unit.did.XDRDRFGYHU8Y67U96T7DFTYUIUYTDR67UJ",
             "addressBookId": "amzn1.alexa.addressbook.did.DRFDCFRT6789876TR56789OLIUYTFY7654EDDF"
        }
    ],
    "errors": [
        {
            "itemId": 2,
            "status": 409,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "AddressBook is already associated with the Unit"
        }
    ]
}

個々の項目の応答本文のパラメーター

フィールド 説明 型 必須
successfulResults このオブジェクトには、リクエストのitemsについて正常に作成された、アドレス帳との関連付けが含まれています。 オブジェクト ◯
itemId アドレス帳との関連付けの作成に成功または失敗したリクエスト項目の一意のID。 整数 ◯
unitId アドレス帳との関連付けのユニットID。 文字列 ◯
addressBookId アドレス帳との関連付けを指定する一意のID。アドレス帳との関連付けの初回作成時に生成されます。 文字列 ◯
errors このオブジェクトには、リクエストのitemsについて失敗した、アドレス帳との関連付けの情報が含まれています。 オブジェクト ◯
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

個々の項目のHTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "UnitId is not valid.Please check your Input."
400 INVALID_PARAM "UnitId is mandatory."
403 FORBIDDEN "Requested action cannot be performed as you don't have access over the specified resource."
404 INVALID_PARAM "UnitId doesn't exist."
409 INVALID_PARAM "AddressBook is already associated with the Unit"
500 INTERNAL_ERROR "An internal service error occurred."

リクエスト全体の失敗を示すエラー応答本文

以下の例に示されているのは、リクエスト全体のエラー応答本文であって、個々の項目のエラー応答本文ではありません。

エラー応答本文の形式（HTTPステータスコードが401、429、503の場合）

{
    "message": "{ErrorMessage}"
}

エラー応答本文の例（HTTPステータスコードが401、429、503の場合）

{
    "message": "Invalid access token"
}

リクエスト全体の失敗を示す応答本文のパラメーター（エラーコードが401、429、503の場合）

フィールド 説明 型 必須
message HTTPステータスコードが401、429、503の場合のエラーメッセージ。 文字列 ◯

エラー応答本文の形式（HTTPステータスコードがその他の4xx、5xxの場合）

{
    "errors": [
        {
            "itemId": {uniqueRequestItemId}, // エラーがリクエストレベルの場合、これはオプション        
            "status": {StatusCode},
            "errorCode": "{ErrorCode}",
            "errorDescription": "{ErrorMessage}"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdあり）

{
    "errors": [
        {
            "itemId": 2,
            "status": 403,
            "errorCode": "FORBIDDEN",
            "errorDescription": "Requested action cannot be performed as you don't have access over the specified resource"
        }
    ]
}

エラー応答本文の例（HTTPステータスコードがその他の4xx、5xxの場合。itemIdなし）

{
    "errors": [
        {
            "status": 400,
            "errorCode": "INVALID_PARAM",
            "errorDescription": "ItemId is mandatory for all request items"
        }
    ]
}

リクエスト全体の失敗を示す応答本文のパラメーター（HTTPステータスコードがその他の4xx、5xxの場合）

フィールド 説明 型 必須
errors このオブジェクトには、リクエストのitemsについて失敗した、アドレス帳との関連付けの情報が含まれています。 オブジェクト ◯
itemId アドレス帳との関連付けの作成に成功または失敗したリクエスト項目の一意のID。 整数 ✕
status 失敗したリクエスト項目のHTTP応答コード。 整数 ◯
errorCode エラーのエラーコード。 列挙 ◯
errorDescription エラーのエラーメッセージ。 文字列 ◯

リクエスト全体の失敗を示すHTTPステータスコードとエラーメッセージ

ステータスコード エラーコード エラーメッセージ
400 INVALID_PARAM "ItemId is mandatory for all request items"
400 INVALID_PARAM "AddressBookId is not valid.Please check your Input"
400 INVALID_PARAM "ItemId should be unique for each request item.Multiple requests with itemId [X] present."
400 INVALID_PARAM "Request item list size must be between 1 to 100"
401 Unauthorized "The LWA token is expired or invalid."
403 FORBIDDEN "The user doesn't have permission to perform the operation."
429 Too many requests "Each user has a provisioned TPS at which they can interact with the API, to prevent system brownout.Per-user soft limit and config controlled."
500 INTERNAL_ERROR "Something went wrong"
503 Service Unavailable "The service is currently unavailable to handle the request."

ユニットに対するアドレス帳の関連付けのリストを取得する

GET /v1/addressBooks/unitAssociationsを呼び出すと、ユニットと関連付けられているアドレス帳のリストを取得できます。オプションのmaxResultsとnextTokenの値を使用すると、結果のページ分割を指定できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯
maxResults 1回の呼び出しで取得する結果の最大数。最大値は100です。デフォルト値は10です。 整数 ✕
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文の形式

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.{id}",
            "addressBookId": "amzn1.alexa.addressbook.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

応答本文の例

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
            "addressBookId": "amzn1.alexa.addressbook.did.AF2B2LU7KDOZAMUJRTVCT66DWPFP3BOQ4RZ5GPHAVCIJTMQBJHEDHLANZOJFZSKLG6X2SVE3YCCUZVCP5R7RNZBKI6KHYHGFFLVFIVVJKNU24O45BRMHPBGQ35IPRBZTSI"
        },
        {
            "unitId": "amzn1.alexa.unit.did.AEYCW45GYHMUG622G44G6ZAGBQUDDRVJZT2YKFHPN5UDMGYAXS6S436V5IEUULHS2722CYHOE5BGZMPAIT2VLJAZEUQC2ULVWNOA3VHL",
            "addressBookId": "amzn1.alexa.addressbook.did.AFOEHWC2DFKIOVNRS7NXM7MCVHNTDODUUXZ5XCXFTBNNEL6QDLC6OTHOES6PRRKP6MRSKE4EZ6APO4TTVZF56QNQYUKYSHTATCGG4AKO2NGZPJ2ZXRZP5M2MUPJWU7FORE"
        }
    ],
    "paginationContext": {
             "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

応答本文のパラメーター

フィールド 説明 型 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたユニットIDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳との関連付けを取得する

GET /v1/addressBooks/{addressBookId}/unitAssociationsを呼び出すと、アドレス帳との関連付けを取得できます。オプションのmaxResultsとnextTokenの値を使用すると、結果のページ分割を指定できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

GET /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

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

フィールド 説明 型 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。unitIdが存在する場合、この呼び出しはaddressBookIdとunitIdとの関連付けを返します。存在しない場合は、指定されたaddressBookIdと関連付けられている全ユニットのリストを返します。 文字列 ✕
maxResults 1回の呼び出しで取得する結果の最大数。最大値は100です。デフォルト値は10です。 整数 ✕
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 200 OK

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

応答本文の形式

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.{id}",
            "addressBookId": "amzn1.alexa.addressbook.did.{id}"
        }
    ],
    "paginationContext": {
        "nextToken": "{nextToken}"
    }
}

応答本文の例

{
    "results": [
        {
            "unitId": "amzn1.alexa.unit.did.AFBVKBXMCA7L7I3NTSSE7IPOJ6IMTPCXCP5VXBFYGPHESUEX66WZSPTFDYLTVJVEZYVLQTC5EGS4DK2JEPGSDH4A43YHRCR77WIIVNXU",
            "addressBookId": "amzn1.alexa.addressbook.did.AHZO6C2F4A4AUHY4EPFA3R5KHVBQ763U3ZWPPLXEUAWCVCKYVSTMXH2GR6TN7CFM4KQXMMNWJVAQBP2Y2YBUKOBUPOPNDFDW434MJQ4ZKV6YQNIC575PUW6RVVVUKMEWYA"
        }
    ],
    "paginationContext": {
             "nextToken": "AAEAAavJzV1c7V1j6BM71c4AHc-dqJ9nUXpl6D8H14nmagy1AAAAAFXOThZrtIpviAPjUrloLZi4GMne_LVU_YagltSkUtryw4xCwgAC9Oil5xxertmeGDG5oGU0MLuKiStF6JjV4="
    }
}

応答本文のパラメーター

フィールド 説明 型 必須
unitId ユニットID。"amzn1.alexa.unit.did.{id}"形式で指定します。 文字列 ◯
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。 文字列 ✕

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたはユニットIDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

アドレス帳との関連付けを削除する

DELETE /v1/addressBooks/{addressBookId}/unitAssociationsを呼び出すと、アドレス帳とユニットとの関連付けを削除できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエストの形式

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを適切なエンドポイントに設定してください。前述のAPIエンドポイントを参照してください。

DELETE /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
addressBookId アドレス帳ID。"amzn1.alexa.addressbook.did.{id}"形式で指定します。 文字列 ◯

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

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

リクエスト本文

なし。

応答ヘッダー

HTTP/1.1 204 No Content

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

成功応答本文

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "AddressBook and Unit are not associated"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not found 指定されたアドレス帳IDまたはユニットIDが見つかりませんでした。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

着信用の相互関連付けを管理する

ある施設ユニットに関連付けられているAlexa搭載デバイスへの着信を外部連絡先が発信できるようにするには、該当する施設ユニットに関連付けられているアドレス帳を外部連絡先に追加したうえで、そのユニットとの相互関連付けを作成する必要があります。

相互関連付けを作成する

POST /v1/communications/profile/{profileId}/reciprocalAssociationsを呼び出すと、施設ユニットのprofileIdと外部連絡先のcontactIdとの相互関連付けを作成して、施設ユニットに関連付けられているデバイスが着信先となる通話を外部連絡先がかけられるようにすることができます。このAPI呼び出しは、エンティティ（unit）のコミュニケーション機能プロファイルを、contactIdで指定される外部ユーザーのアドレス帳の連絡先として作成し、Alexaメッセージを外部ユーザーのAlexaアプリやEchoデバイスに送信して、相互連絡先が作成されたことを通知します。

前提条件としてはまず、外部連絡先を作成し、連絡先管理エンドポイントを使用してそのcontactIdを取得する必要があります。相互関連付けの作成対象である施設ユニットと関連付けられるアドレス帳に、外部連絡先が作成済みである必要があります。

ユニットと外部連絡先との相互関連付けが正常に作成されると、外部連絡先は自身のAlexa搭載デバイスやAlexaアプリの連絡先リストでユニット（ルームなど）の連絡先を表示できるようになります。外部連絡先は、Echoデバイスで音声コントロールや画面に表示されるオンスクリーンコントロールを使用して、ユニット（ルームなど）のデバイスに発信できます。外部連絡先は、必要があれば、ユニット（ルームなど）の連絡先をブロックできます。この着信では、メッセージングやドロップイン通話はサポートされていません。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエストの形式

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

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

フィールド 説明 型 必須
profileId エンティティのコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。 文字列 ◯

リクエスト本文

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

リクエスト本文の例

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

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

フィールド 説明 型 必須
contact.id profileIdに対して作成される相互連絡先の、外部連絡先のcontactId。contactIdは、profileIdを持つ施設ユニットと関連付けられるアドレス帳に外部連絡先が作成される際に、連絡先作成エンドポイントへの応答から取得する必要があります。連絡先には電話番号またはprofileIdを含めることができます。電話番号が複数リストされる連絡先に対しては、有効な電話番号すべてについて相互関連付けが試みられます。contactIdの形式はamzn1.alexa.contact.did.{contactId}である必要があります。 文字列 ◯

応答ヘッダー

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

応答本文

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

応答本文の例

{
    "profileId": "amzn1.alexa.communications.profile.did.AHJ6NDRSRIOBWBCRWDGXTGXTQE",
    "contactId": "amzn1.alexa.contact.did.AHXG6V247SZDZB6LXU6BYXYMJS3XI5"
}

応答本文のパラメーター

フィールド 説明 型
profileId コミュニケーション機能プロファイルの一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。コミュニケーション機能プロファイルが既に存在する場合は、そのユニットの既存のprofileIDが返されます。 文字列
contactId profileIdに対して作成される相互連絡先のcontactId。contactIdは連絡先作成エンドポイントによって返されます。 文字列

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profileId is not valid"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
400 Bad Request Alexaアプリで連絡先のコミュニケーション機能が有効になっていません。追加できるのはAlexaコミュニケーション機能が有効になっている連絡先だけです。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found コミュニケーション機能プロファイルが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

相互関連付けのステータスを取得する

GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}を呼び出すと、profileIdとcontactIdとの間での相互連絡先のステータスを取得できます。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエストの形式

*GET */v1/communications/profile/{ownerProfileId}/reciprocalAssociations?contactId={contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

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

フィールド 説明 型 必須
profileId エンティティのコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。 文字列 ◯

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

フィールド 説明 型 必須
contactId profileIdとの相互関連付けステータスの取得対象であるcontactId。contactIdは連絡先作成エンドポイントによって返されます。 文字列 ◯

リクエスト本文

なし。

リクエスト本文の例

なし。

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

なし。

応答ヘッダー

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

応答本文

{
  "results": [
    {
      "contact": {
        "contactId": "amzn1.alexa.contact.{contactId}"
      },
      "status": "ENABLED|DISABLED"
    }
  ],
  "paginationContext": {
    "nextToken": "string"
  }
}

応答本文の例

{
  "results": [
    {
      "contact": {
        "contactId": "amzn1.alexa.contact.9ef21be8-ae5b-46ef-965e-4f8427fb308d"
      },
      "status": "ENABLED"
    }
  ],
  "paginationContext": {
    "nextToken": "null"
  }
}

応答本文のパラメーター

フィールド 説明 型
contactId profileIdとの相互関連付けステータスの取得対象であるcontactId。contactIdは連絡先作成エンドポイントによって返されます。 文字列
status contactIdとprofileIdとの間に相互関連付けが存在する場合はENABLED、ない場合はDISABLED。
外部連絡先に電話番号が複数ある場合、API応答は、連絡先にリストされる電話番号のいずれかにユニットとの相互連絡先が作成済みであればENABLEDを返し、それ以外の場合にDISABLEDを返します。		 文字列
nextToken nextTokenの値を次回のリクエストで継続トークン（nextTokenクエリパラメーター）に指定すると、結果の次のページを取得できます。詳細については、クエリ結果のページ分割を処理するを参照してください。  

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profileId is not valid"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
400 Bad Request contactIdが無効です。
400 Bad Request Alexaコミュニケーションをプロビジョニング済みのユーザーがcontactIdにありません。
400 Bad Request 連絡先が作成されたアドレス帳が、profileIdのエンティティに関連付けられていません。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
403 Forbidden 指定されたユーザーにはこの機能へのアクセス権限がありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

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

DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}を呼び出すと、profileIdとcontactIdとの間での相互関連付けを削除できます。このAPIは、contactIdのユーザーのアドレス帳の連絡先としてのエンティティ（UNIT）を削除し、Alexaメッセージを外部ユーザーのAlexaアプリやEchoデバイスに送信して、関連付けが削除されたことをユーザーに通知します。相互関連付けの削除により、該当する外部連絡先から該当するユニットへの着信が無効になります。

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

Healthcare Hospitality Senior Living Core

なし

日本

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

なし

リクエストの形式

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

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

フィールド 説明 型 必須
profileId エンティティのコミュニケーション機能プロファイルを指定する一意のプロファイルID。コミュニケーション機能プロファイルの初回作成時に生成されています。 文字列 ◯

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

フィールド 説明 型 必須
contactId profileIdとの相互関連付けステータスの取得対象であるcontactId。contactIdは連絡先作成エンドポイントによって返されます。 文字列 ◯

リクエスト本文

なし。

リクエスト本文の例

なし。

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

なし。

応答ヘッダー

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

応答本文

なし。

応答本文の例

なし。

応答本文のパラメーター

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profileId is not valid"
}

HTTP応答コード

ステータスコード 説明 理由
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
400 Bad Request contactIdが無効です。
400 Bad Request Alexaコミュニケーションをプロビジョニング済みのユーザーがcontactIdにありません。
400 Bad Request 連絡先が作成されたアドレス帳が、profileIdのエンティティに関連付けられていません。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
403 Forbidden 指定されたユーザーにはこの機能へのアクセス権限がありません。
404 Not Found unitIdが存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

呼びかけ設定を管理する

Alexaコミュニケーション機能の設定APIを使用して、Alexa Smart Propertiesのユニット（ルームなど）の呼びかけ設定を管理できます。この設定は、ユニットID間で直接設定されるのではなく、Alexaコミュニケーション機能プロファイルを使用して設定されます。

呼びかけ設定を設定する

Alexaユニットから別のAlexaユニットへの呼びかけを有効または無効にするには、呼びかけ設定を設定する必要があります。呼びかけ設定を有効にすると、alexaCommunicationProfileIdにリンクされているAlexaユニットから、sourceProfileIdにリンクされているAlexaユニットへの呼びかけが可能になります。

PUT /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}を呼び出すと、呼びかけ設定を設定できます。

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

Healthcare Hospitality Senior Living Core

米国

なし

なし

なし

リクエストの形式

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

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

フィールド 説明 型 必須
sourceProfileId 呼びかけ元からの呼びかけを許可／拒否する権限が設定されているユニットのprofileIdを示します。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。 文字列 ◯

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

フィールド 説明 型 必須
alexaCommunicationProfileId 呼びかけ先への呼びかけが許可／拒否されている呼びかけ元ユニットのprofileIdを示します。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。 文字列 ◯

リクエスト本文

{    
    "value": "<Setting>"
}

リクエスト本文の例

{
    "value": "ENABLED"
}

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

フィールド 説明 型 必須
value 呼びかけの有効化のステータス。有効な値は ENABLED、DISABLEDです。 文字列 ◯

応答ヘッダー

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

応答本文

なし。

応答本文の例

なし。

応答本文のパラメーター

なし。

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profileId is not valid"
}

HTTP応答コード

ステータスコード 説明 理由
204 No Content リクエストが成功しました。
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request profileIdが無効です。
400 Bad Request DropIn設定キーの有効な値は、ENABLED、DISABLEDです。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
404 Not Found 指定されたprofileIdの連絡先が存在しません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

呼びかけ設定を取得する

Alexaユニットから別のAlexaユニットへの呼びかけ権限の現在の状態を取得します。設定APIは、呼びかけ先（ソースプロファイルID）から呼びかけ権限が許可されている呼びかけ元（ターゲットプロファイルID）を示します。

GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}を呼び出すと、sourceProfileIdに設定されているすべての呼びかけ設定を取得できます。

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

Healthcare Hospitality Senior Living Core

米国

なし

なし

なし

リクエストの形式

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

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

フィールド 説明 型 必須
sourceProfileId 呼びかけ元からの呼びかけを許可／拒否する権限が設定されているユニットのprofileIdを示します。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。 文字列 ◯

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

フィールド 説明 型 必須
alexaCommunicationProfileId 呼びかけ先への呼びかけが許可／拒否されている呼びかけ元ユニットのprofileIdを示します。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。
このパラメーターが指定されていない場合、APIはsourceProfileIdから呼びかけ権限が許可／拒否されているすべての呼び出し元のリストを返します。		 文字列 ✕

リクエスト本文

なし。

リクエスト本文の例

なし。

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

フィールド 説明 型 必須
value 呼びかけの有効化のステータス。有効な値は ENABLED、DISABLEDです。 文字列 ◯

応答ヘッダー

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

応答本文

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

応答本文の例

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

応答本文のパラメーター

フィールド 説明 型 必須
'setting' 定数値は"DropIn"です。 文字列 ◯
'contactID' 呼びかけが許可／拒否されている連絡先。 文字列 ◯
alexaCommunicationProfileId 呼びかけ先への呼びかけが許可／拒否されているコミュニケーション機能プロファイル。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。 文字列 ◯
value 呼びかけ設定の現在のステータスを示します。値はENABLED、DISABLEDのどちらかです。 文字列 ◯

エラー応答本文の形式

{
    "message": "{errorMessage}"
}

エラー応答本文の例

{
    "message": "Communication profileId is not valid"
}

HTTP応答コード

ステータスコード 説明 理由
200 OK 成功
400 Bad Request リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。
400 Bad Request DropIn設定キーの有効な値は、ENABLED、DISABLEDです。
401 Unauthorized LWAトークンが有効期限切れか無効です。
403 Forbidden 操作を実行する権限がユーザーにありません。
403 Forbidden 指定されたユーザーにはこの機能へのアクセス権限がありません。
404 Not Found sourceProfileIdにはalexaCommunicationProfileIdは連絡先として設定されていません。
429 Too many requests 各ユーザーにはプロビジョンドTPSが指定されており、ユーザーはこの処理速度でAPIとやり取りできます。これはシステムのブラウンアウトを防ぐための措置です。ユーザーごとのソフト制限およびソフト設定が制御されます。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスは現在利用できず、リクエストを処理できません。

ブロックルールを管理する

ブロックルールを作成して、2つの施設ユニット間の通話とメッセージを無効にできます。

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

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

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

Healthcare Hospitality Senior Living Core

米国

米国

米国

米国

リクエスト

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

このリクエストにより、alexaCommunicationProfileIdユニットからprofileIdユニットへの通話がブロックされます。ただし、profileIdユニットからalexaCommunicationProfileIdユニットへの電話は引き続き可能です。

リクエストヘッダーの例

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

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
リクエストのヘッダーとパスのパラメーター
パラメーター 位置 説明 型 必須

access token

ヘッダー

LWAアクセストークン。

文字列

◯

profileId

パス

alexaCommunicationProfileIdユニットからの電話を受信拒否するユニットのコミュニケーション機能プロファイルID。

文字列

◯

alexaCommunicationProfileId

クエリ

profileIdユニットへの通話をブロックするユニットのコミュニケーション機能プロファイルID。

文字列

✕

リクエスト本文の例

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

{
   "value" : "ENABLED"
}
リクエスト本文のパラメーター
パラメーター 説明 型 必須

value

ブロックの設定値。有効な値は、 コミュニケーション機能をブロックする場合はENABLED、有効にする場合はDISABLEDです。

文字列

◯

応答

正常に完了すると、HTTP 204が返されます。

応答本文の例

正常に完了した場合、応答の本文はありません。

以下は、考えられるエラー応答の本文の例です。

{
    "message": "Source and Target CommunicationProfileId cannot be the same."
}
応答本文のパラメーター

正常に完了した場合、応答の本文はありません。

エラー応答には以下のパラメーターが含まれます。

パラメーター 説明 型

message

エラーの説明。

文字列

HTTPステータスコード
ステータス 説明

204 No content

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

400 Bad Request

 リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。例は以下のとおりです。


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

401 Unauthorized

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

403 Forbidden

リクエストを完了できませんでした。この操作を実行する権限がありません。

404 Not Found

指定されたprofileIdの連絡先が存在しません。

429 Too Many Requests

許可されたレート制限（単位時間あたりの指定されたリクエスト数）を超過しています。

500 Internal Server Error

サーバー側のエラーが発生しました。

503 Service Unavailable

サービスは現在利用できず、リクエストを処理できません。

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

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

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

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}
リクエストのヘッダーとパスのパラメーター
パラメーター 位置 説明 型 必須

access token

ヘッダー

LWAアクセストークン。

文字列

◯

profileId

パス

ブロックルールを取得するユニットのコミュニケーション機能プロファイルID。

文字列

◯

value

クエリ

ブロックの設定値。有効な値は、 コミュニケーション機能をブロックする場合はENABLED、有効にする場合はDISABLEDです。

文字列

✕

alexaCommunicationProfileId

クエリ

ターゲットコミュニケーション機能プロファイルの一意のID。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。このパラメーターを指定すると、応答にはこのターゲットの設定のみが含まれます。

文字列

✕

nextToken

クエリ

ページ分割された結果から特定のページを取得するためのトークン。このトークンがない場合、応答には結果の先頭ページが含められます。

文字列

✕

maxResults

クエリ

応答本文で返される結果の最大数。100以下の正の値を指定してください。デフォルト値は100です。値は変更される可能性があります。

数値

✕

リクエスト本文の例

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

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

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

応答

正常に完了すると、HTTP 200が返されます。

応答本文の例

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

{
  "results": [
    {
      "setting": "Block",
      "contactId": "{contactId}",
      "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.{profileId}",
      "value": "ENABLED"
    },
    {
      "setting": "Block",
      "contactId": "{contactId}",
      "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.{profileId}",
      "value": "ENABLED"
    }
  ],
  "paginationContext": {
     "nextToken": "String"
  }
}

以下は、考えられるエラー応答の本文の例です。

{
    "message": "Source and Target CommunicationProfileId cannot be the same."
}

成功した応答本文のパラメーター

パラメーター 説明 型

results

ブロックルールオブジェクトのリスト。

オブジェクトの配列

results[*].setting

取得した設定。値はBlockです。

文字列

results[*].contactId

連絡先ID。amzn1.alexa.contacts.did.{id}形式で指定します。

文字列

results[*].alexaCommunicationProfileId

ターゲットコミュニケーション機能プロファイルの一意のID。amzn1.alexa.communications.profile.did.{profileId}形式で指定します。

文字列

results[*].value

ブロックの設定値。有効な値は、 コミュニケーション機能をブロックする場合はENABLED、有効にする場合はDISABLEDです。

文字列

paginationContext

ページ分割の詳細。

オブジェクト

paginationContext.nextToken

ページ分割された結果から特定のページを取得するためのトークン。

文字列

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

パラメーター 説明 型

message

エラーの説明。

文字列

HTTPステータスコード
ステータス 説明

200 Success

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

400 Bad Request

 リクエストに1つ以上の必須パラメーターが不足しているか、パラメーターの値が無効です。例は以下のとおりです。


  • ソース（ブロック元）とターゲット（ブロック先）のコミュニケーション機能プロファイルIDを同じにすることはできません。つまり、profileIdをalexaCommunicationProfileIdと同じにすることはできません。
  • alexaCommunicationProfileIdはクエリパラメーターとして渡す必要があります。

401 Unauthorized

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

403 Forbidden

リクエストを完了できませんでした。この操作を実行する権限またはこの機能にアクセスする権限がありません。

404 Not Found

profileIdにはalexaCommunicationProfileIdは連絡先として設定されていません。

429 Too Many Requests

許可されたレート制限（単位時間あたりの指定されたリクエスト数）を超過しています。

500 Internal Server Error

サーバー側のエラーが発生しました。

503 Service Unavailable

サービスは現在利用できず、リクエストを処理できません。

リソースの上限

リソース デフォルト 上限を超過した場合のエラーメッセージ

アドレス帳に含められる連絡先の最大数

2000

"You have reached the maximum number of contacts that can be created per address book: 2000"

1つのユニットに関連付けることができるアドレス帳の最大数

10

"You have reached the maximum number of address books that can be associated with a unit: 10"

1つのユニットに関連付けることができる電話番号の最大数

10

"You have reached the maximum number of phone numbers that can be associated with a unit: 10"

1つのアドレス帳に関連付けることができるユニットの最大数

2500

"You have reached the maximum number of units that can be associated with an address book: 2500"

連絡先あたりの電話番号の最大数

3

"The number of phone numbers must be between 1 and 3"

組織あたりのアドレス帳の最大数

35000

"You have reached maximum number of address books that you can create per organization: 35000"

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

最終更新日: 2024 年 03 月 21 日