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

重要

この記事には、Direct Line API 1.1 に関するリファレンス情報が含まれています。This article contains reference information for Direct Line API 1.1. クライアント アプリケーションとボットの間の新しい接続を作成する場合は、代わりに Direct Line API 3.0 を使用します。If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

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

ベース URIBase URI

Direct Line API 1.1 にアクセスするには、すべての API 要求用の次の基本 URI を使用します。To access Direct Line API 1.1, 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 ヘッダーは、"Bearer" スキームまたは "BotConnector" スキームを使用して指定できます。You can specify the Authorization header using either the "Bearer" scheme or the "BotConnector" scheme.

Bearer スキーム:Bearer scheme:

Authorization: Bearer SECRET_OR_TOKEN

BotConnector スキーム:BotConnector scheme:

Authorization: BotConnector 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.
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. 多くの場合、この状態コードの原因は、Authorization ヘッダーに無効なトークンまたはシークレットが指定されていることです。Often this status code occurs because the Authorization header specifies an invalid token or secret.
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 ボット内でエラーが発生しました。ボットが利用できないか、ボットからエラーが返されました。A failure occurred within the bot; the bot is unavailable or returned an error. これは一般的なエラー コードです。This is a common error code.

トークン操作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 /api/tokens/conversation
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns トークンを表す文字列A string that represents the token

トークンの更新Refresh Token

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

GET /api/tokens/{conversationId}/renew
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns 新しいトークンを表す文字列A string that represents the new token

会話操作Conversation operations

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

OperationOperation 説明Description
会話の開始Start Conversation ボットと新しい会話を開きます。Opens a new conversation with the bot.
メッセージの取得Get Messages ボットからメッセージを受信します。Retrieves messages from the bot.
メッセージの送信Send a Message メッセージをボットに送信します。Sends a message 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 /api/conversations
コンテンツContent DescriptionDescription
要求本文Request body 該当なしn/a
戻り値Returns Conversation オブジェクトA Conversation object

メッセージの取得Get Messages

指定された会話用のボットからメッセージを取得します。Retrieves messages from the bot for the specified conversation. クライアントによって認識された最新のメッセージを示すには、要求 URI 内に watermark パラメーターを設定します。Set the watermark parameter in the request URI to indicate the most recent message seen by the client.

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

メッセージの送信Send a Message

メッセージをボットに送信します。Sends a message to the bot.

POST /api/conversations/{conversationId}/messages
コンテンツContent DescriptionDescription
要求本文Request body Message オブジェクトA Message object
戻り値Returns 応答の本文で返されるデータはありません。No data is returned in body of the response. サービスは、メッセージが正常に送信された場合は、HTTP 204 状態コードで応答します。The service responds with an HTTP 204 status code if the message was sent successfully. クライアントは、Get Messages 操作を使用して、送信済みのメッセージを (ボットがクライアントに送信しているメッセージと共に) 取得できます。The client may obtain its sent message (along with any messages that the bot has sent to the client) by using the Get Messages operation.

ファイルのアップロードと送信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 attachments.

POST /api/conversations/{conversationId}/upload?userId={userId}
コンテンツContent DescriptionDescription
要求本文Request body 1 つの添付ファイルの場合は、要求本文にファイルのコンテンツを設定します。For a single attachment, populate the request body with the file contents. 複数の添付ファイルの場合は、各パートが 1 つの添付ファイルを指定するマルチパートを含む要求本文を作成します。(必要に応じて) 指定された添付ファイルのコンテナーとして機能する Message オブジェクト用の 1 つのパートを記述することもできます。For multiple attachments, create a multipart request body that contains one part for each attachment, and also (optionally) one part for the Message object that should serve as the container for the specified attachment(s). 詳細については、「ボットにアクティビティを送信する」を参照してください。For more information, see Send a message to the bot.
戻り値Returns 応答の本文で返されるデータはありません。No data is returned in body of the response. サービスは、メッセージが正常に送信された場合は、HTTP 204 状態コードで応答します。The service responds with an HTTP 204 status code if the message was sent successfully. クライアントは、Get Messages 操作を使用して、送信済みのメッセージを (ボットがクライアントに送信しているメッセージと共に) 取得できます。The client may obtain its sent message (along with any messages that the bot has sent to the client) by using the Get Messages operation.

注意

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

スキーマSchema

Direct Line 1.1 スキーマは、次のオブジェクトを含む Bot Framework v1 スキーマの簡略化されたコピーです。Direct Line 1.1 schema is a simplified copy of the Bot Framework v1 schema that includes the following objects.

Message オブジェクトMessage object

クライアントがボットに送信するメッセージ、またはボットから受信するメッセージを定義します。Defines a message that a client sends to a bot or receives from a bot.

プロパティProperty TypeType 説明Description
idid stringstring メッセージを一意に識別する ID (Direct Line によって割り当てられます)。ID that uniquely identifies the message (assigned by Direct Line).
conversationIdconversationId stringstring 会話を識別する ID。ID that identifies the conversation.
createdcreated stringstring メッセージの作成日時。ISO-8601 で表わされます。Date and time that the message was created, expressed in ISO-8601 format.
fromfrom stringstring メッセージの送信者であるユーザーを識別する ID。ID that identifies the user that is the sender of the message. クライアントは、メッセージを作成するときに、このプロパティを安定したユーザー ID に設定する必要があります。When creating a message, clients should set this property to a stable user ID. Direct Line はユーザー ID が指定されない場合はそれを割り当てますが、通常は、これによって予期しない動作が発生します。Although Direct Line will assign a user ID if none is supplied, this typically results in unexpected behavior.
texttext stringstring ユーザーからボットに、またはボットからユーザーに送信されるメッセージのテキスト。Text of the message that is sent from user to bot or bot to user.
channelDatachannelData objectobject チャネル固有のコンテンツを格納するオブジェクト。An object that contains channel-specific content. 一部のチャネルには、添付ファイル スキーマでは表現できない追加情報を必要とする機能があります。Some channels provide features that require additional information that cannot be represented using the attachment schema. そのような場合は、このプロパティを、チャネルのドキュメントで定義されているチャネル固有のコンテンツに設定します。For those cases, set this property to the channel-specific content as defined in the channel's documentation. このデータは、クライアントとボット間で変更されずに送信されます。This data is sent unmodified between client and bot. このプロパティは、複雑なオブジェクトが設定されるか、空のままにしておく必要があります。This property must either be set to a complex object or left empty. 文字列、数値、またはその他の単純型を設定しないでください。Do not set it to a string, number, or other simple type.
imagesimages string[]string[] メッセージに含まれているイメージの URL を格納する文字列の配列。Array of strings that contains the URL(s) for the image(s) that the message contains. この配列内の文字列は、相対 URL である場合があります。In some cases, strings in this array may be relative URLs. この配列内の任意の文字列が "http" または "https" で始まっていない場合は、文字列の前に https://directline.botframework.com を追加して、完全な URL 形式にします。If any string in this array does not begin with either "http" or "https", prepend https://directline.botframework.com to the string to form the complete URL.
attachmentsattachments Attachment[]Attachment[] メッセージに含まれるイメージ以外の添付ファイルを表す Attachment オブジェクトの配列。Array of Attachment objects that represent the non-image attachments that the message contains. 配列内の各オブジェクトには、url プロパティと contentType プロパティが格納されます。Each object in the array contains a url property and a contentType property. クライアントがボットから受信するメッセージでは、url プロパティは、相対 URL を指定している場合があります。In messages that a client receives from a bot, the url property may sometimes specify a relative URL. url プロパティの値が "http" または "https" で始まっていない場合は、文字列の前に https://directline.botframework.com を追加して、完全な URL 形式にします。For any url property value that does not begin with either "http" or "https", prepend https://directline.botframework.com to the string to form the complete URL.

次の例は、すべての可能なプロパティを含む Message オブジェクトを示しています。The following example shows a Message object that contains all possible properties. ほとんどの場合、メッセージを作成するときに、クライアントが指定する必要があるのは、from プロパティと少なくとも 1 つのコンテンツ プロパティ (例: textimagesattachments、またはchannelData) だけです。In most cases when creating a message, the client only needs to supply the from property and at least one content property (e.g., text, images, attachments, or channelData).

{
    "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 オブジェクトMessageSet object

メッセージのセットを定義します。Defines a set of messages.

プロパティProperty TypeType 説明Description
messagesmessages Message[]Message[] Message オブジェクトの配列。Array of Message objects.
watermarkwatermark stringstring セット内のメッセージの最大ウォーターマーク。Maximum watermark of messages within the set. クライアントは、watermark を使用して、ボットからメッセージを取得したときに認識した最新のメッセージを示すことができます。A client may use the watermark value to indicate the most recent message it has seen when retrieving messages from the bot.

Attachment オブジェクトAttachment object

イメージ以外の添付ファイルを定義します。Defines a non-image attachment.

プロパティProperty TypeType 説明Description
contentTypecontentType stringstring 添付ファイル内のコンテンツのメディアの種類。The media type of the content in the attachment.
urlurl stringstring 添付ファイルのコンテンツの URL。URL for the content of the attachment.

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.
tokentoken stringstring 指定された会話で有効なトークン。Token that is valid for the specified conversation.
expires_inexpires_in numbernumber トークンの有効期限が切れるまでの秒数。Number of seconds until the token expires.

エラー オブジェクトError object

エラーを定義します。Defines an error.

プロパティProperty TypeType 説明Description
codecode stringstring エラー コード。Error code. 次のいずれかの値です:MissingPropertyMalformedDataNotFoundServiceErrorInternalInvalidRangeNotSupportedNotAllowedBadCertificateOne of these values: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
messagemessage stringstring エラーの説明。A description of the error.
statusCodestatusCode numbernumber 状態コード。Status code.

ErrorMessage オブジェクトErrorMessage object

標準化されたメッセージ エラー ペイロード。A standardized message error payload.

プロパティProperty TypeType 説明Description
errorerror ErrorError エラーに関する情報を含む Error オブジェクト。An Error object that contains information about the error.