API リファレンス - Direct Line API 3.0
Direct Line API 3.0 を使用することで、クライアント アプリケーションとボットの通信を有効にできます。 Direct Line API 3.0 では、HTTPS で業界標準の REST および JSON を使用します。
基本 URI
Direct Line API 3.0 にアクセスするには、すべての API 要求に対するこちらの基本 URI を使用します:
グローバル ボットの場合は、
https://directline.botframework.com
を使用しますリージョン ボットの場合は、選択したリージョンに応じて次の URI を入力します。
リージョン 基本 URI ヨーロッパ https://europe.directline.botframework.com
インド https://india.directline.botframework.com
ヒント
リージョン ボットにグローバル ベース URI を使用すると、一部の要求が地理的境界を超える可能性があるため、要求が失敗する可能性があります。
ヘッダー
標準 HTTP 要求ヘッダーに加えて、Direct Line API 要求には、要求を発行しているクライアントを認証するシークレットまたはトークンを指定する Authorization
ヘッダーを含める必要があります。 Authorization
ヘッダーは次の形式を使用して指定します。
Authorization: Bearer SECRET_OR_TOKEN
クライアントが Direct Line API 要求を認証するために使用できるシークレットまたはトークンを取得する方法の詳細については、「Authentication」(認証) を参照してください。
HTTP 状態コード
各応答で返される HTTP 状態コード は、対応する要求の結果を示しています。
HTTP 状態コード | 意味 |
---|---|
200 | 要求は成功しました。 |
201 | 要求は成功しました。 |
202 | 要求の処理は受理されました。 |
204 | 要求は成功しましたが、返されたコンテンツはありませんでした。 |
400 | 要求の形式その他が正しくありませんでした。 |
401 | クライアントには要求を行う権限がありません。 多くの場合、この状態コードの原因は、Authorization ヘッダーが見つからないか、形式が正しくないことです。 |
403 | クライアントは要求された操作の実行が許可されていません。 この操作は、次の理由で失敗する可能性があります。
|
404 | 要求されたリソースが見つかりませんでした。 通常、この状態コードは、要求 URI が無効であることを示します。 |
500 | Direct Line サービス内で内部サーバー エラーが発生しました。 |
502 | ボットが利用できないか、ボットからエラーが返されました。 これは一般的なエラー コードです。 |
Note
HTTP 状態コード 101 は WebSocket 接続パス内で使用されます (ただし、多くの場合は WebSocket クライアントによって処理されます)。
エラー
4xx 範囲または 5xx 範囲の HTTP 状態コードを指定する応答では、エラーの情報を提供する ErrorResponse オブジェクトが応答の本文に含まれます。 4xx 範囲のエラー応答を受け取った場合、要求を再送信する前に、ErrorResponse オブジェクトを検査してエラーの原因を識別し、問題を解決してください。
Note
ErrorResponse オブジェクト内の code
プロパティで指定された HTTP 状態コードと値は変わりません。 ErrorResponse オブジェクト内の message
プロパティで指定された値は、時間の経過と共に変更される可能性があります。
次のスニペットは、要求の例と結果のエラー応答を示したものです。
要求
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]
回答
HTTP/1.1 502 Bad Gateway
[other headers]
{
"error": {
"code": "BotRejectedActivity",
"message": "Failed to send activity: bot returned an error"
}
}
トークン操作
クライアントが 1 つの会話にアクセスするために使用できるトークンを作成または更新するには、次の操作を使用します。
操作 | 説明 |
---|---|
トークンの生成 | 新しい会話用のトークンを生成します。 |
トークンの更新 | トークンを更新します。 |
トークンを生成する
1 つの会話で有効なトークンを生成します。
POST /v3/directline/tokens/generate
Content | 説明 |
---|---|
要求本文 | TokenParameters オブジェクト |
返品 | Conversation オブジェクト |
更新トークン
トークンを更新します。
POST /v3/directline/tokens/refresh
Content | 説明 |
---|---|
要求本文 | 該当なし |
返品 | Conversation オブジェクト |
会話操作
ボットとの会話を開いてクライアントとボット間でアクティビティを交換するには、次の操作を使用します。
操作 | 説明 |
---|---|
会話の開始 | ボットと新しい会話を開きます。 |
会話情報の取得 | 既存の会話に関する情報を取得します。 この操作を実行すると、クライアントが会話に再接続するために使用できる、新しい WebSocket ストリーム URL が生成されます。 |
アクティビティの取得 | ボットからアクティビティを取得します。 |
アクティビティの送信 | ボットにアクティビティを送信します。 |
ファイルのアップロードと送信 | ファイルを添付ファイルとしてアップロードして送信します。 |
会話を開始する
ボットと新しい会話を開きます。
POST /v3/directline/conversations
Content | 説明 |
---|---|
要求本文 | TokenParameters オブジェクト |
返品 | Conversation オブジェクト |
会話情報の取得
既存の会話に関する情報を取得し、クライアントが会話に再接続するために使用できる、新しい WebSocket ストリーム URL を生成します。 クライアントによって認識された最新のメッセージを示す必要がある場合は、要求 URI 内に watermark
パラメーターを指定することもできます。
GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Content | 説明 |
---|---|
要求本文 | 該当なし |
返品 | Conversation オブジェクト |
アクティビティの取得
指定された会話用のボットからアクティビティを取得します。 クライアントによって認識された最新のメッセージを示す必要がある場合は、要求 URI 内に watermark
パラメーターを指定することもできます。
GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Content | 説明 |
---|---|
要求本文 | 該当なし |
返品 | ActivitySet オブジェクト。 応答には、ActivitySet オブジェクトのプロパティとして watermark が含まれます。 クライアントは、アクティビティが返らなくなるまで watermark 値を進めることで、入手できるアクティビティをすべて取得する必要があります。 |
アクティビティの送信
ボットにアクティビティを送信します。
POST /v3/directline/conversations/{conversationId}/activities
Content | 説明 |
---|---|
要求本文 | Activity オブジェクト |
返品 | ボットに送信されたアクティビティの ID を指定する id プロパティを格納した ResourceResponse。 |
ファイルのアップロードと送信
ファイルを添付ファイルとしてアップロードして送信します。 添付ファイルを送信しているユーザーの ID を指定するには、要求 URI 内に userId
パラメーターを設定します。
POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Content | 説明 |
---|---|
要求本文 | 1 つの添付ファイルの場合は、要求本文にファイルのコンテンツを設定します。 複数の添付ファイルの場合は、各パートが 1 つの添付ファイルを指定するマルチパートを含む要求本文を作成します。(必要に応じて) 指定された添付ファイルのコンテナーとして機能する Activity オブジェクト用の 1 つのパートを記述することもできます。 詳しくは、「ボットにアクティビティを送信する」をご覧ください。 |
返品 | ボットに送信されたアクティビティの ID を指定する id プロパティを格納した ResourceResponse。 |
Note
アップロードされたファイルは、24 時間後に削除されます。
[スキーマ]
Direct Line 3.0 スキーマには、Bot Framework スキーマによって定義されるすべてのオブジェクトに加え、Direct Line に固有のオブジェクトがいくつか含まれています。
ActivitySet オブジェクト
アクティビティのセットを定義します。
プロパティ | タイプ | 説明 |
---|---|---|
activities | Activity[] | Activity オブジェクトの配列です。 |
watermark | string | セット内のアクティビティの最大ウォーターマークです。 クライアントは、ボットからアクティビティを取得する際、または新しい WebSocket ストリーム URL を生成する際に、watermark 値を使用して、直近に認識したメッセージを示すことができます。 |
Conversation オブジェクト
Direct Line 会話を定義します。
プロパティ | タイプ | 説明 |
---|---|---|
conversationId | string | 指定されたトークンが有効な会話を一意に識別する ID。 |
eTag, | string | HTTP ETag (エンティティ タグ)。 |
expires_in | 数値 | トークンの有効期限が切れるまでの秒数。 |
referenceGrammarId | string | このボットの参照文法の ID。 |
streamUrl | string | 会話のメッセージ ストリームの URL。 |
token | string | 指定された会話で有効なトークン。 |
TokenParameters オブジェクト
トークンを作成するためのパラメーター。
プロパティ | タイプ | 説明 |
---|---|---|
eTag, | string | HTTP ETag (エンティティ タグ)。 |
trustedOrigins | string[] | トークン内に埋め込む信頼された発行元。 |
ユーザー | ChannelAccount | トークン内に埋め込むユーザー アカウント。 |
活動
クライアントが Direct Line を通じてボットから受信した各アクティビティには、次の操作が適用されます。
- 添付ファイル カードは保持されます。
- アップロードされた添付ファイルの URL は、プライベート リンクを使用して非表示にされます。
channelData
プロパティは変更せずに保持されます。
クライアントは、ActivitySet の一部として、ボットから複数のアクティビティを受信することがあります。
クライアントから Direct Line を通じてボットに Activity
を送信するときには、次のことに注意してください。
type
プロパティでは、送信しているアクティビティの種類を指定します (通常はメッセージ)。from
プロパティには、クライアントによって選択されたユーザー ID を指定する必要があります。- 添付ファイルには、既存のリソースの URL や、Direct Line 添付ファイル エンドポイントを通じてアップロードされた URL を含めることができます。
channelData
プロパティは変更せずに保持されます。- JSON にシリアル化されており暗号化されている場合、アクティビティの合計サイズは 256,000 文字以内にする必要があります。 アクティビティは 150K 以下にすることをお勧めします。 さらにデータが必要な場合は、アクティビティを分割するか、添付ファイルを使用することを検討してください。
クライアントでは、要求ごとにアクティビティを 1 つ送信できます。