심화 실습 — 필요한 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이 “호출 판단 근거”가 되는 이유를 설명할 수 있다
• 커넥터 vs MCP 선택 기준을 안다

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

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