アドレス帳REST APIリファレンス

アドレス帳REST APIリファレンス

アドレス帳REST APIを使用すると、Alexa Smart Properties（ASP）のアドレス帳を管理し、ルームにアドレス帳を関連付けたり、アドレス帳に連絡先を追加したりできます。

ルームのアドレス帳に連絡先を追加する前に、コミュニケーション機能プロファイルを作成して通話機能を有効にする必要があります。Alexaは、ユニットIDの代わりにコミュニケーション機能プロファイルIDを使用して、ルーム内のAlexa搭載デバイスを識別します。詳細については、コミュニケーション機能REST APIリファレンスを参照してください。

代わりにASPマネジメントコンソールでアドレス帳や連絡先の作成と管理を行う場合は、マネジメントコンソールでのコミュニケーション機能の管理を参照してください。

リソースの上限

アドレス帳APIでは、リソースの上限が以下のように定義されています。上限を超えるとリクエストは失敗し、上限に達したことを示すmessageが応答の本文に追加されます。

リソース 上限 エラーメッセージ

アドレス帳あたりの連絡先の数

2000

You have reached the maximum number of contacts that can be created per address book: 2000.（アドレス帳あたりに作成できる連絡先の最大数（2000）に達しました。）

1つのユニットに関連付けられるアドレス帳の数

10

You have reached the maximum number of address books that can be associated with a unit: 10.（1つのユニットに関連付けることができるアドレス帳の最大数（10）に達しました。）

1つのアドレス帳に関連付けられるユニットの数

2500

You have reached the maximum number of units that can be associated with an address book: 2500.（1つのアドレス帳に関連付けることができるユニットの最大数（2500）に達しました。）

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

3

The number of phone numbers must be between 1 and 3.（電話番号の数は1～3個である必要があります。）

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

35000

You have reached maximum number of address books that you can create per organization: 35000.（組織あたりに作成できるアドレス帳の最大数（35000）に達しました。）

APIエンドポイント

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

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.amazonalexa.com

認証

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

操作

アドレス帳APIでは、以下の操作タイプがサポートされています。

  • アドレス帳の管理 - アドレス帳を作成し、施設のルームに関連付けます。
  • 連絡先の管理 - 連絡先を作成し、アドレス帳に追加します。連絡先の作成には、電話番号、コミュニケーション機能プロファイル、WebRTCサービスプロバイダーのいずれかを使用できます。

アドレス帳の管理

操作 HTTPメソッドとURI

アドレス帳を作成する

POST /v1/addressBooks

アドレス帳を削除する

DELETE /v1/addressBooks/{addressBookId}

アドレス帳を取得する

GET /v1/addressBooks/{addressBookId}

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

GET /v1/addressBooks?maxResults={maxResults}&nextToken={nextToken}

アドレス帳を更新する

PUT /v1/addressBooks/{addressBookId}

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

POST /v1/addressBooks/{addressBookId}/unitAssociations

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

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

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

DELETE /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}

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

GET /v1/addressBooks/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken}

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

GET /v1/addressBooks/{addressBookId}/unitAssociations?unitId={unitId}&maxResults={maxResults}&nextToken={nextToken}

連絡先の管理

操作 HTTPメソッドとURI

連絡先を作成する

POST /v1/addressBooks/{addressBookId}/contacts

連絡先を一括で作成する

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

連絡先を削除する

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

連絡先を取得する

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

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

GET /v1/addressBooks/{addressBookId}/contacts?maxResults={maxResults}&nextToken={nextToken}

連絡先を更新する

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

アドレス帳を作成する

アドレス帳を作成します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アドレス帳を作成するには、/v1/addressBooksリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
    "name": "Address Book for Property Name"
}

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

プロパティ 説明 型 必須

name

アドレス帳の名前。
有効な値は 1～50文字の英数字です。

文字列

◯

応答

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

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

addressBookId

新しいアドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

200 OK

アドレス帳のIDが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

アドレス帳を削除する

指定されたアドレス帳を削除します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アドレス帳を削除するには、/v1/addressBooks/{addressBookId}リソースに対してDELETEリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

アドレス帳が正常に削除されました。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

アドレス帳を取得する

指定されたアドレス帳の詳細を取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アドレス帳の詳細を取得するには、v1/addressBooks/{addressBookId}リソースに対してGETリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

name

アドレス帳の名前。
有効な値は 1～50文字の英数字です。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたアドレス帳に関する詳細が応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

呼び出し元が所有しているアドレス帳のリストを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アドレス帳のリストを取得するには、/v1/addressBooksリソースに対してGETリクエストを実行します。

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

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

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

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

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

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

{
    "results": [{
            "addressBookId": "amzn1.alexa.addressbook.did.1000",
            "name": "Property Address Book"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.1"
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

アドレス帳のリスト。

オブジェクトの配列

results[].addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].name

アドレス帳の名前。
有効な値は 1～50文字の英数字です。

文字列

paginationContext

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

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

呼び出し元が所有しているアドレス帳のリストが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

アドレス帳を更新する

指定されたアドレス帳の名前を更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アドレス帳の名前を更新するには、/v1/addressBooks/{addressBookId}リソースに対してPUTリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
    "name": "Example Property Name"
}

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

プロパティ 説明 型 必須

name

アドレス帳の名前。
有効な値は 1～50文字の英数字です。

文字列

◯

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

アドレス帳のプロパティが正常に更新されました。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定されたユニットにアドレス帳を関連付けます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

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

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

プロパティ 説明 型 必須

unitId

アドレス帳に関連付けるユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

応答

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

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

unitId

アドレス帳に関連付けるユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

204 No Content

ユニットとアドレス帳の関連付けが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定されたアドレス帳を最大100個のユニットに関連付けます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

関連付けを作成するには、/v1/addressBooks/{addressBookId}/unitAssociations/batchリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

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

プロパティ 説明 型 必須

items

アドレス帳に関連付けるユニットのリスト。

オブジェクトの配列

◯

items[].itemId

連絡先の一意の識別子。通常は1から始まる連番です。

整数

◯

items[].unitId

アドレス帳に関連付けるユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

応答

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

応答本文の例

以下の例は成功応答を示し、各項目に連絡先IDが割り当てられています。

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

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

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

応答本文のプロパティ

プロパティ 説明 型

results

成功した結果のリスト。

オブジェクトの配列

results[].itemId

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

整数

results[].unitId

アドレス帳に関連付けられたユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

errors

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

オブジェクトの配列

errors[].itemId

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

整数

errors[].status

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

整数

errors[].errorCode

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

文字列

errors[].errorDescription

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

文字列

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

status errorCode errorDescription

400

INVALID_PARAM

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

400

INVALID_PARAM

UnitId is mandatory.（unitIdは必須です。）

403

FORBIDDEN

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

404

INVALID_PARAM

UnitId doesn't exist.（unitIdが存在しません。）

409

INVALID_PARAM

AddressBook is already associated with the unit.（アドレス帳は既にユニットに関連付けられています。）

500

INTERNAL_ERROR

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

HTTPステータスコード

ステータス 説明

200 OK

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

400 Bad Request

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

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

  • itemIdはすべてのリクエスト項目で必須です。
  • addressBookIdが無効です。入力を確認してください。
  • itemIdはリクエスト項目ごとに一意である必要があります。itemId [X]を使用するリクエストが複数存在します。
  • リクエスト項目のリストサイズは1～100である必要があります。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

アドレス帳とユニットの間の関連付けを削除します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

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

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

unitId

クエリ

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

関連付けが正常に削除されました。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定されたユニットに関連付けられているアドレス帳のリストを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

関連付けを取得するには、/v1/addressBooks/unitAssociationsリソースに対してGETリクエストを実行します。

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

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

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

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

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

unitId

クエリ

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

文字列

◯

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

{
    "results": [{
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1235"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.2"
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

関連付けのリスト。

オブジェクトの配列

results[].unitId

アドレス帳に関連付けられたユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

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

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

ユニットとアドレス帳の関連付けが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定されたアドレス帳に対するユニットの関連付けのリストを取得します。必要に応じてユニットIDを指定すると、特定のユニットの関連付けを取得できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

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

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

unitId

クエリ

ユニットを識別します。
unitIdの指定がある場合、応答には、addressBookIdとunitIdとの関連付けが返されます。指定がない場合、応答には、指定されたaddressBookIdに関連付けられているすべてのユニットのリストが返されます。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

{
    "results": [{
            "unitId": "amzn1.alexa.unit.did.101",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.102",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        },
        {
            "unitId": "amzn1.alexa.unit.did.103",
            "addressBookId": "amzn1.alexa.addressbook.did.1234"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.2"
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

関連付けのリスト。

オブジェクトの配列

results[].unitId

アドレス帳に関連付けられたユニットを識別します。
amzn1.alexa.unit.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

results[].addressBookId

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

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

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

ユニットとアドレス帳の関連付けが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

連絡先を作成する

指定されたアドレス帳に連絡先を追加します。連絡先は、通話可能なAlexa搭載デバイス、PSTN番号、WebRTCエンドポイントのいずれかを表すアドレス帳エントリです。連絡先の作成には、電話番号、コミュニケーション機能プロファイル、WebRTC通話のサービスプロバイダーの連絡先IDのいずれかを使用できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

連絡先を作成するには、/v1/addressBooks/{addressBookId}/contactsリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

次の例は、指定したアドレス帳に連絡先を作成するリクエストを示しています。連絡先は、電話番号、コミュニケーション機能プロファイル、WebRTCサービスプロバイダーのいずれかとして定義できます。

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

プロパティ 説明 型 必須

contact

作成する連絡先。number、alexaCommunicationProfileId、providerContactのいずれかの連絡先タイプを指定します。

オブジェクト

◯

contact.name

連絡先の名前。
有効な値は 1～50文字の英数字です。

文字列

◯

contact.number

連絡先の電話番号。
米国、英国、カナダ（CA）の電話番号をE.164形式で表す必要があります。1つの連絡先に最大3つの電話番号を指定できます。

文字列

✕

contact.alexaCommunicationProfileId

ユニットのコミュニケーション機能プロファイルを識別します。
この値は、コミュニケーション機能REST APIリファレンスに記載されているprofileIdと同じです。
amzn1.alexa.communications.profile.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

contact.providerContact

WebRTC通話の場合にのみ指定します。

オブジェクト

✕

contact.providerContact.id

サービスプロバイダーの内部ID。
amzn1.comms.csp.id.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

応答

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

応答本文の例

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

応答本文のプロパティ

プロパティ 説明 型

contactId

連絡先を表すID。
amzn1.alexa.contact.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

HTTPステータスコード

ステータス 説明

204 No Content

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

400 Bad Request

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

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

  • 連絡先には、少なくとも1つのnumberか、alexaCommunicationProfileIdまたはproviderContact.idプロパティが必要です。
  • 連絡先にnumberとalexaCommunicationProfileIdの両方を含めることはできません。
  • alexaCommunicationProfileIdの文字数は40～200文字である必要があります。

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

連絡先を一括で作成する

アドレス帳の連絡先を一括で作成します。単一のリクエストで最大100件の連絡先を作成できます。連絡先は、通話可能なAlexa搭載デバイスまたはPSTN番号を表すアドレス帳エントリです。連絡先の作成には、電話番号またはコミュニケーション機能プロファイルを使用できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

複数の連絡先を作成するには、/v1/addressBooks/{addressBookId}/contacts/batchリソースに対してPOSTリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

{
    "items": [{
            "itemId": 1,
            "contact": {
                "name": "Mary - Room 202",
                "phoneNumbers": [{
                        "number": "+15555551212"
                    },
                    {
                        "number": "+15555551213"
                    }
                ]
            }
        },
        {
            "itemId": 2,
            "contact": {
                "name": "Bob - Room 203",
                "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.1234"
            }
        }
    ]
}

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

プロパティ 説明 型 必須

items

アドレス帳に追加する連絡先のリスト。

オブジェクトの配列

◯

items[].itemId

連絡先の一意の識別子。通常は1から始まる連番です。

整数

◯

items[].contact

作成する連絡先。項目ごとに、number、alexaCommunicationProfileId、providerContactのいずれかの連絡先タイプを指定します。

オブジェクト

◯

items[].contact.name

連絡先の名前。
有効な値は 1～50文字の英数字です。

文字列

◯

items[].contact.number

連絡先の電話番号。
米国、英国、カナダ（CA）の電話番号をE.164形式で表す必要があります。1つの連絡先に最大3つの電話番号を指定できます。

文字列

✕

items[].contact.alexaCommunicationProfileId

ユニットのコミュニケーション機能プロファイルを識別します。
この値は、コミュニケーション機能REST APIリファレンスに記載されているprofileIdと同じです。
amzn1.alexa.communications.profile.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

items[].contact.providerContact

WebRTC通話の場合にのみ指定します。

オブジェクト

✕

items[].contact.providerContact.id

サービスプロバイダーの内部ID。
amzn1.comms.csp.id.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

応答

正常に完了すると、HTTP 201 Createdと共に、連絡先IDのリストが返されます。リクエスト全体が失敗した場合は、適切なHTTPステータスコードが応答として返され、エラーを説明するmessage文字列が応答の本文に追加されます。個々の項目でエラーが発生した場合、応答本文には成功とエラーの項目が含まれます。

応答本文の例

以下の例は成功応答を示し、各項目に連絡先IDが割り当てられています。

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

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

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

応答本文のプロパティ

プロパティ 説明 型

results

成功した結果のリスト。

オブジェクトの配列

results[].itemId

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

整数

results[].contactId

連絡先の一意のID。
amzn1.alexa.contact.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

errors

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

オブジェクトの配列

errors[].itemId

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

整数

errors[].status

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

整数

errors[].errorCode

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

文字列

errors[].errorDescription

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

文字列

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

status errorCode errorDescription

400

INVALID_PARAM

Contact must have at least one PhoneNumber or a CommunicationProfileId.（連絡先には、少なくとも1つの電話番号またはコミュニケーション機能プロファイルIDが必要です。）

400

INVALID_PARAM

A Contact can't contain both PhoneNumber and a CommunicationProfileId. You must add either one.（連絡先に電話番号とコミュニケーション機能プロファイルIDの両方を含めることはできません。どちらか1つを追加する必要があります。）

400

INVALID_PARAM

AlexaCommunicationProfileId isn't in standard format.（alexaCommunicationProfileIdが標準形式ではありません。）

400

INVALID_PARAM

Given phone number is not per E.164 format.（指定された電話番号がE.164形式に従っていません。）

400

INVALID_PARAM

Contact is mandatory.（contactは必須です。）

400

INVALID_PARAM

Contact Name must be between 1 and 50 characters.（連絡先の名前は1～50文字である必要があります。）

400

INVALID_PARAM

Number of phone numbers must be between 1 and 3.（電話番号の数は1～3個である必要があります。）

400

INVALID_PARAM

ItemId is mandatory for all request items.（itemIdはすべてのリクエスト項目で必須です。）

400

INVALID_PARAM

ItemId should be unique for each request item. Multiple requests with itemId [X] present.（itemIdはリクエスト項目ごとに一意である必要があります。itemId [X]を使用するリクエストが複数存在します。）

400

INVALID_PARAM

Request item list size must be between 1 to 100.（リクエスト項目のリストサイズは1～100である必要があります。）

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ステータスコード

ステータス 説明

204 No Content

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

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

連絡先を削除する

指定されたアドレス帳から連絡先を削除します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

連絡先を削除するには、/v1/addressBooks/{addressBookId}/contacts/{contactId}リソースに対してDELETEリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

contactId

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

204 No Content

連絡先が正常に削除されました。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

連絡先を取得する

アドレス帳から指定された連絡先の詳細を取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

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

米国

リクエスト

連絡先を取得するには、/v1/addressBooks/{addressBookId}/contacts/{contactId}リソースに対してGETリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

contactId

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

次の例は、連絡先の詳細として、電話番号、コミュニケーション機能プロファイル、WebRTCサービスプロバイダーのいずれかを示しています。

応答本文のプロパティ

プロパティ 説明 型

contact

リクエストされた連絡先。number、alexaCommunicationProfileId、providerContactのいずれかの連絡先タイプが含まれます。

オブジェクト

contact.name

連絡先の名前。
有効な値は 1～50文字の英数字です。

文字列

contact.number

（オプション）連絡先の電話番号。
米国、英国、カナダ（CA）の電話番号をE.164形式で表す必要があります。1つの連絡先に最大3つの電話番号を指定できます。

文字列

contact.alexaCommunicationProfileId

（オプション）ユニットのコミュニケーション機能プロファイルを識別します。
この値は、コミュニケーション機能REST APIリファレンスに記載されているprofileIdと同じです。
amzn1.alexa.communications.profile.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

contact.providerContact

（オプション）WebRTC通話の場合にのみ含まれます。

オブジェクト

contact.providerContact.id

サービスプロバイダーの内部ID。
amzn1.comms.csp.id.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

contactId

連絡先を一意に識別します。
amzn1.alexa.contact.did.{id}というAmazon Common Identifier（ACI）形式で表します。

整数

HTTPステータスコード

ステータス 説明

200 OK

指定されたアドレス帳からの連絡先が応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

指定されたアドレス帳から連絡先のリストを取得します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

連絡先のリストを取得するには、/v1/addressBooks/{addressBookId}/contactsリソースに対してGETリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

maxResults

クエリ

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

整数

✕

nextToken

クエリ

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

文字列

✕

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

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

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

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

応答

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

応答本文の例

{
    "results": [{
            "contactName": "Example Contact Name 1",
            "contactId": "amzn1.alexa.contact.did.1101"
        },
        {
            "contactName": "Example Contact Name 2",
            "contactId": "amzn1.alexa.contact.did.1234"
        },
        {
            "contactName": "Example Contact Name 3",
            "contactId": "amzn1.alexa.contact.did.1235"
        }
    ],
    "paginationContext": {
        "nextToken": "someToken.1"
    }
}

応答本文のプロパティ

プロパティ 説明 型

results

連絡先のリスト。

オブジェクトの配列

results[].contactName

連絡先の名前。
有効な値は 1～50文字の英数字です。

文字列

results[].contactId

連絡先の一意のID。
amzn1.alexa.contact.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

paginationContext

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

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

指定されたアドレス帳からの連絡先のリストが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

連絡先を更新する

アドレス帳に含まれている指定された連絡先のメタデータを更新します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

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

米国

リクエスト

連絡先を更新するには、/v1/addressBooks/{addressBookId}/contacts/{contactId}リソースに対してPUTリクエストを実行します。

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

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

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

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

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

addressBookId

パス

アドレス帳を識別します。
amzn1.alexa.addressbook.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

◯

contactId

パス

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

文字列

◯

access token

ヘッダー

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

文字列

◯

リクエスト本文の例

次の例は、指定したアドレス帳の連絡先を更新するリクエストを示しています。連絡先は、電話番号、コミュニケーション機能プロファイル、WebRTCサービスプロバイダーのいずれかとして定義できます。

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

プロパティ 説明 型 必須

contact

更新する連絡先。number、alexaCommunicationProfileId、providerContactのいずれかの連絡先タイプを指定します。

オブジェクト

◯

contact.name

連絡先の名前。
有効な値は 1～50文字の英数字です。

文字列

◯

contact.number

連絡先の電話番号。
米国、英国、カナダ（CA）の電話番号をE.164形式で表す必要があります。1つの連絡先に最大3つの電話番号を指定できます。

文字列

✕

contact.alexaCommunicationProfileId

ユニットのコミュニケーション機能プロファイルを識別します。
この値は、コミュニケーション機能REST APIリファレンスに記載されているprofileIdと同じです。
amzn1.alexa.communications.profile.did.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

contact.providerContact

WebRTC通話の場合にのみ指定します。

オブジェクト

✕

contact.providerContact.id

サービスプロバイダーの内部ID。
amzn1.comms.csp.id.{id}というAmazon Common Identifier（ACI）形式で表します。

文字列

✕

応答

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

応答本文の例

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

応答本文のプロパティ

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

HTTPステータスコード

ステータス 説明

200 OK

指定されたアドレス帳からの連絡先のリストが応答本文に含まれています。

400 Bad Request

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

401 Unauthorized

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

403 Forbidden

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

404 Not Found

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

429 Too Many Requests

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

500 Server Error

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

503 Service Unavailable

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

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

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