다음을 통해 공유

HTTP 요청하기

  • 아티클

중요

Power Virtual Agents 기능 및 특징은 생성 AI에 대한 막대한 투자와 Microsoft Copilot 전반의 향상된 통합에 따라 이제 Microsoft Copilot Studio의 일부가 되었습니다.

문서 및 교육 콘텐츠를 업데이트하는 동안 일부 문서와 스크린샷에서는 Power Virtual Agents을 참조할 수 있습니다.

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

전제 조건

HTTP 요청 노드 사용

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

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

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

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

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

  4. 노드의 헤더 및 본문에서 수정 버튼을 클릭합니다. 이렇게 하면 HTTP 요청 속성 창이 열립니다.

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

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

  6. 기본적으로 HTTP 요청 본문에는 콘텐츠가 전송되지 않지만 본문에서 보낼 콘텐츠를 지정합니다.

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

    강력한 형식의 Power FX 변수를 생성하는 예제 JSON 응답(일반적으로 호출하는 API에 대한 문서에서 찾을 수 있음)을 제공할 수 있습니다. 이는 Power FX 편집기의 intellisense 지원을 통해 저작 캔버스의 다른 곳에서 사용할 수 있습니다. 이렇게 하려면 샘플 데이터에서를 선택한 다음 샘플 JSON에서 스키마 가져오기를 클릭하고 표시된 편집기에 샘플 응답을 붙여넣고 확인을 선택합니다.

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

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

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

  1. 노드의 헤더 및 본문에서 수정 버튼을 클릭합니다. 이렇게 하면 HTTP 요청 속성 창이 열립니다.

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

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

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

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

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

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

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

오류 처리 및 시간 초과

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

기본적으로 이 기능은 "오류 발생"입니다. 이는 HTTP 요청이 오류를 반환하거나 실행에 실패할 경우 Copilot이 해당 작업을 중지하고 오류 시스템 토픽을 트리거하여 오류 메시지를 표시한다는 것을 의미합니다.

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

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

  1. 노드의 헤더 및 본문에서 수정 버튼을 클릭합니다. 이렇게 하면 HTTP 요청 속성 창이 열립니다.

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

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

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

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

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

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