심화 실습 — 필요한 REST API 직접 만들기 (OpenAPI 제작)

목표 — 이미 공개된 API에 얽매이지 않고, 우리 업무에 필요한 API를 직접 정의합니다. 1단계는 Copilot으로 OpenAPI 스펙 작성(호스팅 불필요), 2단계는 실제 배포(선택)입니다. ⏱ 1단계 약 20분 · 2단계는 별도 시간 · 전제: M2-4b 커넥터를 먼저 학습

왜 필요할까

실습 ③은 남이 만든 API를 연결했습니다. 실무에서는 “사내 발주 이력 조회”, “협력사 평가 점수 조회”처럼 우리 회사에만 있는 API가 필요합니다. 그 출발점이 OpenAPI 정의입니다 — 스펙의 description이 곧 도구 설명이 되므로, 정의를 잘 써야 커넥터 품질도 좋아집니다.

1단계 — Copilot으로 OpenAPI 스펙 작성 (호스팅 불필요)

1. M365 Copilot(또는 사용 중인 AI)에 요구 사항을 설명해 스펙 초안을 만듭니다:

사내 발주 이력 조회 API의 OpenAPI 2.0(swagger) JSON을 만들어줘.
- GET /orders : 파라미터 dept(부서), yearFrom, yearTo, keyword(사업명 검색)
- 응답: 사업명, 발주부서, 계약금액, 낙찰사, 결과(성공/유찰) 목록
- operationId·summary·description을 에이전트가 읽고 호출을 판단할 수 있게 구체적으로.
  파라미터마다 description과 형식 예시를 넣어줘. host는 api.example.com으로.

1. 검수하기 — ③에서 배운 기준으로 확인: operationId가 무슨 동작인지 알려 주는가 / description에 “언제 쓰는지 + 무엇을 돌려주는지”가 있는가 / 파라미터에 형식·기본값이 있는가
2. make.powerapps.com → Custom connectors → OpenAPI 파일 가져오기로 가져와서 정의 화면까지 확인합니다 (host가 가상 주소이므로 테스트 호출은 실패하는 것이 정상입니다 — 여기까지가 “정의 품질” 실습입니다)

2단계 (선택·별도) — 실제 배포

• Azure Functions(무료 티어)나 Power Platform 환경에 간단한 HTTP 함수로 배포하면 1단계 스펙의 host만 바꿔 실제로 호출할 수 있습니다
• 사내 시스템이라면: IT 부서에 기존 API의 OpenAPI 문서가 있는지부터 확인 — 있으면 바로 커넥터로 만들 수 있음

💡 도구를 여러 개 제공할 시스템이라면 REST API보다 MCP 서버(M2-4d)가 표준 방식입니다. 조회 API 하나는 커넥터, 도구가 여러 개인 시스템은 MCP — 이 기준을 기억하세요.

마무리 확인

• 요구 사항 설명 → 스펙 생성 → 검수 과정을 한 번 거쳤다
• operationId·description이 “호출 여부를 판단하는 근거”가 되는 이유를 설명할 수 있다
• 커넥터와 MCP 중 무엇을 고를지 기준을 안다

이론: M2-4b. 커넥터 · M2-4 도구로

출처: Custom connectors (MS Learn) · Available tools (MS Learn)