API リファレンス - Direct Line API 3.0API reference - Direct Line API 3.0

Direct Line API 3.0 を使用することで、クライアント アプリケーションとボットの通信を有効にできます。You can enable your client application to communicate with your bot by using Direct Line API 3.0. Direct Line API 3.0 では、HTTPS で業界標準の REST および JSON を使用します。Direct Line API 3.0 uses industry-standard REST and JSON over HTTPS.

ベース URIBase URI

Direct Line API 3.0 にアクセスするには、すべての API 要求用の次の基本 URI を使用します。To access Direct Line API 3.0, use this base URI for all API requests:

https://directline.botframework.com

ヘッダーHeaders

標準 HTTP 要求ヘッダーに加えて、Direct Line API 要求には、要求を発行しているクライアントを認証するシークレットまたはトークンを指定する Authorization ヘッダーを含める必要があります。In addition to the standard HTTP request headers, a Direct Line API request must include an Authorization header that specifies a secret or token to authenticate the client that is issuing the request. Authorization ヘッダーは次の形式を使用して指定します。Specify the Authorization header using this format:

Authorization: Bearer SECRET_OR_TOKEN

クライアントが Direct Line API 要求を認証するために使用できるシークレットまたはトークンを取得する方法の詳細については、「Authentication」(認証) を参照してください。For details about how to obtain a secret or token that your client can use to authenticate its Direct Line API requests, see Authentication.

HTTP 状態コードHTTP status codes

各応答で返される HTTP 状態コード は、対応する要求の結果を示しています。The HTTP status code that is returned with each response indicates the outcome of the corresponding request.

HTTP 状態コードHTTP status code 意味Meaning
200200 要求は成功しました。The request succeeded.
201201 要求は成功しました。The request succeeded.
202202 要求の処理は受理されました。The request has been accepted for processing.
204204 要求は成功しましたが、返されたコンテンツはありませんでした。The request succeeded but no content was returned.
400400 要求の形式その他が正しくありませんでした。The request was malformed or otherwise incorrect.
401401 クライアントは要求を行うことを許可されていません。The client is not authorized to make the request. 多くの場合、この状態コードの原因は、Authorization ヘッダーが見つからないか、形式が正しくないことです。Often this status code occurs because the Authorization header is missing or malformed.
403403 要求された操作の実行がクライアントに許可されていません。The client is not allowed to perform the requested operation. 以前は有効であったが期限切れとなったトークンが要求で指定されている場合は、ErrorResponse オブジェクト内で返された Errorcode プロパティが TokenExpired に設定されます。If the request specified a token that was previously valid but has expired, the code property of the Error that is returned within the ErrorResponse object is set to TokenExpired.
404404 要求されたリソースが見つかりませんでした。The requested resource was not found. 通常、この状態コードは、要求 URI が無効であることを示します。Typically this status code indicates an invalid request URI.
500500 Direct Line サービス内で内部サーバー エラーが発生しました。An internal server error occurred within the Direct Line service.
502502 ボットが利用できないか、ボットからエラーが返されました。The bot is unavailable or returned an error. これは一般的なエラー コードです。This is a common error code.

注意

HTTP 状態コード 101 は WebSocket 接続パス内で使用されます (ただし、多くの場合は WebSocket クライアントによって処理されます)。HTTP status code 101 is used in the WebSocket connection path, although this is likely handled by your WebSocket client.

エラーErrors

4xx 範囲または 5xx 範囲の HTTP 状態コードを指定する応答では、エラーの情報を提供する ErrorResponse オブジェクトが応答の本文に含まれます。Any response that specifies an HTTP status code in the 4xx range or 5xx range will include an ErrorResponse object in the body of the response that provides information about the error. 4xx 範囲のエラー応答を受け取った場合、要求を再送信する前に、ErrorResponse オブジェクトを検査してエラーの原因を識別し、問題を解決してください。If you receive an error response in the 4xx range, inspect the ErrorResponse object to identify the cause of the error and resolve your issue prior to resubmitting the request.

注意

ErrorResponse オブジェクト内の code プロパティで指定された HTTP 状態コードと値は変わりません。HTTP status codes and values specified in the code property inside the ErrorResponse object are stable. ErrorResponse オブジェクト内の message プロパティで指定された値は、時間の経過と共に変更される可能性があります。Values specified in the message property inside the ErrorResponse object may change over time.

次のスニペットは、要求の例と結果のエラー応答を示したものです。The following snippets show an example request and the resulting error response.

RequestRequest

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

ResponseResponse

HTTP/1.1 502 Bad Gateway
[other headers]
{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

トークン操作Token operations

クライアントが 1 つの会話にアクセスするために使用できるトークンを作成または更新するには、次の操作を使用します。Use these operations to create or refresh a token that a client can use to access a single conversation.

OperationOperation 説明Description
トークンの生成Generate Token 新しい会話用のトークンを生成します。Generate a token for a new conversation.
トークンの更新Refresh Token トークンを更新します。Refresh a token.

トークンの生成Generate Token

1 つの会話で有効なトークンを生成します。Generates a token that is valid for one conversation.

POST /v3/directline/tokens/generate
コンテンツContent DescriptionDescription
要求本文Request body TokenParameters オブジェクトA TokenParameters object
戻り値Returns Conversation オブジェクトA Conversation object

トークンの更新Refresh Token

トークンを更新します。Refreshes the token.

POST /v3/directline/tokens/refresh
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns Conversation オブジェクトA Conversation object

会話操作Conversation operations

ボットとの会話を開いてクライアントとボット間でアクティビティを交換するには、次の操作を使用します。Use these operations to open a conversation with your bot and exchange activities between client and bot.

OperationOperation 説明Description
会話の開始Start Conversation ボットと新しい会話を開きます。Opens a new conversation with the bot.
会話情報の取得Get Conversation Information 既存の会話に関する情報を取得します。Gets information about an existing conversation. この操作を実行すると、クライアントが会話に再接続するために使用できる、新しい WebSocket ストリーム URL が生成されます。This operation generates a new WebSocket stream URL that a client may use to reconnect to a conversation.
アクティビティの取得Get Activities ボットからアクティビティを取得します。Retrieves activities from the bot.
アクティビティの送信Send an Activity ボットにアクティビティを送信します。Sends an activity to the bot.
ファイルのアップロードと送信Upload and Send File(s) ファイルを添付ファイルとしてアップロードして送信します。Uploads and sends file(s) as attachment(s).

会話を開始するStart Conversation

ボットと新しい会話を開きます。Opens a new conversation with the bot.

POST /v3/directline/conversations
コンテンツContent DescriptionDescription
要求本文Request body TokenParameters オブジェクトA TokenParameters object
戻り値Returns Conversation オブジェクトA Conversation object

会話情報の取得Get Conversation Information

既存の会話に関する情報を取得し、クライアントが会話に再接続するために使用できる、新しい WebSocket ストリーム URL を生成します。Gets information about an existing conversation and also generates a new WebSocket stream URL that a client may use to reconnect to a conversation. クライアントによって認識された最新のメッセージを示す必要がある場合は、要求 URI 内に watermark パラメーターを指定することもできます。You may optionally supply the watermark parameter in the request URI to indicate the most recent message seen by the client.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns Conversation オブジェクトA Conversation object

アクティビティの取得Get Activities

指定された会話用のボットからアクティビティを取得します。Retrieves activities from the bot for the specified conversation. クライアントによって認識された最新のメッセージを示す必要がある場合は、要求 URI 内に watermark パラメーターを指定することもできます。You may optionally supply the watermark parameter in the request URI to indicate the most recent message seen by the client.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns ActivitySet オブジェクト。An ActivitySet object. 応答には、ActivitySet オブジェクトのプロパティとして watermark が含まれます。The response contains watermark as a property of the ActivitySet object. クライアントは、アクティビティが返らなくなるまで watermark 値を進めることで、入手できるアクティビティをすべて取得する必要があります。Clients should page through the available activities by advancing the watermark value until no activities are returned.

アクティビティの送信Send an Activity

ボットにアクティビティを送信します。Sends an activity to the bot.

POST /v3/directline/conversations/{conversationId}/activities
コンテンツContent DescriptionDescription
要求本文Request body Activity オブジェクトAn Activity object
戻り値Returns ボットに送信されたアクティビティの ID を指定する id プロパティを格納した ResourceResponseA ResourceResponse that contains an id property which specifies the ID of the Activity that was sent to the bot.

ファイルのアップロードと送信Upload and Send File(s)

ファイルを添付ファイルとしてアップロードして送信します。Uploads and sends file(s) as attachment(s). 添付ファイルを送信しているユーザーの ID を指定するには、要求 URI 内に userId パラメーターを設定します。Set the userId parameter in the request URI to specify the ID of the user that is sending the attachment(s).

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
コンテンツContent DescriptionDescription
要求本文Request body 1 つの添付ファイルの場合は、要求本文にファイルのコンテンツを設定します。For a single attachment, populate the request body with the file contents. 複数の添付ファイルの場合は、各パートが 1 つの添付ファイルを指定するマルチパートを含む要求本文を作成します。(必要に応じて) 指定された添付ファイルのコンテナーとして機能する Activity オブジェクト用の 1 つのパートを記述することもできます。For multiple attachments, create a multipart request body that contains one part for each attachment, and also (optionally) one part for the Activity object that should serve as the container for the specified attachment(s). 詳しくは、「ボットにアクティビティを送信する」をご覧ください。For more information, see Send an activity to the bot.
戻り値Returns ボットに送信されたアクティビティの ID を指定する id プロパティを格納した ResourceResponseA ResourceResponse that contains an id property which specifies the ID of the Activity that was sent to the bot.

注意

アップロードされたファイルは、24 時間後に削除されます。Uploaded files are deleted after 24 hours.

スキーマSchema

Direct Line 3.0 スキーマには、Bot Framework スキーマによって定義されるすべてのオブジェクトに加え、Direct Line に固有のオブジェクトがいくつか含まれています。The Direct Line 3.0 schema includes all of the objects that are defined by the Bot Framework schema as well as some objects that are specific to Direct Line.

ActivitySet オブジェクトActivitySet object

アクティビティのセットを定義します。Defines a set of activities.

プロパティProperty TypeType 説明Description
activitiesactivities Activity[]Activity[] Activity オブジェクトの配列です。Array of Activity objects.
watermarkwatermark stringstring セット内のアクティビティの最大ウォーターマークです。Maximum watermark of activities within the set. クライアントは、ボットからアクティビティを取得する際、または新しい WebSocket ストリーム URL を生成する際に、watermark 値を使用して、直近に認識したメッセージを示すことができます。A client may use the watermark value to indicate the most recent message it has seen either when retrieving activities from the bot or when generating a new WebSocket stream URL.

Conversation オブジェクトConversation object

Direct Line 会話を定義します。Defines a Direct Line conversation.

プロパティProperty TypeType 説明Description
conversationIdconversationId stringstring 指定されたトークンが有効な会話を一意に識別する ID。ID that uniquely identifies the conversation for which the specified token is valid.
eTageTag stringstring HTTP ETag (エンティティ タグ)。An HTTP ETag (entity tag).
expires_inexpires_in numbernumber トークンの有効期限が切れるまでの秒数。Number of seconds until the token expires.
referenceGrammarIdreferenceGrammarId stringstring このボットの参照文法の ID。ID for the reference grammar for this bot.
streamUrlstreamUrl stringstring 会話のメッセージ ストリームの URL。URL for the conversation's message stream.
tokentoken stringstring 指定された会話で有効なトークン。Token that is valid for the specified conversation.

TokenParameters オブジェクトTokenParameters object

トークンを作成するためのパラメーター。Parameters for creating a token.

プロパティProperty TypeType 説明Description
eTageTag stringstring HTTP ETag (エンティティ タグ)。An HTTP ETag (entity tag).
trustedOriginstrustedOrigins string[]string[] トークン内に埋め込む信頼された発行元。Trusted origins to embed within the token.
useruser ChannelAccountChannelAccount トークン内に埋め込むユーザー アカウント。User account to embed within the token.

ActivitiesActivities

クライアントが Direct Line を通じてボットから受信した各Activityには、次の操作が適用されます。For each Activity that a client receives from a bot via Direct Line:

  • 添付ファイル カードは保持されます。Attachment cards are preserved.
  • アップロードされた添付ファイルの URL は、プライベート リンクを使用して非表示にされます。URLs for uploaded attachments are hidden with a private link.
  • channelData プロパティは変更せずに保持されます。The channelData property is preserved without modification.

クライアントは、ActivitySet の一部として、ボットから複数のアクティビティを受信することがあります。Clients may receive multiple activities from the bot as part of an ActivitySet.

クライアントから Direct Line を通じてボットに Activity を送信するときには、次のことに注意してください。When a client sends an Activity to a bot via Direct Line:

  • type プロパティでは、送信するアクティビティの種類を指定します (通常は メッセージ)。The type property specifies the type activity it is sending (typically message).
  • from プロパティには、クライアントによって選択されたユーザー ID を指定する必要があります。The from property must be populated with a user ID, chosen by the client.
  • 添付ファイルには、既存のリソースの URL や、Direct Line 添付ファイル エンドポイントを通じてアップロードされた URL を含めることができます。Attachments may contain URLs to existing resources or URLs uploaded through the Direct Line attachment endpoint.
  • channelData プロパティは変更せずに保持されます。The channelData property is preserved without modification.
  • JSON にシリアル化されており暗号化されている場合、アクティビティの合計サイズは 256,000 文字以内にする必要があります。The total size of the activity, when serialized to JSON and encrypted, must not exceed 256K characters. そのため、アクティビティを 150,000 未満に抑えることをお勧めします。Therefore it is recommended that activities are kept under 150K. さらにデータが必要な場合、アクティビティを複数に分割するか、添付ファイルを使用することを検討してください。If more data is needed consider breaking the activity into multiple and/or consider using attachments.

クライアントでは、要求ごとにアクティビティを 1 つ送信できます。Clients may send a single activity per request.

その他のリソースAdditional resources