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

ヘッダー

標準の HTTP 要求ヘッダーに加えて、Direct Line API 要求には、要求を発行しているクライアントを認証するためのシークレットまたはトークンを指定するAuthorization ヘッダーが含まれている必要があります。 次の形式を使用して、 Authorization ヘッダーを指定します。

Authorization: Bearer SECRET_OR_TOKEN

クライアントがDirect Line API 要求の認証に使用できるシークレットまたはトークンを取得する方法の詳細については、「認証」を参照してください。

HTTP 状態コード

各応答で返される HTTP 状態コード は、対応する要求の結果を示します。

Errors

4xx 範囲または 5xx 範囲の HTTP 状態コードを指定する応答には、エラーに関する情報を提供する ErrorResponse オブジェクトが応答の本文に含まれます。 4xx の範囲でエラー応答を受け取った場合は、 ErrorResponse オブジェクトを調べてエラーの原因を特定し、要求を再送信する前に問題を解決します。

次のスニペットは、要求の例と結果のエラー応答を示しています。

依頼

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

更新トークン

トークンを更新します。

POST /v3/directline/tokens/refresh

会話操作

これらの操作を使用して、ボットとの会話を開き、クライアントとボットの間でアクティビティを交換します。

会話を始めましょう

ボットとの新しい会話を開きます。

POST /v3/directline/conversations

会話情報を取得する

既存の会話に関する情報を取得し、クライアントが会話への 再接続 に使用できる新しい WebSocket ストリーム URL も生成します。 必要に応じて、要求 URI に watermark パラメーターを指定して、クライアントによって表示される最新のメッセージを示します。

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

アクティビティを取得する

指定した会話のアクティビティをボットから取得します。 必要に応じて、要求 URI に watermark パラメーターを指定して、クライアントによって表示される最新のメッセージを示します。

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

アクティビティの送信

ボットにアクティビティを送信します。

POST /v3/directline/conversations/{conversationId}/activities

ファイルのアップロードと送信

ファイルを添付ファイルとしてアップロードして送信します。 要求 URI で userId パラメーターを設定して、添付ファイルを送信するユーザーの ID を指定します。

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Schema

Direct Line 3.0 スキーマには、Bot Framework スキーマで定義されているすべてのオブジェクトと、Direct Lineに固有のオブジェクトが含まれます。

ActivitySet オブジェクト

一連のアクティビティを定義します。

Conversation オブジェクト

Direct Line会話を定義します。

TokenParameters オブジェクト

トークンを作成するためのパラメーター。

アクティビティ

クライアントがDirect Lineを介してボットから受け取るアクティビティごとに、次の操作を行います。

• 添付ファイル カードは保持されます。
• アップロードされた添付ファイルの URL は、プライベート リンクで非表示になります。
• channelData プロパティは変更せずに保持されます。

クライアントは、ActivitySet の一部としてボットから複数のアクティビティを受信できます。

クライアントがDirect Lineを介してボットにActivityを送信する場合:

• type プロパティは、送信する型アクティビティ (通常はメッセージ) を指定します。
• from プロパティには、クライアントによって選択されたユーザー ID が設定されている必要があります。
• 添付ファイルには、Direct Line添付ファイル エンドポイント経由でアップロードされた既存のリソースまたは URL への URL が含まれている場合があります。
• channelData プロパティは変更せずに保持されます。
• アクティビティの合計サイズ (JSON にシリアル化して暗号化する場合) は、256,000 文字を超えてはなりません。 アクティビティは 150K 以下にすることをお勧めします。 さらにデータが必要な場合は、アクティビティを分割するか、添付ファイルを使用することを検討してください。

クライアントは、要求ごとに 1 つのアクティビティを 送信 できます。

その他のリソース

• アクティビティ プロトコルの仕様