API 참조 - 직접 회선 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. 클라이언트 애플리케이션과 봇 간에 새 연결을 만들 경우에는 직접 회선 API 3.0을 대신 사용합니다.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

직업 회선 API 1.1을 사용하여 클라이언트 애플리케이션이 봇과 통신하도록 할 수 있습니다.You can enable your client application to communicate with your bot by using Direct Line API 1.1. 직접 회선 API 1.1은 HTTPS를 통해 업계 표준 REST와 JSON을 사용합니다.Direct Line API 1.1 uses industry-standard REST and JSON over HTTPS.

기본 URIBase URI

직접 회선 API 1.1에 액세스하려면 모든 API 요청에 이 기본 URI를 사용합니다.To access Direct Line API 1.1, use this base URI for all API requests:

https://directline.botframework.com

headersHeaders

표준 HTTP 요청 헤더 외에 직접 회선 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. “전달자” 체계나 “BotConnector” 체계를 사용하여 Authorization 헤더를 지정할 수 있습니다.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

클라이언트가 직접 회선 API 요청을 인증하는 데 사용할 수 있는 비밀 또는 토큰을 가져오는 방법에 대한 자세한 내용은 인증을 참조하세요.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 직접 회선 서비스 내에서 내부 서버 오류가 발생했습니다.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

이러한 작업을 사용하여 클라이언트가 단일 대화에 액세스하는 데 사용할 수 있는 토큰을 만들거나 새로 고칩니다.Use these operations to create or refresh a token that a client can use to access a single conversation.

작업(Operation)Operation DescriptionDescription
토큰 생성Generate Token 새 대화에 대한 토큰을 생성합니다.Generate a token for a new conversation.
토큰 새로 고침Refresh Token 토큰을 새로 고칩니다.Refresh a token.

토큰 생성Generate Token

하나의 대화에 유효한 토큰을 생성합니다.Generates a token that is valid for one conversation.

POST /api/tokens/conversation
콘텐츠Content 설명Description
요청 본문Request body 해당 없음n/a
반환Returns 토큰을 나타내는 문자열입니다.A string that represents the token

토큰 새로 고침Refresh Token

토큰을 새로 고칩니다.Refreshes the token.

GET /api/tokens/{conversationId}/renew
콘텐츠Content 설명Description
요청 본문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.

작업(Operation)Operation DescriptionDescription
대화 시작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 설명Description
요청 본문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 설명Description
요청 본문Request body 해당 없음n/a
반환Returns MessageSet 개체.A MessageSet object. 응답에는 watermarkMessageSet 개체의 속성으로 포함됩니다.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 설명Description
요청 본문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). 요청 URI에서 userId 매개 변수를 설정하여 첨부 파일을 보내는 사용자의 ID를 지정합니다.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 설명Description
요청 본문Request body 단일 첨부 파일의 경우 요청 본문을 파일 콘텐츠로 채웁니다.For a single attachment, populate the request body with the file contents. 여러 첨부 파일의 경우 첨부 파일별로 하나의 파트를 포함하고, 필요한 경우 지정된 첨부 파일의 컨테이너로 제공되어야 하는 Message 개체에 대한 하나의 파트를 포함하는 다중 파트 요청 본문을 만듭니다.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

직접 회선 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 DescriptionDescription
idid 문자열string 메시지를 고유하게 식별하는 ID입니다(직접 회선에서 할당됨).ID that uniquely identifies the message (assigned by Direct Line).
conversationIdconversationId 문자열string 대화를 식별하는 ID입니다.ID that identifies the conversation.
createdcreated 문자열string ISO-8601 형식으로 표시된, 메시지가 생성된 날짜 및 시간입니다.Date and time that the message was created, expressed in ISO-8601 format.
fromfrom 문자열string 메시지를 보낸 사람인 사용자를 식별하는 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. 아무것도 제공되지 않은 경우 직접 회선은 사용자 ID를 할당하지만 일반적으로 이로 인해 예기치 않은 동작이 발생합니다.Although Direct Line will assign a user ID if none is supplied, this typically results in unexpected behavior.
texttext 문자열string 사용자가 봇으로 보내거나 봇에서 사용자로 보내는 메시지의 텍스트입니다.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. “http” 또는 “https”로 시작되지 않는 url 속성 값의 경우, 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 속성과 하나 이상의 콘텐츠 속성(예: text, images, attachments 또는 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 DescriptionDescription
messagesmessages Message[]Message[] Message 개체의 배열입니다.Array of Message objects.
watermarkwatermark 문자열string 집합 내 메시지의 최대 워터마크입니다.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 DescriptionDescription
contentTypecontentType 문자열string 첨부 파일에 있는 콘텐츠의 미디어 유형입니다.The media type of the content in the attachment.
urlurl 문자열string 첨부 파일의 콘텐츠에 대한 URL입니다.URL for the content of the attachment.

대화 개체Conversation object

직접 회선 대화를 정의합니다.Defines a Direct Line conversation.

속성Property TypeType DescriptionDescription
conversationIdconversationId 문자열string 지정된 토큰이 유효한 대화를 고유하게 식별하는 ID입니다.ID that uniquely identifies the conversation for which the specified token is valid.
토큰token 문자열string 지정된 대화에 유효한 토큰입니다.Token that is valid for the specified conversation.
expires_inexpires_in numbernumber 토큰이 만료되기 전 시간(초)입니다.Number of seconds until the token expires.

Error 개체Error object

오류를 정의합니다.Defines an error.

속성Property TypeType DescriptionDescription
codecode 문자열string 오류 코드Error code. 다음 값 중 하나입니다. MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.One of these values: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
messagemessage 문자열string 오류에 대한 설명입니다.A description of the error.
statusCodestatusCode numbernumber 상태 코드입니다.Status code.

ErrorMessage 개체ErrorMessage object

표준화된 메시지 오류 페이로드입니다.A standardized message error payload.

속성Property TypeType DescriptionDescription
errorerror 오류Error 오류에 대한 정보를 포함하는 Error 개체입니다.An Error object that contains information about the error.