HTTP Request 노드 — 외부 API 연결하기

HTTP Request 노드 — 외부 API 연결하기

HTTP Request 노드는 워크플로를 외부 API와 웹 서비스에 연결합니다. 데이터를 가져오거나, 웹훅을 보내거나, 파일을 업로드하거나, HTTP 요청을 받아들이는 어떤 서비스와도 통합할 때 사용해요.

출처: 공식문서 — HTTP Request Node

HTTP 메서드

이 노드는 다양한 유형의 연산을 위한 모든 표준 HTTP 메서드를 지원합니다.

데이터 조회

  • GET — 아무것도 수정하지 않고 서버에서 데이터를 가져옵니다. 사용자 프로필 조회, DB 검색, 현재 상태 확인에 씁니다.
  • HEAD — 응답 본문 없이 응답 헤더만 가져옵니다. 리소스 존재 여부 확인이나 메타데이터 얻기에 유용해요.

데이터 제출

  • POST — 서버에 데이터를 보내며, 주로 새 리소스 생성에 씁니다. 폼 제출, 파일 업로드, JSON 페이로드 전송에 적합해요.
  • PUT — 리소스를 생성하거나 완전히 교체합니다. 리소스의 전체 상태를 설정해야 할 때 사용합니다.
  • PATCH — 기존 리소스에 부분 업데이트를 합니다. 특정 필드만 수정하면 될 때 씁니다.

리소스 관리

  • DELETE — 서버에서 리소스를 제거합니다. 파일, 사용자 계정, 또는 제거해야 할 어떤 리소스든 삭제할 때 사용합니다.

설정

URL, 헤더, 쿼리 파라미터, 요청 본문, 인증을 포함한 HTTP 요청의 모든 측면을 구성합니다. 이전 워크플로 노드의 변수는 요청 구성 어디에든 동적으로 삽입할 수 있어요.

변수 치환

워크플로 변수를 이중 중괄호로 참조합니다: {{variable_name}}. Dify는 깊은 객체 접근을 지원하므로 이전 HTTP 응답에서 {{api_response.data.items[0].id}}처럼 중첩 값을 뽑을 수 있습니다.

시크릿(secret) 타입 환경 변수 값은 워크플로 실행 로그와 이 노드의 요청 로그에서 마스킹됩니다.

타임아웃 설정

HTTP 요청은 멈춤을 방지하기 위해 설정 가능한 타임아웃을 가집니다.

  • Connect timeout — 연결을 맺는 최대 시간
  • Read timeout — 응답 데이터를 읽는 최대 시간
  • Write timeout — 요청 데이터를 보내는 최대 시간

타임아웃은 워크플로 성능을 유지하고 리소스 고갈을 방지합니다.

인증

이 노드는 여러 인증 타입을 지원합니다.

No Auth (type: "no-auth") — 인증 헤더를 추가하지 않음

API Key (type: "api-key") — 세 가지 하위 타입

  • Basic (type: "basic") — base64 인코딩으로 Basic Auth 헤더 추가
  • Bearer (type: "bearer") — Authorization: Bearer *** 헤더 추가
  • Custom (type: "custom") — 지정한 이름·값의 커스텀 헤더 추가

요청 본문

API 요구사항에 맞는 적절한 본문 타입을 선택합니다.

  • JSON — 구조화된 데이터용
  • Form Data — 전통적인 웹 폼용
  • Binary — 파일 업로드용
  • Raw Text — 커스텀 콘텐츠 타입용

파일 감지

HTTP Request 노드는 정교한 로직으로 파일 응답을 자동 감지합니다.

  1. Content-Disposition 분석 — attachment disposition이나 filename 파라미터 확인
  2. MIME 타입 평가 — 텍스트와 바이너리를 구분하기 위해 콘텐츠 타입 분석
  3. 콘텐츠 샘플링 — 모호한 타입은 처음 1024바이트를 샘플링해 텍스트 패턴 감지

텍스트 기반 응답(JSON, XML, HTML 등)은 일반 데이터로, 바이너리 콘텐츠는 파일 변수로 처리됩니다.

파일 연산

HTTP Request 노드는 파일 업로드와 다운로드를 매끄럽게 처리합니다.

파일 업로드는 바이너리 요청 본문 옵션을 사용합니다. 이전 노드의 파일 변수를 선택해 문서 저장, 미디어 처리, 백업을 위해 외부 서비스로 파일을 보냅니다.

파일 다운로드는 응답에 파일 콘텐츠가 포함되면 자동 처리됩니다. 다운로드된 파일은 다운스트림 노드에서 사용할 파일 변수로 제공됩니다.

오류 처리와 재시도

외부 서비스에 의존하는 프로덕션 워크플로를 위한 견고한 오류 처리를 구성합니다.

Retry Settings는 설정 가능한 간격(최대 5000ms)으로 실패한 요청을 최대 10번 자동 재시도합니다. 일시적인 네트워크 문제나 서비스 일시 중단을 처리합니다.

Error Handling은 HTTP 요청이 실패할 때 대체 워크플로 경로를 정의해, 외부 API를 사용할 수 없어도 워크플로가 계속 실행되게 합니다.

응답 처리

HTTP 응답은 이후 노드에서 각각 접근 가능한 구조화된 변수가 됩니다.

  • Response Body — API가 반환한 주요 콘텐츠
  • Status Code — 조건 로직을 위한 HTTP 상태
  • Headers — 키-값 쌍의 응답 메타데이터
  • Files — API가 반환한 파일 콘텐츠
  • Size Information — 읽기 쉬운 형식(KB/MB)의 콘텐츠 크기(바이트)

SSL 검증

SSL 인증서 검증은 노드별로 구성할 수 있습니다(ssl_verify 파라미터). 외부 API의 보안은 유지하면서 자체 서명 인증서를 쓰는 내부 서비스에 연결할 수 있어요.

더 알아보기