다음을 통해 공유

HTTP 요청하기

  • 아티클

Copilot Studio에서 HTTP 요청 노드를 사용하여 외부 REST API를 호출하면 에이전트의 기능을 확장할 수 있습니다. 이 호출은 외부 시스템에서 데이터를 검색하거나 해당 시스템의 데이터를 조작해야 할 때 유용할 수 있습니다.

전제 조건

HTTP 요청 노드 사용

  1. 노드 추가(+)를 선택하고 고급 하위 메뉴를 연 다음 HTTP 요청 전송을 선택합니다.

    고급 메뉴의 HTTP 요청 보내기 옵션 스크린샷.

  2. URL 상자에 호출하려는 API 엔드포인트의 URL을 입력합니다.

  3. 드롭다운에서 적절한 요청 메서드를 선택합니다. GET, POST, PATCH, PUT 및 DELETE 메서드가 지원됩니다.

    완료된 API URL 및 메서드 드롭다운 스크린샷

  4. 노드의 헤더 및 본문 아래에서 편집 버튼를 선택하면 HTTP 요청 속성 창이 열립니다.

  5. 선택적으로 HTTP 요청에 하나 이상의 헤더를 추가할 수 있습니다. 추가 버튼을 선택하여 각 헤더의 키와 값을 추가합니다.

    HTTP 노드에 대한 헤더 키 값 쌍 목록의 스크린샷.

  6. 기본적으로 HTTP 요청 본문에는 아무런 내용도 전송되지 않지만, 본문에 내용을 지정할 수 있습니다.

  7. 노드의 사용 가능한 옵션 중에서 응답 데이터 형식을 선택합니다.

    일반적으로 호출하는 API에 대한 설명서에서 찾을 수 있는 JSON 예시 응답을 제공할 수 있습니다. Power Fx 변수를 생성하여 Power Fx 편집기에서 intellisense 지원을 통해 작성 캔버스의 다른 곳에서 사용할 수 있습니다. 샘플 데이터에서를 선택한 다음 샘플 JSON에서 스키마 가져오기를 선택합니다. 편집기에 샘플 응답을 붙여넣고 확인을 선택하세요.

    샘플 JSON 편집기에서 스키마 가져오기의 스크린샷.

  8. 다음으로 응답 저장에서 새 변수를 생성하거나 기존 변수를 선택하여 HTTP 요청 응답을 저장할 위치를 선택합니다.

HTTP 요청 본문에 콘텐츠 보내기

  1. 노드의 헤더 및 본문 아래에서 편집 버튼를 선택하면 HTTP 요청 속성 창이 열립니다.

  2. 본문에서 적절한 콘텐츠 유형을 선택합니다. 기본적으로 본문은 내용 없음으로 설정됩니다. 즉, 요청 본문에 내용이 없어야 하며, GET 요청에서 가장 일반적으로 사용됩니다. 본문에 콘텐츠를 추가하려면 사용 가능한 옵션 중 하나를 선택하세요.

    본문 콘텐츠 옵션 드롭다운 스크린샷

    • JSON 콘텐츠: JSON 콘텐츠를 사용하면 요청 본문에 JSON 개체를 제공할 수 있습니다. 이 개체는 POST 또는 PUT 요청을 할 때 자주 사용됩니다. 이 옵션을 선택하면 편집기를 사용하여 JSON 콘텐츠를 입력할 수 있습니다.

      Power Fx를 사용하여 JSON 콘텐츠를 지정하면 동적 값과 참조 변수를 포함할 수도 있습니다. JSON 편집 버튼을 선택하고, 수식을 선택한 다음, HTTP 요청이 이루어질 때 JSON으로 변환되는 Power Fx 개체(입력된 기존 JSON이 모두 Power Fx 개체로 변환됨)를 입력합니다.

      본문 콘텐츠 형식에 대해 선택된 JSON 콘텐츠의 스크린샷.

    • 원시 콘텐츠: 원시 콘텐츠를 사용하면 요청 본문에 데이터 문자열을 삽입할 수 있으며, 이 문자열은 지정한 콘텐츠 형식 중 하나일 수 있습니다. 원시 콘텐츠는 다음 예제에 표시된 문자열 콘텐츠와 같은 Power Fx 수식을 사용하여 입력됩니다.

      본문 콘텐츠 형식에 대해 선택된 RAW 콘텐츠의 스크린샷.

오류 처리 및 시간 초과

HTTP 요청 노드에는 HTTP 요청이 실패하거나 오류가 반환되는 상황을 처리하기 위한 여러 가지 옵션이 있습니다.

기본적으로 이 기능은 "오류를 발생시킵니다." 즉, HTTP 요청이 오류를 반환하거나 실행에 실패하면 에이전트가 작동을 중단하고 오류 시스템 토픽를 트리거하여 오류 메시지를 표시합니다.

하지만 오류 처리를 구성하여 오류 시스템 토픽이 발생하지 않도록 할 수 있습니다. 대신 HTTP 상태 코드와 오류 응답 본문을 사용자가 지정한 변수에 채워서 필요에 따라 이러한 변수를 조사하고 토픽이 계속 실행되도록 할 수 있습니다. 이 구성은 특정 HTTP 요청이 실패하더라도 에이전트가 작업을 계속 진행하도록 하려는 시나리오에서 유용합니다.

오류 처리 동작을 구성합니다.

  1. 노드의 헤더 및 본문 아래에서 편집 버튼를 선택하면 HTTP 요청 속성 창이 열립니다.

  2. 오류 처리 드롭다운에서 원하는 동작을 선택하세요.

  3. 오류 발생 시 계속을 선택한 경우 새 변수를 생성하거나 선택기에서 기존 변수를 선택하여 상태 코드 및 오류 응답 본문 변수를 구성합니다.

    상태 코드 및 오류 응답 본문에 대해 지정된 변수를 사용하여 오류 발생 시 계속되도록 구성된 오류 처리 스크린샷.

이 코드 샘플에서 HTTP 요청이 실패하면, 에이전트는 HTTP 상태 코드를 Topic.StatusCode 변수에 저장하고, 응답 본문을 Topic.ErrorResponse 변수에 저장합니다. 에이전트는 토픽에서 다음 단계를 계속 진행합니다.

오류 응답 변수 유형은 모두입니다. 값 노드 구문 분석을 사용하여 이 변수를 Power Fx 레코드로 변환할 수 있습니다.

속성 창에는 밀리초 단위로 값을 허용하는 요청 시간 초과 속성도 포함되어 있습니다. 기본값은 30초이지만 필요한 경우 이 값을 변경할 수 있습니다.