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

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

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

APIエンドポイント

コミュニケーション機能APIのエンドポイントは、https://api.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

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

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

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

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

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

Healthcare Hospitality Residential 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": "Dave"
}

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

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

名前の文字列は1～128文字の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 Residential 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": "Front desk"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
            },
            "name": "Hotel Restaurant"
        }
    ]
}

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

フィールド 説明 型 必須
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 Residential 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": "Dave"
 }

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

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

名前の文字列は1～128文字の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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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": "Dave",
    "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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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": "Dave",
    "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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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

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

なし。

リクエスト本文の形式

{
    "name": "{addressbookName}"
}

リクエスト本文の例

{
    "name": "Example Hotel Seattle"
}

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

フィールド 説明 型 必須
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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Hotel Seattle"
        }

    ],
    "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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Hotel Seattle"
}

応答本文のパラメーター

フィールド 説明 型 必須
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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Hotel Seattle"
}

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

フィールド 説明 型 必須
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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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番号を表すアドレス帳エントリです。連絡先の作成には、電話番号とコミュニケーション機能プロファイルのどちらかを使用できます。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Hotel Reception",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    }
}

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

{
    "contact": {
        "name": "Example Hotel Laundry Service",
        "phoneNumbers": [
            {
                "number": "+12055551233"
            },
            {
                "number": "+12055551244"
            }
        ]
    }
}

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

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

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

{
    "contact": {
        "name": "Example Hotel Laundry Service",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

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

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

応答ヘッダー

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 Residential 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": "Diego Ramirez",
                "phoneNumbers": [
                    {
                        "number": "{phoneNumber}"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
              "name": "Nurse station",
              "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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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": "Marriott Reception",
            "contactId": "amzn1.alexa.contact.did.AGNA6I63RJBIV7EFEL73AJEIUZ7XGKDCB7VYRO6JTLMHX72F2P4YX4ZVZNCWB3SZR5ZS5ETPJTCCHCTV2NV2XU66GCKSNGF54PZCBCUE"
        },
        {
            "contactName": "Blueacre Restaurant",
            "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 Residential Senior Living Core

米国

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

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

米国

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

米国

リクエストの形式

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 Hotel Seattle Reception",
        "phoneNumbers": [
            {
                "number": "+16055554411"
            }
        ]
    },
    "contactId": "amzn1.alexa.contact.did.AGKABCFZTM7UVXPXYQDJED2L6TLVIOMURFFTBG65WW3FA6UQXWQ6BJES2CFS7SZ6L4R2MXEU35TAQW7X7EQXBSHS6AGOO4XBUYZ6TPAU"
}

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

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

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

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

応答本文のパラメーター

フィールド 説明 型 必須
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
number 連絡先の電話番号。E.164形式である必要があります。電話番号は3つまで追加できます。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。 文字列 ◯
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 Residential Senior Living Core

米国

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

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

米国

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

米国

リクエストの形式

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 Hotel Seattle Reception",
        "phoneNumbers": [
            {
                "number": "+16055554412"
            }
        ]
    }
}

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

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

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

{
    "contact": {
        "name": "Example Hotel Seattle Reception",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.AE4Y3SCIFVMNLJRVI66TBJZ6PFZVEO36RPG5DD2NAOI7BODAYNIRL32QL72CPHOLFRVI3ZZXFWXLF4ORJ3HZ4PW42ANPUTA5K7LVQ2B"
    }
}

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

フィールド 説明 型 必須
name 連絡先の名前。文字数は1～50文字である必要があります。 文字列 ◯
number 連絡先の電話番号。E.164形式の米国、英国、カナダ（CA）の電話番号である必要があります。1つの連絡先に電話番号を3つまで指定できます。同じ連絡先に電話番号とalexaCommunicationProfileIdを両方追加することはできません。 文字列 ◯
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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential 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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

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 Residential 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が無効です。
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 Residential 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 Residential 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 サービスは現在利用できず、リクエストを処理できません。

リソースの上限

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

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

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"

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