Direct Line API 1.1 での認証
重要
この記事では、Direct Line API 1.1 での認証について説明します。 クライアント アプリケーションとボットの間に新しい接続を作成する場合は、代わりに Direct Line API 3.0 を使用します。
クライアントは、Direct Line API 1.1 に対する要求を、Bot Framework Portal の Direct Line チャネル構成ページから取得するシークレットを使用するか、ランタイム時に取得するトークンを使用して認証できます。
各要求の Authorization ヘッダーで、"Bearer" スキームまたは "BotConnector" スキームを使用して、シークレットまたはトークンを指定する必要があります。
Bearer スキーム:
Authorization: Bearer SECRET_OR_TOKEN
BotConnector スキーム:
Authorization: BotConnector SECRET_OR_TOKEN
シークレットとトークン
Direct Line シークレットは、関連付けられているボットに属するすべての会話にアクセスするために使用できるマスター キーです。 シークレットは、トークンを取得するために使用することもできます。 シークレットの有効期限は切れない。
Direct Line トークンは、1 つの会話にアクセスするために使用できるキーです。 トークンには有効期限がありますが、更新できます。
サービス間アプリケーションを作成する場合は、Direct Line API 要求の Authorization ヘッダー内にシークレットを指定することが最も簡単な方法です。 クライアントが Web ブラウザーまたはモバイル アプリで実行されるアプリケーションを記述する場合は、シークレットをトークン (1 つの会話でのみ機能し、更新されない限り有効期限が切れます) と交換し、そのトークンを、Direct Line API 要求の Authorization ヘッダー内に指定できます。 自分にとって最適なセキュリティ モデルを選択してください。
Note
Direct Line クライアント資格情報は、ボットの資格情報とは異なります。 これにより、キーを個別に変更でき、ボットのパスワードを公開せずにクライアント トークンを共有できます。
Direct Line シークレットを取得する
Azure portalのボットのDirect Line チャネル構成ページを使用して、Direct Line シークレットを取得できます。
Direct Line トークンを生成する
単一の会話にアクセスするために使用できるDirect Line トークンを生成するには、まず、Azure portalのDirect Line チャネル構成ページからDirect Line シークレットを取得します。 その後、次の要求を発行して、Direct Line シークレットを Direct Line トークンと交換します。
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer SECRET
この要求の Authorization ヘッダーの SECRET を、Direct Line シークレットの値に置き換えます。
以下のスニペットは、トークン生成要求と応答の例を示しています。
Request
POST https://directline.botframework.com/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Response
要求が成功した場合、応答には 1 つの会話で有効なトークンが含まれます。 トークンの有効期限は 30 分です。 トークンを有効のままにするには、有効期限が切れる前にトークンを更新する必要があります。
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"
トークンの生成と会話の開始
トークンの生成操作 (POST /api/tokens/conversation) と会話の開始操作 (POST /api/conversations) は、どちらの操作も、1 つの会話にアクセスするために使用できる token を返すという点で類似しています。 ただし、会話の開始操作とは異なり、トークンの生成操作は会話を開始したりボットに連絡したりしません。
トークンをクライアントに配布し、クライアントに会話を開始してほしい場合は、トークンの生成操作を使用します。 会話をすぐに開始するつもりの場合は、会話の開始操作を使用します。
Direct Line トークンを更新する
Direct Line トークンは、生成された時点から 30 分間有効であり、有効期限が切れていない限り、無制限に更新できます。 期限切れのトークンは更新できません。 Direct Line トークンを更新するには、次の要求を発行します。
POST https://directline.botframework.com/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED
この要求では、URI の {conversationId} をトークンが有効な会話の ID に置き換え、Authorization ヘッダーの TOKEN_TO_BE_REFRESHED を更新する Direct Line トークンに置き換えます。
以下のスニペットは、トークン更新要求と応答の例を示しています。
Request
POST https://directline.botframework.com/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn
Response
要求が成功した場合、応答には前のトークンと同じ会話で有効な新しいトークンが含まれます。 新しいトークンの有効期限は 30 分です。 新しいトークンを有効のままにするには、有効期限が切れる前にトークンを更新する必要があります。
HTTP/1.1 200 OK
[other headers]
"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"