이 블로그 글에서는 다음을 확인하실 수 있습니다:
- OpenAPI 사양이 무엇인지.
- AI 프레임워크 및 플랫폼에서 도구 정의에 널리 사용되는 이유.
- Bright Data가 AI 에이전트 및 워크플로우 통합을 간소화하기 위해 OpenAPI를 지원하는 방법.
- Bright Data Web Unlocker API의 OpenAPI 사양.
- Bright Data SERP API의 OpenAPI 사양.
- 실제 AI 플랫폼 내에서 이러한 사양들이 작동하는 방식
자, 시작해 보겠습니다!
OpenAPI 사양이란 무엇인가요?
OpenAPI 사양(OAS) 은 RESTful API를 설명하기 위한 언어에 구애받지 않는 개방형 표준입니다. API의 작업, 매개 변수, 응답, 보안 체계 및 기타 특성을 정의하기 위해 구조화된 기계 판독 가능 형식(일반적으로 YAML 또는 JSON)을 제공합니다.
사양에 대한 GitHub 저장소를 살펴보세요!
참고: OpenAPI 사양은 원래 “Swagger 사양”으로 불렸습니다. 따라서 “Bright Data Swagger 사양”을 찾고 계시다면, 바로 이곳이 맞습니다!
많은 AI 솔루션이 도구 정의를 위해 OpenAPI 사양을 사용하는 이유
많은 AI 프레임워크가 도구 정의를 위해 OpenAPI 지원을 채택합니다. 주된 이유는 OpenAPI 사양이 외부 API의 기능을 정확히 기술하는 표준화된 기계가 읽을 수 있는 계약을 제공하기 때문입니다.
이러한 표준화는 세 가지 주요 이점을 제공합니다:
- 상호 운용성과 최소한의 마찰: OpenAPI는 널리 지원되는 표준입니다. 스펙을 제공하면 플랫폼이 API를 자동으로 가져오고, 입력 양식, 호출 및 응답 처리를 생성하며, 자체 툴링에 통합할 수 있습니다.
- 학습 곡선 감소: 비기술 사용자도 문서나 기타 출처에서 OpenAPI 사양을 복사하기만 하면 API를 사용해 도구를 구축할 수 있습니다. 따라서 수동 연결이나 코딩이 필요하지 않으며, 이것이 저코드/노코드 AI 플랫폼에서 OpenAPI 지원이 흔한 이유입니다.
- 유지보수 용이성: 명시적인 API 계약을 통해 업데이트가 간편합니다. API가 진화할 때 도구 정의 내 스펙만 업데이트하면 되므로 유지보수가 크게 단순화되고 대규모 재작성 필요성이 줄어듭니다.
요약하자면, OpenAPI를 통한 도구 정의는 기업용 생태계의 문을 열어줍니다. 여기서 CRM, 데이터 공급자, 내부 API 및 기타 외부 서비스를 AI 에이전트, 파이프라인, 워크플로우 내에서 최소한의 수동 작업으로 안전하게 연결, 문서화 및 유지 관리할 수 있습니다.
Bright Data의 OpenAPI 사양 소개
Bright Data는 웹 데이터 추출, 자동화된 웹 상호 작용, 웹 크롤링 등을 위한 제품 및 서비스 제품군을 제공합니다.
이러한 솔루션은 API(및 노코드 옵션)를 통해 이용 가능하므로, 해당 기능을 지원하는 AI 플랫폼에서 OpenAPI 사양을 사용하여 구성할 수 있습니다.
이 글에서는 가장 중요한 두 가지 Bright Data 도구인
- SERP API: Google, Bing, Yandex와 같은 검색 엔진에서 구조화된 데이터를 자동으로 추출합니다. 프록시 관리, CAPTCHA 해결, JavaScript 렌더링과 같은 복잡한 작업을 처리하여 차단되지 않고 JSON 또는 HTML 형식의 깨끗한 실시간 결과를 받을 수 있게 합니다.
- 웹 언락커 API: 복잡한 안티봇 조치(CAPTCHA, IP 차단, 지문 인식 등)를 우회하여 모든 웹 페이지에서 데이터를 추출합니다. 프록시 관리, 실제 사용자 에뮬레이션, 깨끗한 HTML/JSON/Markdown 응답 전달을 중개하는 역할을 수행합니다.
각 서비스에 대해 YAML 및 JSON 형식의 OpenAPI 3.x 사양과 Swagger Editor에서 테스트하는 예시를 확인할 수 있습니다.
이러한 사양을 바탕으로 웹 스크래핑 API 및 기타 API 엔드포인트를 AI 통합을 위한 OpenAPI 사양으로 변환할 수 있습니다.
참고: 일부 Bright Data 제품은 동일한 API 엔드포인트를 공유하며 요청 본문에 따라 동작이 달라집니다. 단일 OpenAPI 문서에서 동일한 경로와 메서드에 대해 완전히 분리된 두 스펙을 정의할 수 없으므로 별도의 OpenAPI 스펙이 필요합니다. 따라서 SERP API와 Web Unlocker API(동일한 엔드포인트 공유)에 대해 각각 전용 OpenAPI 스펙을 제공할 예정입니다.
웹 언락커 API OpenAPI 사양
Bright Data의 Web Unlocker API에 대한 OpenAPI 사양을 확인하세요.
참고: 자세한 내용은 다음 문서 페이지에서 사용 가능한 인자, 옵션, 인증 방법 등을 확인하세요:
YAML 사양
다음은 Bright Data 웹 언락커 API의 OpenAPI YAML 사양입니다:
openapi: 3.0.4
info:
title: Bright Data 웹 언락커 API
version: 1.0.0
description: |
Bright Data 언락커 API는 봇 방지 조치를 우회하고, 프록시를 관리하며, CAPTCHA를 자동으로 해결하여 웹 데이터 수집을 용이하게 합니다.
[웹 언락커 API 문서](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: Web Unlocker
description: Bright Data 웹 언락커 API와 상호작용하기 위한 작업들.
구성 요소:
보안 체계:
BearerAuth:
유형: http
방식: bearer
베어러 형식: BRIGHT_DATA_API_KEY
경로:
/request:
post:
작업 ID: sendWebUnlockerRequest
요약: 웹 언락커 API 요청 전송
설명: |
Bright Data 웹 언락커 API 영역을 사용하여 웹 언락커 API 요청을 제출합니다.
[웹 언락커 API `/request` 문서](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)
태그:
- 웹 언락커
보안:
- BearerAuth: []
requestBody:
필수: true
내용:
application/json:
스키마:
유형: 객체
필수:
- zone
- url
- format
속성:
zone:
유형: 문자열
설명: 귀하의 웹 언락커 존 이름.
url:
유형: 문자열
설명: 잠금 해제 및 가져올 대상 웹사이트 URL.
예시: https://example.com/products
format:
type: string
설명: |
응답 형식.
허용 값:
- `raw`: 응답을 본문에 즉시 반환합니다.
- `json`: 응답을 구조화된 JSON 객체로 반환합니다.
기본값: raw
method:
유형: 문자열
설명: 대상 URL을 가져올 때 사용되는 HTTP 메서드.
예시: GET
country:
유형: 문자열
설명: |
프록시 위치 국가 코드 (ISO 3166-1 alpha-2 형식).
예시: us
data_format:
유형: 문자열
설명: |
스크랩된 출력 데이터의 형식.
허용 값:
- `markdown`: 페이지 콘텐츠를 마크다운으로 변환.
- `screenshot`: 렌더링된 페이지의 PNG 이미지 캡처.
enum:
- markdown
- screenshot
응답:
"200":
설명: 검색 결과를 포함한 성공적인 응답.
"400":
description: 유효하지 않은 요청 (필수 필드 누락 또는 잘못된 매개변수).
"401":
description: 권한 없음 (잘못된 Bright Data API 키 또는 키 누락).참고:securitySchemes 섹션은 HTTP 베어러 인증을 사용하는 보안 체계를 지정합니다. 구체적으로, 클라이언트는 API 호출 시 Authorization 헤더에 BRIGHT_DATA_API_KEY를 베어러 토큰으로 전송해야 합니다.
동시에 대부분의 AI 플랫폼은 이미 내장된 인증 방식을 포함하고 있어 해당 지정 필드를 무시할 수 있습니다. 그럼에도 명확성과 참조를 위해 OpenAPI 사양에 포함하는 것이 유용합니다.
JSON 사양
다음은 Web Unlocker API의 JSON OpenAPI 사양입니다:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data Web Unlocker API",
"version": "1.0.0",
"description": "Bright Data Unlocker API는 봇 방지 조치를 우회하고, 프록시를 관리하며, CAPTCHA를 자동으로 해결하여 웹 데이터 수집을 용이하게 합니다.\n[웹 언락커 API 문서](https://docs.brightdata.com/scraping-automation/web-unlocker/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
},
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "Web Unlocker",
"description": "Bright Data Web Unlocker API와 상호작용하기 위한 작업들입니다."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendWebUnlockerRequest",
"summary": "웹 언락커 API 요청 전송",
"description": "Bright Data 웹 언락커 API 영역을 사용하여 웹 언락커 API 요청을 제출합니다. nn[웹 언락커 API `/request` 문서](https://docs.brightdata.com/api-reference/rest-api/unlocker/unlock-website)n",
"tags": [
"웹 언락커"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"zone",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "웹 언락커 영역 이름입니다.",
},
"url": {
"type": "string",
"description": "잠금 해제 및 가져올 대상 웹사이트 URL.",
"example": "https://example.com/products"
},
"format": {
"type": "string",
"description": "응답 형식. n허용되는 값: n- `raw`: 응답을 본문에 즉시 반환합니다. n- `json`: 응답을 구조화된 JSON 객체로 반환합니다. n",
"default": "raw"
},
"method": {
"type": "string",
"description": "대상 URL을 가져올 때 사용되는 HTTP 메서드입니다.",
"example": "GET"
},
"country": {
"type": "string",
"description": "프록시 위치 국가 코드 (ISO 3166-1 alpha-2 형식). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "스크랩된 출력 데이터의 형식. 허용되는 값:n- `markdown`: 페이지 콘텐츠를 마크다운으로 변환합니다.n- `screenshot`: 렌더링된 페이지의 PNG 이미지를 캡처합니다.n",
"enum": [
"markdown",
"screenshot"
]
}
}
}
}
}
},
"응답 코드": {
"200": {
"설명": "검색 결과를 포함한 성공적인 응답."
},
"400": {
"설명": "잘못된 요청 (필수 필드 누락 또는 잘못된 매개변수)."
},
"401": {
"description": "권한 없음 (잘못되었거나 누락된 Bright Data API 키)."
}
}
}
}
}
}Swagger Editor에서 테스트하기
OpenAPI 사양을 Swagger Editor에 붙여넣어 테스트하세요:
SERP API OpenAPI 사양
Bright Data의 SERP API에 대한 OpenAPI 사양을 살펴보세요.
참고: 자세한 내용은 다음 문서 페이지에서 인자, 옵션, 인증 방법 등을 확인하세요:
YAML 사양
다음은 SERP API의 OpenAPI YAML 사양입니다:
openapi: 3.0.4
info:
title: Bright Data SERP API
version: 1.0.0
description: |
Bright Data SERP API를 사용하여 검색 엔진 결과를 추출합니다. Google, Bing, Yandex, DuckDuckGo 등 주요 검색 엔진에서 구조화된 데이터를 추출합니다.
자연 검색 결과, 유료 광고, 지역 목록, 쇼핑 결과 및 기타 SERP 기능을 가져옵니다.
[SERP API 문서](https://docs.brightdata.com/scraping-automation/serp-api/introduction)
contact:
name: Bright Data
url:
servers:
- url: https://api.brightdata.com
tags:
- name: SERP
description: Bright Data SERP API 관련 작업.
구성 요소:
보안 체계:
BearerAuth:
유형: http
방식: bearer
베어러 형식: BRIGHT_DATA_API_KEY
경로:
/request:
post:
작업 ID: sendSerpRequest
요약: SERP API 요청 전송
설명: |
Bright Data SERP API 영역을 사용하여 SERP API 요청을 제출합니다.
[SERP API `/request` 문서](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)
tags:
- SERP
security:
- BearerAuth: []
requestBody:
필수: true
내용:
application/json:
스키마:
유형: 객체
필수:
- zone
- url
- format
속성:
zone:
유형: 문자열
설명: SERP API 영역의 이름.
url:
type: string
description: 쿼리할 검색 엔진 URL (예: `https://www.google.com/search?q=<search_query>`).
example: https://www.google.com/search?q=pizza&hl=en&gl=us
format:
type: string
description: |
응답 형식.
허용 값:
- `raw`: 응답을 본문에 즉시 반환합니다.
- `json`: 응답을 구조화된 JSON 객체로 반환합니다.
기본값: raw
열거형:
- raw
- json
country:
유형: 문자열
설명: |
프록시 위치 국가 코드(ISO 3166-1 alpha-2 형식).
예시: us
data_format:
type: string
description: |
SERP 출력 데이터 형식.
허용 값:
- `json`: 유기적, 유료, 지역, 쇼핑, 피처 스니펫을 포함한 구조화된 SERP 결과의 완전히 파싱된 JSON 데이터.
- `markdown`: 마크다운으로 변환된 SERP 콘텐츠.
enum:
- json
- markdown
응답:
"200":
설명: 검색 결과를 포함한 성공적인 응답.
"400":
설명: 잘못된 요청 (필수 필드 누락 또는 잘못된 매개변수).
"401":
description: 권한 없음 (Bright Data API 키가 없거나 잘못됨).JSON 사양
SERP API의 JSON OpenAPI 사양입니다:
{
"openapi": "3.0.4",
"info": {
"title": "Bright Data SERP API",
"version": "1.0.0",
"description": "Bright Data SERP API를 사용하여 검색 엔진 결과를 추출합니다. Google, Bing, Yandex, DuckDuckGo 등 주요 검색 엔진에서 구조화된 데이터를 추출합니다. n자연 검색 결과, 유료 광고, 지역 정보, 쇼핑 결과 및 기타 SERP 기능을 가져옵니다.n[SERP API 문서](https://docs.brightdata.com/scraping-automation/serp-api/introduction)n",
"contact": {
"name": "Bright Data",
"url": ""
}
},
"servers": [
{
"url": "https://api.brightdata.com"
}
],
"tags": [
{
"name": "SERP",
"description": "Bright Data SERP API 관련 작업."
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "BRIGHT_DATA_API_KEY"
}
}
},
"paths": {
"/request": {
"post": {
"operationId": "sendSerpRequest",
"summary": "SERP API 요청 전송",
"description": "Bright Data SERP API 영역을 사용하여 SERP API 요청을 제출합니다. nn[SERP API `/request` 문서](https://docs.brightdata.com/api-reference/rest-api/serp/scrape-serp)n",
"tags": [
"SERP"
],
"security": [
{
"BearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"zone",
"url",
"format"
],
"properties": {
"zone": {
"type": "string",
"description": "SERP API 영역의 이름입니다."
},
"url": {
"type": "string",
"description": "쿼리할 검색 엔진 URL (예: `https://www.google.com/search?q=<search_query>`).",
"example": "https://www.google.com/search?q=pizza&hl=en&gl=us"
},
"format": {
"type": "string",
"description": "응답 형식. 허용되는 값: n- `raw`: 응답을 본문에 즉시 반환합니다. n- `json`: 응답을 구조화된 JSON 객체로 반환합니다. n",
"default": "raw",
"enum": [
"raw",
"json"
]
},
"country": {
"type": "string",
"description": "프록시 위치 국가 코드 (ISO 3166-1 alpha-2 형식). n",
"example": "us"
},
"data_format": {
"type": "string",
"description": "SERP 출력 데이터의 형식. 허용되는 값:n- `json`: 유기적, 유료, 지역, 쇼핑, 피처 스니펫을 포함한 구조화된 SERP 결과를 가진 완전히 파싱된 JSON 데이터.n- `markdown`: Markdown으로 변환된 SERP 콘텐츠. n",
"enum": [
"json",
"markdown"
]
}
}
}
}
}
},
"응답 코드": {
"200": {
"설명": "검색 결과를 포함한 성공적인 응답."
},
"400": {
"설명": "잘못된 요청 (필수 필드 누락 또는 잘못된 매개변수)."
},
"401": {
"description": "권한 없음 (잘못되었거나 누락된 Bright Data API 키)."
}
}
}
}
}
}Swagger Editor에서 테스트하기
이 사양을 테스트하려면 온라인 Swagger Editor에 붙여넣으세요:
Dify에서 도구 통합을 위한 Bright Data OpenAPI 사양 테스트
API를 통해 Bright Data 서비스에 연결하기 위한 위 OpenAPI 사양의 작동 여부를 확인하기 위해 Dify에서 테스트합니다.
구체적으로는 Bright Data SERP API OpenAPI 사양을 테스트할 예정이지만, 이 가이드 섹션을 다른 Web Unlocker API SERP 사양에도 쉽게 적용할 수 있습니다.
Dify는 AI 기반 애플리케이션의 구축, 배포 및 관리를 간소화하는 오픈소스 로우코드 개발 플랫폼입니다. 다양한 기능 중에서도 OpenAPI 사양을 사용하여 맞춤형 도구를 정의할 수 있습니다.
이 기능은 Dify만의 독점적인 것은 아닙니다. 오히려 그 반대입니다. 특히 로우코드/노코드 또는 엔터프라이즈급 솔루션과 같은 다른 많은 AI 에이전트 구축 플랫폼들도 OpenAPI 스펙을 통한 도구 통합을 지원합니다.
다음 가이드에서 OpenAPI 사양을 통한 Bright Data의 추가 통합 방법을 확인하세요:
- Microsoft Copilot Studio의 AI 에이전트에 Bright Data의 SERP API 통합하기
- IBM watsonx의 AI 에이전트에 Bright Data의 SERP API 통합하기
이제 Dify에서 Bright Data OpenAPI 사양을 테스트해 보겠습니다!
필수 조건
이 튜토리얼 섹션을 따라하려면 다음이 필요합니다:
- API 키와 SERP API 영역이 설정된 Bright Data 계정.
- 클라우드 버전을 사용하려면 Dify Cloud 계정 또는 로컬 머신에서 실행 중인 Dify 인스턴스.
공식 가이드를 따라 Bright Data API 키를 생성하세요. SERP API 도구 호출 인증에 필요하므로 안전한 곳에 보관하십시오.
다음으로 Bright Data 문서의 지침에 따라 계정에 SERP API 영역을 설정하세요:
이후 설명에서는 SERP API 영역이 'serp_api'로 설정된 것으로 가정합니다. 예시에서 영역 이름을 본인의 설정과 일치하도록 수정하세요.
단계 #1: 새 사용자 정의 도구 생성
Dify Cloud 계정에 로그인하거나 로컬 인스턴스를 실행하세요. 새 커스텀 툴을 생성하려면 상단 메뉴에서 “Tools” 옵션을 선택하세요:
“도구” 페이지에서 “사용자 정의” 탭으로 이동하세요:
“사용자 정의” 탭에서 “사용자 정의 도구 생성” 카드를 클릭하세요:
다음과 같은 “사용자 정의 도구 생성” 모달이 나타납니다:
좋습니다! 여기에 Bright Data SERP API OpenAPI 사양을 붙여넣으시면 됩니다.
2단계: OpenAPI 사양을 사용하여 SERP API 도구 정의하기
“사용자 정의 도구 만들기” 모달에서 도구에 “SERP API”와 같은 이름을 지정하세요. “스키마” 필드에 Bright Data SERP API용 YAML OpenAPI 사양을 붙여넣으세요.
다음과 같은 화면이 표시됩니다:
OpenAPI 사양에 정의된 내용에 따라 “사용 가능한 도구” 섹션이 자동으로 채워지는 것을 확인할 수 있습니다.
예상대로 대부분의 플랫폼에서는 내장된 방법을 통해 인증을 정의해야 합니다. 이 경우 “인증 방법” 섹션의 톱니바퀴 아이콘을 클릭하세요:
다음과 같이 인증을 구성하세요:
- 인증 유형: “헤더”
- 유형: “Bearer”
- 키: “Authorization”
- 값: Bright Data API 키를 붙여넣기
이 설정은 Authorization 헤더를 통한 인증을 구성하며, 다음과 같이 전송됩니다:
Bearer <YOUR_BRIGHT_DATA_API_KEY>이것이 바로 Bright Data API가 지원하는 인증 방식입니다.
훌륭합니다! SERP API 도구가 이제 올바르게 정의되고 구성되었습니다.
3단계: 도구 테스트
“사용 가능한 도구” 섹션에서 구성된 /request 엔드포인트 행을 찾아 “테스트” 버튼을 클릭하세요:
그러면 “sendSerpRequest 테스트” 모달이 열리며, 여기서 매개변수와 값을 맞춤 설정하여 구성된 도구가 작동하는지 확인할 수 있습니다.
예를 들어, JSON 형식의 기본 응답을 테스트해 보세요. 예상 결과는 Google에서 스크랩한 SERP 페이지를 HTML 형식으로 포함하는 구조화된 JSON 응답입니다(SERP API의 기본 데이터 형식):
“테스트 결과” 섹션으로 스크롤하여 API 응답을 확인하세요. JSON의 body 필드에 예상대로 SERP 페이지의 HTML이 포함된 것을 확인할 수 있습니다:
훌륭합니다! 이 결과는 기대와 일치합니다.
이제 동일한 페이지의 마크다운 버전을 응답 본문에 직접 가져오는 것을 시도해 보세요:
이번에는 응답이 ( format: raw 때문에) 일반 텍스트이며, ( data_format: markdown 덕분에) SERP 데이터를 마크다운 형식으로 포함하고 있음을 확인하세요.LLM(대규모 언어 모델)에 바로 활용할 수 있습니다.
이제 도구가 작동함을 확인했으니(기본 API 호출이 성공했기 때문), 이를 Dify 워크플로우나 AI 에이전트에 통합할 수 있습니다.
자, 이제 OpenAPI 사양으로 정의된 Bright Data 도구가 완벽하게 작동합니다.
결론
이 글에서는 AI 플랫폼과 라이브러리가 도구 정의를 위해 OpenAPI 사양을 허용하는 이유와 Bright Data가 이를 지원하는 방식을 알아보았습니다. 특히 Bright Data의 Web Unlocker 및 SERP API 솔루션에 대한 OpenAPI 사양을 확인했습니다.
이 두 도구를 통합하면 웹 검색 및 RAG, 심층 연구 등 다양한 작업을 위한 웹 데이터 수집이 가능한 복잡한 AI 에이전트를 구축할 수 있습니다. Bright Data의 AI용 API 서비스 전체 제품군을 활용하여 에이전트의 잠재력을 최대한 발휘하세요!
지금 바로 Bright Data 계정을 무료로 생성하고 웹 데이터 수집을 위한 API 통합을 시작하세요!
