Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

OpenAPI 3.x 기능 제한사항

이 문서에서는 API Gateway에서 OpenAPI 3.x를 사용할 때의 기능 제한사항을 설명합니다.

지원되는 OpenAPI 사양 버전에 대한 자세한 내용은 OpenAPI 개요를 참조하세요.

새로운 OpenAPI 3.x 제한사항

이 섹션에서는 OpenAPI 3.x의 새로운 기능에 대한 제한사항을 설명합니다.

서버

OpenAPI 3.x는 여러 server 객체를 지원하여 호스트와 기본 경로를 정의합니다. 하지만 API Gateway는 x-google-endpoint 확장 프로그램으로 식별되는 단일 서버 객체를 사용하여 서비스를 구성합니다.

여러 서버를 정의할 수 있지만 API Gateway는 x-google-endpoint 확장 프로그램이 포함된 서버만 고려하고 이러한 서버를 하나만 허용합니다. API Gateway의 경우 서버 URL이 필요하지 않으므로 서버를 정의하지 않거나 x-google-endpoint 확장 프로그램이 있는 서버를 하나만 사용할 수 있습니다.

예를 들어 다음 정의는 API Gateway에 유효합니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com

다음 정의는 여러 x-google-endpoint 확장 프로그램을 포함하므로 잘못되었습니다.

servers:
  - url: https://example.com
    x-google-endpoint: {}
  - url: https://example2.com
    x-google-endpoint: {}

다음 정의는 API Gateway에 유효하지만 API Gateway는 서버 객체를 무시합니다.

servers:
  - url: https://example.com

여러 파일에 걸친 서버

여러 OpenAPI 파일을 업로드하고 한 파일에 x-google-endpoint 확장자가 있는 서버가 포함된 경우 모든 파일에 동일한 x-google-endpoint 확장자와 서버 URL의 동일한 호스트로 정의된 서버가 있어야 합니다. 기본 경로는 파일마다 다를 수 있습니다.

상대 URL

API Gateway의 경우 사양에 호스트 이름이 필요하지 않으므로 servers 객체의 상대 URL은 자체적으로 기본 경로로 처리됩니다. 이는 OpenAPI 정의를 호스팅하는 서버에 대해 상대 URL을 확인하는 표준 OpenAPI 동작과 다릅니다. 예를 들어 API Gateway는 url: /v1를 기본 경로로 취급합니다.

기본 경로는 '/'로 시작해야 합니다. API Gateway는 스키마가 없거나 '/'로 시작하여 기본 경로를 나타내지 않는 URL을 거부합니다.

지원되지 않는 확장 프로그램

API Gateway는 OpenAPI 3.x의 x-google-allow 확장 프로그램을 지원하지 않습니다.

파일 크기 한도

API Gateway는 업로드된 OpenAPI 3.x 파일에 대해 총 크기 한도 10MB, 파일 수 한도 50개를 적용합니다.

MCP 제한사항

공개 프리뷰 기간에는 모델 컨텍스트 프로토콜 (MCP) 지원에 다음과 같은 제한사항이 적용됩니다.

도구 수 제한: 고객은 게이트웨이당 최대 1,000개의 MCP 도구로 제한됩니다.
HTTP 메서드: GET, POST, PUT, PATCH, DELETE 작업만 MCP 도구로 노출할 수 있습니다. HEAD, OPTIONS, TRACE는 지원되지 않습니다.
스트리밍: 장기 실행 도구 호출의 서버 전송 이벤트 (SSE) 스트리밍은 지원되지 않습니다.
일괄 요청: JSON-RPC 일괄 배열이 거부됩니다.
멀티모달 페이로드: 도구 응답은 UTF-8 텍스트로 제한됩니다. 바이너리 응답은 지원되지 않습니다.
스테이트리스니스(Statelessness): 구현은 스테이트리스(Stateless)입니다. 세션 식별자(예: MCP-Session-Id)는 사용되거나 유지되지 않습니다.
지원되지 않는 MCP 메서드: resources/*, prompts/*, sampling/*, completion/*, ping, logging/*와 같은 특수 메서드는 지원되지 않으며 JSON-RPC 오류 코드 -32601를 반환합니다.
도구 주석 없음: destructiveHint 또는 readOnlyHint와 같은 힌트는 도구 선언에서 내보내지 않습니다.
CORS 프리플라이트: /mcp 경로의 자동 CORS 프리플라이트 처리 (OPTIONS 요청)는 게이트웨이에서 관리되지 않습니다.
모델 라우팅 상호 배타성: 동일한 API 구성 내에서 MCP와 모델 라우팅을 모두 사용할 수는 없습니다.
지원되지 않는 MCP 응답: HTTP 204 응답과 같이 응답에 빈 본문을 반환하는 작업은 지원되지 않습니다.
스키마 탐색: OpenAPI 사양에서 파생된 복잡한 중첩 객체 스키마는 알려진 구성 처리 제한으로 인해 tools/list 탐색 응답에서 완전히 또는 올바르게 렌더링되지 않을 수 있습니다.
도구 목록 변경 알림 없음: 게이트웨이가 notifications/tools/list_changed를 내보내지 않습니다. 새 API 구성을 배포한 후 클라이언트는 tools/list를 다시 호출해야 합니다. 노출된 MCP 도구 업데이트를 참고하세요.

기존 제한사항

이 섹션에서는 OpenAPI 2.0에서 이월되어 OpenAPI 3.x에도 적용되는 제한사항을 설명합니다.

무시하는 범위

API Gateway는 보안 스키마 객체에 정의된 범위가 있는 OpenAPI 문서를 허용하지만 이러한 범위를 확인하거나 적용하지는 않습니다.

여러 보안 요구사항

API 키 요구사항: API Gateway는 스키마 중 하나가 API 키인 경우 대체 (논리합) 보안 요구사항을 지원하지 않습니다. 하지만 API Gateway는 결합 (논리곱)을 지원하므로 API 키와 OAuth2 토큰을 모두 요구할 수 있습니다.
OAuth2 요구사항: API Gateway는 다양한 OAuth2 보안 스키마에 대한 대체 (논리합) 보안 요구사항을 지원합니다. API Gateway는 추가 보안 요구사항이 API 키가 아닌 한 논리곱 (논리적 AND)을 지원하지 않습니다.
선택적 보안: 빈 보안 요구사항 (- {})을 사용하여 API 키에 대한 보안을 선택사항으로 만들 수 있지만 API 게이트웨이는 OAuth에 대해 이를 지원하지 않습니다.

보안 정의 유효성 검사

API Gateway는 securityDefinitions 섹션에 해당 정의가 없는 보안 요구사항을 사용하는 OpenAPI 3.x 사양을 거부합니다.

URL 경로 템플릿

API Gateway는 전체 경로 세그먼트를 나타내는 URL 경로 템플릿 매개변수만 지원합니다(예: /items/{itemId}). API Gateway는 부분 세그먼트에 해당하는 매개변수(예: /items/prefix_{id}_suffix)를 지원하지 않으며 거부합니다.

매개변수, 스키마, 요청 본문, 유형

API Gateway는 다양한 매개변수 및 유형 정의 (예: required 매개변수 및 배열 형식)가 포함된 OpenAPI 문서를 허용하지만 이를 적용하지는 않습니다. API 게이트웨이는 이러한 정의와 관계없이 수신 요청을 API로 전달합니다.

API Gateway는 요청 매개변수에서 기본 유형만 지원합니다.

외부 유형 참조

API Gateway는 제공된 OpenAPI 문서 외부의 유형에 대한 참조를 지원하지 않습니다. 예를 들어 API 게이트웨이는 외부 URL을 가리키는 $ref를 허용하지 않고 거부합니다.

호스트 주소의 커스텀 포트

API Gateway는 OpenAPI 문서의 servers.url 필드에서 커스텀 포트를 허용하지 않습니다.

YAML 별칭 제한사항

API Gateway에 제출된 OpenAPI 문서에는 YAML 별칭 노드가 최대 200개까지 포함될 수 있습니다.