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

아티클
04/24/2024

적용 대상: 모든 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는 이러한 구분을 지원하지 않으므로 전체 URL 템플릿 내에서 매개 변수 이름이 고유해야 합니다. 이름은 대/소문자를 구분하지 않습니다.
정의된 URL 매개 변수	URL 템플릿의 일부여야 합니다.
사용 가능한 원본 파일 URL	상대 서버 URL에 적용됩니다.
`\$ref` 포인터	외부 파일을 참조할 수 없습니다.

OpenAPI 사양

지원되는 버전

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

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

크기 제한

크기 제한	설명
최대 4MB	OpenAPI 사양을 API Management에 인라인으로 가져오는 경우
Azure Resource Manager API 요청 크기	API Management 서비스에서 액세스할 수 있는 위치에 대한 URL을 통해 OpenAPI 문서가 제공되는 경우 Azure 구독 제한을 참조하세요.

지원되는 확장

다음 확장만 지원됩니다.

내선 번호	설명
`x-ms-paths`	URL에서 쿼리 매개 변수로 구분되는 경로를 정의할 수 있습니다. AutoRest 문서에서 설명합니다.
`x-servers`	OpenAPI 2에 대한 OpenAPI 3 `servers` 개체의 백포트입니다.

지원되지 않는 확장

내선 번호	설명
`Recursion`	API Management는 재귀적으로 정의된 정의를 지원하지 않습니다. 예를 들어 자체를 참조하는 스키마입니다.
`Server` 개체	API 작업 수준에서는 지원되지 않습니다.
`Produces` 키워드	API에서 반환되는 MIME 형식을 설명합니다. 지원되지 않습니다.

사용자 지정 확장

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

지원되지 않는 정의

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에 포함되어 있지만 지원되지 않습니다.

Object	필드
OpenAPI	`externalDocs`
정보	`summary`
Components	`responses` `parameters` `examples` `requestBodies` `headers` `securitySchemes` `links` `callbacks`
PathItem	`trace` `servers`
연산	`externalDocs` `callbacks` `security` `servers`
매개 변수	`allowEmptyValue` `style` `explode` `allowReserved`

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 가져오기 문제가 없습니다.

다음을 통해 공유