各IDの種類と役割

ここではドコモAIエージェントAPIで利用されているIDについて説明します。

各IDの役割について

Bot ID

Botを区別するためにつけられているIDです。Agentcraft™でエージェントを作成した際に自動で割り当てられます。

Client Secret

Botに接続可能なデバイスを払い出すためのIDです。このIDを用いてデバイスの固有IDを払い出します。Botを紐付けることで発行されます。ドコモAIエージェントAPIを商用利用する際には、このClient Secretごとに課金されます。詳しくは契約の流れをご確認ください。

Device ID

Client Secretによって払い出されたデバイス固有のIDです。デバイスを区別するために用います。
Client Secretを用いない限り、ドコモAIエージェントAPIに接続可能なデバイスを作成することはできません。ドコモAIエージェントAPIマネジメントサイトを利用している場合は、マネジメントサイト上にClientSecretが払い出されておりますので、そちらを利用してDevice IDを払い出してください(※1)。

Device IDはデバイスの識別の役割に加え、Botに接続するユーザを識別するキーや、接続認証時に利用するトークンを払い出す役割も担っています。
Device IDとユーザを紐付けることで、接続時にユーザを識別するキー(Shadow ID)や、接続認証に用いるトークン(DeviceToken)を生成することが可能になります。なお、Device IDは一つにつき、一人のユーザのみに紐付けることができます。

※1. Agentcraft™とトライアル環境を使用してエージェントを開発されている場合、Agentcraft™内の画面からDevice IDの払い出しが可能です。開発やテストでご利用される場合はこちらから払い出したDevice IDをご利用下さい。。

Shadow ID

ユーザを識別すると一時的に払い出される識別子です。ユーザがログインを実施しDeviceIDの紐付けを実施することで、DeviceIDが紐づくBotに対するユーザの識別子として発行されます。

Botとユーザが紐づくことにより、一人のユーザがドコモAIエージェントAPIにつながる複数の種類のデバイスやアプリを保持していても、ユーザが同じClient Secret(=Bot)に紐付けられているデバイス上でユーザを区別することができるようになっています。

ShadowIDはBot単位でユニークとなります。ユーザが最初にBotに紐付けられたデバイスを登録した際に発行され、変化しません。同一ユーザが同一のBotに紐付けられたデバイスを複数登録したとしても、Shadow IDは同一となります。

ただし、同じ種類のBotに紐付けられたデバイスがユーザからすべて削除された場合にはShadow IDは消失し、次にそのBotに紐付けられたデバイスが登録された場合は別のShadow IDが発行されます。Shadow IDはシステム外にユーザを識別する識別子として利用できます。

ログイン方法に関しては、ドコモAIエージェントAPIが標準で用意している認証機構(UDSF,UDSDB)を用いたログインを利用するか、個別にログイン機能を実装する必要があります。標準の認証機構では、dアカウントでのログイン機能をご用意しています(開発時に利用できるトライアル環境に関しては、googleアカウントでのログインも可能です)。詳しくはユーザとDeviceIDの紐付けを参照ください。

Device Token

ユーザがシステムにログインし、デバイスを自分のアカウントに紐付けると、デバイスとユーザ情報を紐付ける役割を持つDevice Tokenが発行可能になります。

ユーザに自分のアカウントにDevice IDの紐づけを完了させた後、つまりShadowIDが生成さた後に、デバイスは自分のDevice IDを利用してAPIに問い合わせることによって、Device TokenおよびRefresh Tokenの発行を一度だけ受けることができるようになります。その後デバイスはそのDevice TokenおよびRefresh Tokenを保持しなければなりません。

Device Tokenはシステムへの接続認証の役割を持ち、以後Device Tokenが、

  1. デバイスが接続するBotの情報
  2. デバイスが接続するBotに対するユーザ
  3. デバイスがAPIに接続可能などうかの認可

の3つの役割を担います。発行に失敗した場合はDevice IDをユーザのアカウントから削除の上、再度登録することで発行できます。

Refresh Token

Device Tokenは1ヶ月の期限をもって利用ができなくなります。この場合はRefresh Tokenを用いてDevice Tokenを更新する必要があります。

Refresh Tokenを用いてDevice Tokenを更新すると、新たにDevice TokenとRefresh Tokenが配布されます。デバイスはこれを保持しなければなりません。

各ID同士の連携について

ドコモAIエージェントAPIで利用されているIDは、以下のように連携されています。