API リファレンス - Direct Line API 1.1

重要

この記事には、Direct Line API 1.1 に関するリファレンス情報が含まれています。 クライアント アプリケーションとボットの間に新しい接続を作成する場合は、代わりに Direct Line API 3.0 を使用します。

Direct Line API 1.1 を使用することで、クライアント アプリケーションとボットの通信を有効にできます。 Direct Line API 1.1 では、HTTPS で業界標準の REST および JSON を使用します。

ベース URI

Direct Line API 1.1 にアクセスするには、すべての API 要求用の次の基本 URI を使用します。

https://directline.botframework.com

ヘッダー

標準 HTTP 要求ヘッダーに加えて、Direct Line API 要求には、要求を発行しているクライアントを認証するシークレットまたはトークンを指定する Authorization ヘッダーを含める必要があります。 Authorization ヘッダーは、"Bearer" スキームまたは "BotConnector" スキームを使用して指定できます。

Bearer スキーム:

Authorization: Bearer SECRET_OR_TOKEN

BotConnector スキーム:

Authorization: BotConnector SECRET_OR_TOKEN

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

HTTP 状態コード

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

HTTP 状態コード	意味
200	要求は成功しました。
204	要求は成功しましたが、返されたコンテンツはありませんでした。
400	要求の形式その他が正しくありませんでした。
401	クライアントは要求を行う権限がありません。 多くの場合、この状態コードの原因は、Authorization ヘッダーが見つからないか、形式が正しくないことです。
403	クライアントは、要求された操作を実行できません。 多くの場合、この状態コードの原因は、Authorization ヘッダーに無効なトークンまたはシークレットが指定されていることです。
404	要求されたリソースが見つかりませんでした。 通常、この状態コードは、要求 URI が無効であることを示します。
500	Direct Line サービス内で内部サーバー エラーが発生しました
502	ボット内でエラーが発生しました。ボットが利用できないか、ボットからエラーが返されました。 これは一般的なエラー コードです。

トークン操作

クライアントが 1 つの会話にアクセスするために使用できるトークンを作成または更新するには、次の操作を使用します。

Operation	説明
トークンの生成	新しい会話用のトークンを生成します。
トークンの更新	トークンを更新します。

トークンの生成

1 つの会話で有効なトークンを生成します。

POST /api/tokens/conversation

コンテンツ	Description
要求本文	該当なし
戻り値	トークンを表す文字列

トークンの更新

トークンを更新します。

GET /api/tokens/{conversationId}/renew

コンテンツ	Description
要求本文	該当なし
戻り値	新しいトークンを表す文字列

会話操作

ボットとの会話を開いてクライアントとボット間でメッセージを交換するには、次の操作を使用します。

Operation	説明
会話の開始	ボットと新しい会話を開きます。
メッセージの取得	ボットからメッセージを受信します。
メッセージの送信	メッセージをボットに送信します。
ファイルのアップロードと送信	ファイルを添付ファイルとしてアップロードして送信します。

会話を開始する

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

POST /api/conversations

コンテンツ	Description
要求本文	該当なし
戻り値	Conversation オブジェクト

メッセージの取得

指定された会話用のボットからメッセージを取得します。 クライアントによって認識された最新のメッセージを示すには、要求 URI 内に watermark パラメーターを設定します。

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}

コンテンツ	Description
要求本文	該当なし
戻り値	MessageSet オブジェクト。 応答には、MessageSet オブジェクトのプロパティとして watermark が含まれます。 クライアントは、メッセージが返らなくなるまで watermark 値を進めることで、入手できるメッセージをすべて取得する必要があります。

メッセージの送信

メッセージをボットに送信します。

POST /api/conversations/{conversationId}/messages

コンテンツ	Description
要求本文	Message オブジェクト
戻り値	応答の本文で返されるデータはありません。 サービスは、メッセージが正常に送信された場合は、HTTP 204 状態コードで応答します。 クライアントは、Get Messages 操作を使用して、送信済みのメッセージを (ボットがクライアントに送信しているメッセージと共に) 取得できます。

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

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

POST /api/conversations/{conversationId}/upload?userId={userId}

コンテンツ	Description
要求本文	1 つの添付ファイルの場合は、要求本文にファイルのコンテンツを設定します。 複数の添付ファイルの場合は、各パートが 1 つの添付ファイルを指定するマルチパートを含む要求本文を作成します。(必要に応じて) 指定された添付ファイルのコンテナーとして機能する Message オブジェクト用の 1 つのパートを記述することもできます。 詳細については、「ボットにアクティビティを送信する」を参照してください。
戻り値	応答の本文で返されるデータはありません。 サービスは、メッセージが正常に送信された場合は、HTTP 204 状態コードで応答します。 クライアントは、Get Messages 操作を使用して、送信済みのメッセージを (ボットがクライアントに送信しているメッセージと共に) 取得できます。

注意

アップロードされたファイルは、24 時間後に削除されます。

スキーマ

Direct Line 1.1 スキーマは、次のオブジェクトを含む Bot Framework v1 スキーマの簡略化されたコピーです。

Message オブジェクト

クライアントがボットに送信するメッセージ、またはボットから受信するメッセージを定義します。

プロパティ	Type	説明
id	string	メッセージを一意に識別する ID (Direct Line によって割り当てられます)。
conversationId	string	会話を識別する ID。
created	string	メッセージが作成された日時。 ISO-8601) 形式で表されます。
from	string	メッセージの送信者であるユーザーを識別する ID。 クライアントは、メッセージを作成するときに、このプロパティを安定したユーザー ID に設定する必要があります。 Direct Line はユーザー ID が指定されない場合はそれを割り当てますが、通常は、これによって予期しない動作が発生します。
text	string	ユーザーからボットに、またはボットからユーザーに送信されるメッセージのテキスト。
channelData	object	チャネル固有のコンテンツを格納するオブジェクト。 一部のチャネルには、添付ファイル スキーマを使用して表現できない追加情報を必要とする機能が用意されています。 そのような場合は、このプロパティを、チャネルのドキュメントで定義されているチャネル固有のコンテンツに設定します。 このデータは、クライアントとボット間で変更されずに送信されます。 このプロパティは、複雑なオブジェクトが設定されるか、空のままにしておく必要があります。 文字列、数値、またはその他の単純型を設定しないでください。
images	string[]	メッセージに含まれているイメージの URL を格納する文字列の配列。 この配列内の文字列は、相対 URL である場合があります。 この配列内の文字列が "http" または "https" で始まらない場合は、文字列の先頭 https://directline.botframework.com に追加して完全な URL を形成します。
attachments	Attachment[]	メッセージに含まれるイメージ以外の添付ファイルを表す Attachment オブジェクトの配列。 配列内の各オブジェクトには、url プロパティと contentType プロパティが格納されます。 クライアントがボットから受信するメッセージでは、url プロパティは、相対 URL を指定している場合があります。 url"http" または "https" で始まらないプロパティ値の場合は、文字列の先頭https://directline.botframework.comに追加して完全な URL を形成します。

次の例は、すべての可能なプロパティを含む Message オブジェクトを示しています。 ほとんどの場合、メッセージを作成する場合、クライアントは プロパティと、少なくとも 1 つのコンテンツ プロパティ (、、、 channelDataなどtext) を指定fromattachmentsするだけで済みます。 images

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

MessageSet オブジェクト

メッセージのセットを定義します。

プロパティ	Type	説明
messages	Message[]	Message オブジェクトの配列。
watermark	string	セット内のメッセージの最大ウォーターマーク。 クライアントは、watermark を使用して、ボットからメッセージを取得したときに認識した最新のメッセージを示すことができます。

Attachment オブジェクト

イメージ以外の添付ファイルを定義します。

プロパティ	Type	説明
contentType	string	添付ファイル内のコンテンツのメディアの種類。
url	string	添付ファイルのコンテンツの URL。

Conversation オブジェクト

Direct Line 会話を定義します。

プロパティ	Type	説明
conversationId	string	指定されたトークンが有効な会話を一意に識別する ID。
token	string	指定された会話で有効なトークン。
expires_in	number	トークンの有効期限が切れるまでの秒数。

エラー オブジェクト

エラーを定義します。

プロパティ	Type	説明
code	string	エラー コード。 次のいずれかの値です:MissingProperty、MalformedData、NotFound、ServiceError、Internal、InvalidRange、NotSupported、NotAllowed、BadCertificate。
message	string	エラーの説明。
statusCode	number	状態コード。

ErrorMessage オブジェクト

標準化されたメッセージ エラー ペイロード。

プロパティ	Type	説明
error	Error	エラーに関する情報を含む Error オブジェクト。