API 참조 - 직접 회선 API 3.0

직업 회선 API 3.0을 사용하여 클라이언트 애플리케이션이 봇과 통신하도록 할 수 있습니다. 직접 회선 API 3.0은 HTTPS를 통해 업계 표준 REST 및 JSON을 사용합니다.

기본 URI

직접 회선 API 3.0에 액세스하려면 모든 API 요청에 대해 다음 기본 URI 중 하나를 사용합니다.

• 글로벌 봇의 경우 https://directline.botframework.com

• 지역 봇의 경우 선택한 지역에 따라 다음 URI를 입력합니다.

  지역	기본 URI
  유럽	https://europe.directline.botframework.com
  인도	https://india.directline.botframework.com

헤더

표준 HTTP 요청 헤더 외에도 직접 회선 API 요청에는 요청을 발급하는 클라이언트를 인증하기 위한 비밀 또는 토큰을 지정하는 헤더가 포함되어 Authorization 야 합니다. 다음 형식을 사용하여 Authorization 헤더를 지정합니다.

Authorization: Bearer SECRET_OR_TOKEN

클라이언트가 직접 회선 API 요청을 인증하는 데 사용할 수 있는 비밀 또는 토큰을 가져오는 방법에 대한 자세한 내용은 인증을 참조하세요.

HTTP 상태 코드

각 응답과 함께 반환되는 HTTP 상태 코드는 해당 요청의 결과를 나타냅니다.

Errors

4xx 범위 또는 5xx 범위의 HTTP 상태 코드를 지정하는 모든 응답에서 오류 관련 정보를 제공하는 응답 본문에는 ErrorResponse 개체가 포함됩니다. 4xx 범위에서 오류 응답을 수신하는 경우 ErrorResponse 개체를 검사하여 오류의 원인을 확인하고 요청을 다시 제출하기 전에 문제를 해결합니다.

다음 코드 조각은 예제 요청 및 결과 오류 응답을 보여줍니다.

Request

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

Response

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

토큰 작업

이러한 작업을 사용하여 클라이언트가 단일 대화에 액세스하는 데 사용할 수 있는 토큰을 만들거나 새로 고칩니다.

토큰 생성

한 대화에 유효한 토큰을 생성합니다.

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

파일 업로드 및 보내기

파일을 첨부 파일로 업로드하고 보냅니다. userId 요청 URI에서 매개 변수를 설정하여 첨부 파일을 보내는 사용자의 ID를 지정합니다.

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

스키마

Direct Line 3.0 스키마에는 Bot Framework 스키마에서 정의한 모든 개체와 Direct Line과 관련된 일부 개체가 포함됩니다.

ActivitySet 개체

활동 집합을 정의합니다.

대화 개체

직접 회선 대화를 정의합니다.

TokenParameters 개체

토큰을 만들기 위한 매개 변수입니다.

활동

클라이언트가 Direct Line을 통해 봇에서 수신하는 각 활동에 대해:

• 첨부 파일 카드 유지됩니다.
• 업로드된 첨부 파일의 URL은 프라이빗 링크와 함께 숨겨집니다.
• 속성은 channelData 수정 없이 유지됩니다.

클라이언트는 ActivitySet의 일부로 봇에서 여러 활동을 받을 수 있습니다.

클라이언트가 Direct Line을 Activity 통해 봇에 보내는 경우:

• 이 속성은 type 보내는 형식 활동(일반적으로 메시지)을 지정합니다.
• 속성은 from 클라이언트에서 선택한 사용자 ID로 채워져야 합니다.
• 첨부 파일에는 기존 리소스에 대한 URL 또는 직접 회선 첨부 파일 엔드포인트를 통해 업로드된 URL이 포함될 수 있습니다.
• 속성은 channelData 수정 없이 유지됩니다.
• JSON으로 직렬화되고 암호화될 때 활동의 전체 크기는 256K 자를 초과할 수 없습니다. 활동을 150K 미만으로 유지하는 것이 좋습니다. 더 많은 데이터가 필요한 경우 활동을 위로 분할하거나 첨부 파일을 사용하는 것이 좋습니다.

클라이언트는 요청당 단일 작업을 보낼 수 있습니다.

추가 리소스

• Bot Framework 활동 사양