API 가져오기 제한 사항 및 알려진 문제

적용 대상: 모든 API Management 계층

API를 가져올 때 성공적으로 가져오기 전에 몇 가지 제한 사항이 발생하거나 문제를 식별하고 수정해야 할 수 있습니다. 이 문서에서는 다음에 대해 알아봅니다.

• OpenAPI를 가져오는 동안의 API Management 동작
• OpenAPI 가져오기 제한 사항 및 OpenAPI 내보내기 작동 방식
• WSDL 및 WADL 가져오기에 대한 요구 사항 및 제한 사항

OpenAPI를 가져오는 동안의 API Management

OpenAPI를 가져오는 동안 API Management에서 다음을 수행합니다.

• 특히 필수로 표시된 쿼리 문자열 매개 변수를 확인합니다.
• 기본적으로 필요한 쿼리 문자열 매개 변수를 필수 템플릿 매개 변수로 변환합니다.

사양의 필수 쿼리 매개 변수가 API Management의 쿼리 매개 변수로 변환되도록 하려면 포털에서 API를 만들 때 작업 템플릿에 쿼리 매개 변수 포함 설정을 사용하지 않도록 설정합니다. API - 만들기 또는 업데이트 REST API를 사용하여 API의 translateRequiredQueryParameters 속성을 query로 설정하여 이 작업을 수행할 수도 있습니다.

GET, HEAD 및 OPTIONS 작업의 경우 API Management는 OpenAPI 사양에 정의된 경우 요청 본문 매개 변수를 삭제합니다.

OpenAPI/Swagger 가져오기 제한

OpenAPI 문서를 가져오는 동안 오류가 발생하면 다음 중 하나를 통해 해당 문서의 유효성을 미리 검사했는지 확인합니다.

• Azure Portal에서 디자이너 사용(디자인 > 프런트 엔드 > OpenAPI 사양 편집기) 또는
• 타사 도구(예: Swagger Editor) 사용

일반

URL 템플릿 요구 사항

OpenAPI 사양

지원되는 버전

API Management는 다음 버전만 지원합니다.

• OpenAPI 버전 2
• OpenAPI 버전 3.0.x(3.0.3 버전까지)
• OpenAPI 버전 3.1(가져오기 전용)

크기 제한

지원되는 확장

다음 확장만 지원됩니다.

지원되지 않는 확장

사용자 지정 확장

• 가져올 때 무시됩니다.
• 내보내기를 위해 저장되거나 유지되지 않습니다.

지원되지 않는 정의

API 작업의 인라인 스키마 정의는 지원되지 않습니다. 스키마 정의는 다음과 같습니다.

• API 범위에서 정의됩니다.
• API 작업 요청 또는 응답 범위에서 참조할 수 있습니다.

무시되는 정의

보안 정의는 무시됩니다.

정의 제한

쿼리 매개 변수를 가져올 때 기본 배열 serialization 메서드(style: form, explode: true)만 지원됩니다. OpenAPI 사양의 쿼리 매개 변수에 대한 자세한 내용은 serialization 사양을 참조하세요.

쿠키에 정의된 매개 변수는 지원되지 않습니다. 여전히 정책을 사용하여 쿠키 콘텐츠를 디코딩하고 유효성을 검사할 수 있습니다.

OpenAPI 버전 2

OpenAPI 버전 2 지원은 JSON 형식으로만 제한됩니다.

“Form” 형식 매개 변수는 지원되지 않습니다. 여전히 정책을 사용하여 application/x-www-form-urlencoded 및 application/form-data 페이로드를 디코딩하고 유효성을 검사할 수 있습니다.

OpenAPI 버전 3.x

API Management는 다음 사양 버전을 지원합니다.

• OpenAPI 3.0.3
• OpenAPI 3.1.0(가져오기 전용)

HTTPS URL

• 여러 servers가 지정되면 API Management에서 찾은 첫 번째 HTTPS URL을 사용합니다.
• HTTPS URL이 없으면 서버 URL이 비어 있습니다.

지원됨

• example

지원되지 않음

다음 필드는 OpenAPI 버전 3.0.x 또는 OpenAPI 버전 3.1.x에 포함되어 있지만 지원되지 않습니다.

OpenAPI 가져오기, 업데이트, 내보내기 메커니즘

일반

API Management 서비스에서 내보낸 API 정의는 다음과 같습니다.

• 주로 API Management 서비스에서 호스트되는 API를 호출해야 하는 외부 애플리케이션을 위한 것입니다.
• 동일하거나 다른 API Management 서비스로 가져올 수 없습니다.

다양한 서비스/환경에서 API 정의의 구성 관리는 Git에서 API Management 서비스를 사용하는 방법과 관련된 설명서를 참조하세요.

OpenAPI 가져오기를 통해 새 API 추가

OpenAPI 문서에 있는 각 작업에 대해 다음을 사용하여 새 작업이 만들어집니다.

• operationId로 설정된 Azure 리소스 이름

  • operationId 값이 정규화됩니다.
  • operationId가 지정되지 않으면(없거나, null이거나, 비어 있음) HTTP 메서드와 경로 템플릿을 결합하여 Azure 리소스 이름 값이 생성됩니다.
    • 예: get-foo.

• summary로 설정된 표시 이름

  • summary 값은 다음과 같습니다.
    • 있는 그대로 가져옵니다.
    • 길이는 300자로 제한됩니다.
  • summary이 지정되지 않으면(없거나, null이거나, 비어 있음) 표시 이름 값이 operationId로 설정됩니다.

operationId에 대한 정규화 규칙

• 소문자로 변환합니다.
• 영숫자가 아닌 문자의 각 시퀀스를 단일 대시로 바꿉니다.
  • 예를 들어 GET-/foo/{bar}?buzz={quix}는 get-foo-bar-buzz-quix-로 변환됩니다.
• 양쪽에 있는 대시를 자릅니다.
  • 예를 들어 get-foo-bar-buzz-quix-는 get-foo-bar-buzz-quix가 됩니다.
• 리소스 이름의 최대 한도보다 4자 더 적은 76자에 맞게 자릅니다.
• 필요한 경우 나머지 4자를 -1, -2, ..., -999 형식으로 중복 제거 접미사에 사용합니다.

OpenAPI 가져오기를 통해 기존 API 업데이트

가져오는 동안 기존 API 작업은 다음과 같습니다.

• OpenAPI 문서에서 설명하는 API와 일치하도록 변경합니다.
• operationId 값을 기존 작업의 Azure 리소스 이름과 비교하여 OpenAPI 문서의 작업과 일치시킵니다.
  • 일치 항목이 있으면 기존 작업의 속성이 “현재 위치”에서 업데이트됩니다.
  • 일치 항목이 없으면 다음과 같습니다.
    • HTTP 메서드와 경로 템플릿을 결합하여(예: get-foo) 새 작업이 만들어집니다.
    • 가져오기는 새 작업에 대해 각각 동일한 HTTP 메서드와 경로 템플릿을 사용하여 기존 작업의 정책을 복사하려고 합니다.

일치되지 않은 기존 작업은 모두 삭제됩니다.

가져오기를 더 예측 가능하게 하려면 다음 지침을 따릅니다.

• 모든 작업에 대해 operationId 속성을 지정합니다.
• 초기 가져오기 후에는 operationId를 변경하지 않습니다.
• operationId와 HTTP 메서드 또는 경로 템플릿을 동시에 변경하지 않습니다.

operationId에 대한 정규화 규칙

• 소문자로 변환합니다.
• 영숫자가 아닌 문자의 각 시퀀스를 단일 대시로 바꿉니다.
  • 예를 들어 GET-/foo/{bar}?buzz={quix}는 get-foo-bar-buzz-quix-로 변환됩니다.
• 양쪽에 있는 대시를 자릅니다.
  • 예를 들어 get-foo-bar-buzz-quix-는 get-foo-bar-buzz-quix가 됩니다.
• 리소스 이름의 최대 한도보다 4자 더 적은 76자에 맞게 자릅니다.
• 필요한 경우 나머지 4자를 -1, -2, ..., -999 형식으로 중복 제거 접미사에 사용합니다.

OpenAPI로 API 내보내기

각 작업에 대해 다음이 적용됩니다.

• Azure 리소스 이름은 operationId로 내보냅니다.
• 표시 이름은 summary로 내보냅니다.

operationId의 정규화는 내보내기가 아니라 가져오기에서 수행됩니다.

WSDL

WSDL 파일을 사용하여 SOAP 통과 및 SOAP-REST API를 만들 수 있습니다.

SOAP 바인딩

• "document" 및 "literal" 인코딩 스타일의 SOAP 바인딩만 지원됩니다.
• "rpc" 스타일 또는 SOAP 인코딩은 지원되지 않습니다.

가져오기 및 포함

• wsdl:import, xsd:import 및 xsd:include 지시문은 지원되지 않습니다. 대신 종속성을 하나의 문서로 병합합니다.

• WSDL 파일에서 wsdl:import, xsd:import 및 xsd:include 종속성을 확인하고 병합하는 오픈 소스 도구는 이 GitHub 리포지토리를 참조하세요.

WS-* 사양

WS-* 사양을 통합하는 WSDL 파일은 지원되지 않습니다.

여러 파트가 포함된 메시지

이 메시지 형식은 지원되지 않습니다.

WCF wsHttpBinding

• Windows Communication Foundation을 사용하여 만든 SOAP 서비스는 basicHttpBinding을 사용해야 합니다.
• wsHttpBinding는 지원되지 않습니다.

MTOM

• MTOM을 사용하는 서비스는 작동할 수 있습니다.
• 현재는 공식적으로 지원되지 않습니다.

재귀

• 재귀적으로 정의된 형식은 API Management에서 지원되지 않습니다.
• 예를 들어 자체 배열을 참조합니다.

여러 네임스페이스

여러 네임스페이스는 하나의 스키마에서 사용할 수 있지만, 대상 네임스페이스만 메시지 파트를 정의하는 데 사용할 수 있습니다. 이러한 네임스페이스는 다른 입력 또는 출력 요소를 정의하는 데 사용됩니다.

대상 이외의 네임스페이스는 내보내기에서 유지되지 않습니다. 다른 네임스페이스를 사용하여 메시지 파트를 정의하는 WSDL 문서를 가져올 수 있지만, 모든 메시지 파트는 내보내기에서 WSDL 대상 네임스페이스를 갖습니다.

다중 엔드포인트

WSDL 파일은 하나 이상의 wsdl:service 및 wsdl:port 요소로 여러 서비스 및 엔드포인트(포트)를 정의할 수 있습니다. 그러나 API Management 게이트웨이는 단일 서비스 및 엔드포인트로만 프록시 요청을 가져올 수 있습니다. WSDL 파일에 여러 서비스 또는 엔드포인트가 정의된 경우 wsdlSelector 속성을 사용하여 API를 가져올 때 대상 서비스 이름 및 엔드포인트를 식별합니다.

배열

SOAP-REST 변환은 아래 예제에 표시된 래핑된 배열만 지원합니다.

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

현재, 알려진 WADL 가져오기 문제가 없습니다.