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

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

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

APIエンドポイント

コミュニケーション機能APIのエンドポイントは、https://api.amazonalexa.comです。

認証

すべてのAPIリクエストには認可ヘッダーが必要であり、その値には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トークン}

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

ありません。

リクエスト本文の形式

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.{UnitId}"
    },
    "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 コミュニケーション機能プロファイルの表示名です。

名前の文字列は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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスが現在利用不可能なため、リクエストを処理できません。

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

複数のコミュニケーション機能プロファイルを一括で作成するには、POST /v1/communications/profiles/batchを呼び出します。1回のリクエストで最大100ユニットのプロファイル（ユニットあたり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トークン}

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

ありません。

リクエスト本文の形式

{
    "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": "フロントデスク"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.DFG2A43WS5ED6RF7TG8Y9HJS6D57FCGE83"
            },
            "name": "ホテルレストラン"
        }
    ]
}

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

フィールド 説明 型 必須
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トークン}

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

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

リクエスト本文の形式

{
    "name": "<プロファイルの表示名>"
 }

リクエスト本文の例

{
    "name": "Dave"
 }

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

フィールド 説明 型 必須
name コミュニケーション機能プロファイルの表示名です。

名前の文字列は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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスが現在利用不可能なため、リクエストを処理できません。

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

コミュニケーション機能プロファイルに関連付けられているユニットIDを取得するには、GET /v1/communications/profile/{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トークン}

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

フィールド 説明 型 必須
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": "プロファイルの表示名",
    "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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスが現在利用不可能なため、リクエストを処理できません。

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

コミュニケーション機能プロファイルに関連付けられているユニットIDを取得するには、GET /v1/communications/profile?entity.type={entity.type}&entity.id={entity.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トークン}

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

フィールド 説明 型 必須
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": "プロファイルの表示名",
    "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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

ありません。

リクエスト本文の形式

{
    "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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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形式で指定する必要があります。1つの連絡先に電話番号を3つまで指定できます。同じ連絡先に電話番号とalexaCommunicationProfileIdの両方を追加することはできません。注： フランス（fr-FR）では、電話番号はサポートされません。 文字列 ◯
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 連絡先には、少なくとも1つのnumberオブジェクト、または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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスが現在利用不可能なため、リクエストを処理できません。

連絡先を一括で作成する

アドレス帳に複数の連絡先を一括で作成するには、POST /v1/addressBooks/{addressBookId}/contacts/batchを呼び出します。1回のリクエストで最大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トークン}

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

フィールド 説明 型 必須
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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の両方を追加することはできません。注： フランス（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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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形式で指定する必要があります。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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
500 Internal Server Error 内部サービスエラーが発生しました。
503 Service Unavailable サービスが現在利用不可能なため、リクエストを処理できません。

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

アドレス帳を最大100個のユニットに一括で関連付けるには、POST /v1/addressBooks/{addressBookId}/unitAssociations/batchを呼び出します。

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

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トークン}

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

フィールド 説明 型 必須
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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トークン}

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

フィールド 説明 型 必須
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 システムの電圧降下を防ぐために、各ユーザーにはAPIと対話できるTPSがプロビジョニングされています。ユーザーごとのソフト制限および設定によって制御されました。
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 月 16 日