[OpenMetadata] API 서비스 등록
서비스 등록 방법
API Services | OpenMetadata Connector Integration Guide
OpenAPI(Swagger) 명세를 제공하는 RESTful API로부터 메타데이터를 수집할 수 있도록 지원하고 있다.
API 서비스 커넥터가 제공하는 핵심 기능
- 메타데이터 수집 (Metadata Ingestion)
- JSON 파일(OpenAPI Spec)**을 읽어들이는 기능입니다. API가 어떤 엔드포인트를 가지고 있고, 요청/응답 파라미터(
BondEntry,isin등)가 어떤 구조인지 파싱하여 OpenMetadata의 자산(Asset)으로 등록
- JSON 파일(OpenAPI Spec)**을 읽어들이는 기능입니다. API가 어떤 엔드포인트를 가지고 있고, 요청/응답 파라미터(
- 커스텀 통합 (Custom Integration)
- OpenMetadata가 기본적으로 지원하지 않는(예: MySQL, Kafka 처럼 유명하지 않은) 사내 자체 개발 시스템이나 특수 목적의 솔루션이라도, Swagger(OpenAPI) 문서만 있다면 OpenMetadata에 연결할 수 있다는 뜻 (현재 해보려고 하는 부분)
- 유연한 배포 (Flexible Deployment)
- UI 기반: OpenMetadata 웹 화면에서 ‘Add Service’ 버튼을 누르고 URL을 입력해서 수집하는 방식
- CLI 기반: Python 스크립트나 터미널 명령어, 그리고 Airflow 같은 오케스트레이션 도구를 통해 코드로 수집을 자동화하는 방식
직접 등록해보기
현재, raw 수집을 위해서 외부 API를 통해서 채권 약 1만권이 정보를 받아오고 있습니다. 현재, 채권 정보 수집이 데이터 파이프라인의 구축을 하고 있으며, 추후 해당 데이러를 활용할 수 있는 모든 관계자를 위해서 openmetadata에 데이터 정보 등록이 필요합니다.
또한, 파이프라인의 흐름을 읽기 위한 계보 등록을 위해서 API Service 및 Collection, EndPoint를 등록해서 확인할 수 있도록 하는 것이 목표입니다.
현재 상황
현재 보유 중인 API는 단순히 엔드포인트 URL만 존재할 뿐, 메타데이터 수집에 필수적인 OpenAPI(Swagger) 명세서나 JSON Schema가 부재한 상황입니다
OpenMetadata의 API Ingestion(수집) 프로세스는 명세서 URL을 호출하여 그 안에 정의된 요청/응답 모델과 필드 타입 등을 자동으로 파싱하는 구조로 설계되어 있습니다. 따라서 명세서 없이 URL만으로는 API의 내부 데이터 구조를 인식할 수 없어 자동 수집이 불가능합니다.
또한, OpenMetadata는 수많은 필드와 타입을 UI에서 일일이 수기로 정의하여 등록하는 기능을 지원하지 않으므로, 현재로서는 해당 API를 메타데이터 자산으로 적재하는 데 기술적 제약이 따릅니다.
진행 방법
기존 API에 명세서가 존재하지 않아 자동 수집이 불가능했기에, OpenAPI 규격에 맞춘 JSON 파일을 수기로 작성하는 우회 방안을 적용했습니다.
문법 오류를 방지하기 위해 Swagger Editor에 등록하여 테스트를 진행하면서 작성하였고, 최종 파일은 GitHub Gist를 통해 배포하여 OpenMetadata 커넥터가 읽을 수 있는 스키마 URL을 생성했습니다.
OpenAPI 3.0 표준 포맷에 맞춘 JSON 예시
{
"openapi": "3.0.0",
"info": {
"title": "채권 정보 조회 시스템 API",
"description": "이 API 명세서는 OpenMetadata 수집을 위해 수기로 작성되었습니다.\n채권의 기본 정보 및 상세 분석 데이터를 조회하는 엔드포인트를 정의합니다.",
"version": "1.0.0",
"contact": {
"name": "데이터 엔지니어링팀",
"email": "data-team@company.com"
}
},
"servers": [
{
"url": "https://api.bond-system.internal",
"description": "내부 운영(Production) 서버"
}
],
"tags": [
{
"name": "Bonds",
"description": "채권 데이터 조회 및 검색 관련 API"
}
],
"paths": {
"/api/v1/bonds/search": {
"post": {
"tags": [
"Bonds"
],
"summary": "채권 리스트 검색",
"description": "ISIN 코드를 기반으로 채권의 발행 정보, 금리, 상환 스케줄 등 상세 정보를 조회합니다.",
"operationId": "searchBonds",
"requestBody": {
"description": "검색 조건 (ISIN 리스트)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BondSearchRequest"
}
}
}
},
"responses": {
"200": {
"description": "조회 성공",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BondListResponse"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"BondSearchRequest": {
"type": "object",
"properties": {
"isin_list": {
"type": "array",
"description": "조회할 채권의 국제증권식별번호(ISIN) 배열",
"items": {
"type": "string",
"example": "US00033GAB14"
}
}
}
},
"BondListResponse": {
"type": "object",
"properties": {
"total_count": {
"type": "integer",
"description": "검색된 전체 채권 수"
},
"data": {
"type": "array",
"description": "채권 상세 정보 리스트",
"items": {
"$ref": "#/components/schemas/BondDetail"
}
}
}
},
"BondDetail": {
"type": "object",
"description": "개별 채권의 상세 속성 모델",
"properties": {
"isin": {
"type": "string",
"description": "국제증권식별번호 (ISIN)"
},
"ticker": {
"type": "string",
"description": "종목 코드"
},
"coupon_rate": {
"type": "number",
"format": "float",
"description": "표면 이자율 (%)"
},
"maturity_date": {
"type": "string",
"format": "date",
"description": "만기일 (YYYY-MM-DD)"
}
}
}
}
}
}- Swagger 예시
등록 절차
OpenMetadata에 API 서비스 등록하기 (1) – 커넥터 선택
먼저, 구축한 오픈메타데이터 접속 후 [설정들] ⇒ [서비스들] ⇒ [API들] ⇒ [새 서비스 추가 클릭]
커넥터 선택 (왜 REST만 있을까?): 화면을 보면 선택 가능한 커넥터 목록에 REST 딱 하나만 떠 있는 걸 볼 수 있습니다.
OpenMetadata의 API 서비스 연동은 OpenAPI(Swagger) 표준을 따르고 있습니다. 즉, REST라는 이름의 이 커넥터는 특정 툴에 종속되지 않는 만능(Generic) 커넥터입니다.
다음 단계로 고민할 것 없이 REST를 선택하고, 하단의 Next 버튼을 눌러줍니다. 이제 아까 만든 JSON URL을 넣어줄 차례입니다!
OpenMetadata API 서비스 등록하기 (2) – 이름과 설명
REST 커넥터를 선택하고 다음으로 넘어오면, 이제 서비스의 이름(Name)과 설명(Description) 등을 입력하는 폼이 나옵니다.
여기서 그냥 test_api 혹은 api_1 이렇게 적고 넘어가지 말고 네이밍 규칙에 맞게 작성하는 것이 중요합니다. (추후 보여지게 하고 싶은 이름은 display name에서 수정이 가능합니다.)
여기서 정한 이름은 OpenMetadata 전체에서 고유한 식별자(ID) 역할을 하게 되며, 나중에 데이터 리니지(Lineage)가 복잡해졌을 때 이 서비스가 도대체 뭐 하는 녀석인지 구분하는 중요한 이정표가 됩니다.
- 서비스 이름 (Service Name) 이 필드는 시스템 내부에서 사용되는 고유 ID입니다. 한 번 만들면 수정하기 어렵고, URL이나 API 호출 시에도 사용되므로 영문 소문자와 언더스코어(_) 조합을 추천합니다.
- 권장 패턴:
[팀/프로젝트명]_[기능]_[환경] - 예:
viewtrade_api_dev(ViewTrade 연동 API 개발) - 팁: 뒤에
_prod,_dev처럼 환경을 명시해주면, 나중에 운영 데이터와 테스트 데이터가 섞여서 리니지가 꼬이는 대참사를 막을 수 있습니다.
- 권장 패턴:
- 설명 (Description) “이게 무슨 서비스인가요?”라고 누가 물었을 때 대답할 내용을 적습니다. 검색 결과에 노출되므로 핵심 키워드를 포함하는 것이 좋습니다.
- 포함하면 좋은 내용:
- 무엇을: 어떤 데이터를 다루는지 (예: 채권 마스터 정보, 주문 내역)
- 누구를 위해: 주요 사용자가 누구인지 (예: Data팀, 채권팀)
- 어디서: 데이터 원천이 어디인지 (예: 외부 밴더, 사내 DB)
- 포함하면 좋은 내용:
예시:
**[서비스 개요]** VTS(ViewTrade)에서 제공하는 해외 채권 정보를 조회하는 API 서비스입니다. **[주요 데이터]** - 채권 마스터 정보 (ISIN, 발행일, 만기일 등) - 실시간/종가 호가 데이터 **[담당 부서]** 데이터 엔지니어링팀 (문의: data@company.com)OpenMetadata에 API 서비스 등록하기 (3) – 연결 설정 및 테스트
서비스 이름까지 지어줬다면, 이제 가장 중요한 ‘연결 정보(Connection Configuration)’를 설정할 차례입니다.
OpenMetadata가 우리가 만든 API 명세서를 읽어갈 수 있도록 OpenAPI Schema URL 필드에 주소를 입력해 주어야 합니다.
URL 입력 (주의사항!) 아까 GitHub Gist에서 복사해 둔 주소를 여기에 붙여넣습니다.
⚠️ 확인필요 붙여넣으려는 주소가 gist.github.com/… 으로 시작한다면 실패할 수 있습니다. 반드시 gist.githubusercontent.com/… 으로 시작하는 Raw URL인지 확인하세요. (HTML 페이지가 아닌, 순수 JSON 텍스트만 나오는 주소여야 합니다.)
연결 테스트 (Test Connection) URL을 입력했다면 우측 하단의 연결 테스트 버튼을 눌러줍니다. 이 버튼은 단순히 “서버가 살아있나?”만 보는 게 아니라, “입력한 URL에서 유효한 JSON 데이터를 가져올 수 있고, 그 내용이 OpenAPI 규격에 맞는가?”를 검증하는 과정
결과 확인 잠시 기다렸다가 화면 상단에 초록색 알림창과 함께 “연결 테스트가 성공했습니다.” 메시지가 뜬다면 성공입니다!
이 메시지가 떴다는 것은 다음 두 가지가 검증되었다는 뜻입니다.
- 접근성(Accessibility): OpenMetadata가 해당 URL에 접근하여 파일을 다운로드할 수 있음.
- 유효성(Validity): 다운로드한 파일이 깨진 JSON이 아니며, OpenAPI 스펙을 준수하고 있음.
OpenMetadata에 API 서비스 등록하기 (4) – 수집 범위 설정 (Filter Pattern)
연결 테스트를 통과하고 다음 단계로 넘어오면 ‘Default API Collection Filter Pattern’이라는 다소 긴 이름의 설정창을 마주하게 됩니다
이 단계는 쉽게 말해 “API 명세서에 있는 내용을 몽땅 다 가져올래? 아니면 필요한 것만 골라서 가져올래?”를 결정하는 단계입니다.
- API Collection이란? OpenMetadata는 OpenAPI(Swagger)의
Tag를 기준으로 API들을 그룹화하여 ‘Collection’이라는 이름으로 저장합니다.- 예: 우리가 작성한 JSON에서
tags: ["Bonds"]라고 적힌 엔드포인트들은Bonds라는 컬렉션으로 묶입니다.
- 예: 우리가 작성한 JSON에서
- Include vs Exclude (어떻게 골라낼까?) 이 두 필드는 정규표현식(Regex)을 사용하여 수집할 대상을 필터링합니다.
- Include (포함하기 – Whitelist)
- 의미: “여기에 적힌 이름과 매칭되는 컬렉션만 가져와라.”
- 언제 쓰나? 명세서에 수십 개의 태그가 있지만, 나는 딱
Bonds와Market관련 API만 관리하고 싶을 때. - 예시:
Bonds라고 적으면Auth나Admin태그가 붙은 API는 무시하고, 오직Bonds만 수집합니다.
- Exclude (제외하기 – Blacklist)
- 의미: “여기에 적힌 건 빼고, 나머지는 다 가져와라.”
- 언제 쓰나? 대부분 다 필요한데, 내부 테스트용 API나
Deprecated(사용 중단)된 API 그룹만 쏙 빼고 싶을 때. - 예시:
Internal.*라고 적으면Internal_Test,Internal_Dev등으로 시작하는 컬렉션은 수집하지 않습니다.
- Include (포함하기 – Whitelist)
일반적으로는 모든 데이터를 확인할 것이므로, 이 필터들은 공란(Empty)으로 두고 Add 버튼을 눌러 설정을 마칩니다.
'TECH' 카테고리의 다른 글
댓글
댓글 기능은 준비 중입니다.