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 を使用します:

ヒント

リージョン ボットにグローバル ベース 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 クライアントは要求された操作の実行が許可されていません。 この操作は、次の理由で失敗する可能性があります。
  • 無効なトークン: 以前は有効であったが期限切れとなったトークンが要求で使用されている場合は、ErrorResponse オブジェクト内で返された Error の code プロパティが TokenExpired に設定されます。
  • データの境界違反: ボットがリージョン ボットであっても、ベース URI がリージョンではない場合、一部の要求が地理的境界を超える可能性があります。
  • 無効なターゲット リソース: ターゲット ボットまたはサイトが無効であるか、削除されました。
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 つ送信できます。

その他のリソース