Udostępnij za pośrednictwem

Ograniczenia importu interfejsu API i znane problemy

DOTYCZY: Wszystkie warstwy usługi API Management

Podczas importowania interfejsu API mogą wystąpić pewne ograniczenia lub konieczność identyfikowania i rozwiązywania problemów przed pomyślnym zaimportowaniem. Z tego artykułu dowiesz się:

  • Zachowanie usługi API Management podczas importowania interfejsu OpenAPI.
  • Ograniczenia importowania interfejsu OpenAPI i sposób działania eksportu interfejsu OpenAPI.
  • Wymagania i ograniczenia dotyczące importowania plików WSDL i WADL.

Zarządzanie API podczas importowania OpenAPI

Podczas importu interfejsu OpenAPI, zarządzanie interfejsami API:

  • Sprawdza parametry ciągu zapytania oznaczone jako wymagane.
  • Domyślnie konwertuje wymagane parametry ciągu zapytania na wymagane parametry szablonu.

Jeśli wolisz, aby wymagane parametry zapytania w specyfikacji zostały przetłumaczone na parametry zapytania w usłudze API Management, wyłącz ustawienie Uwzględnij parametry zapytania w szablonach operacji podczas tworzenia interfejsu API w portalu. Można to również zrobić, używając interfejsów API — Utwórz lub Zaktualizuj REST API, aby ustawić właściwość interfejsu translateRequiredQueryParameters API na query.

W przypadku operacji GET, HEAD i OPTIONS usługa API Management odrzuca parametr treści żądania, jeśli jest zdefiniowany w specyfikacji interfejsu OpenAPI.

Ograniczenia importu openAPI/Swagger

Jeśli podczas importowania dokumentu OpenAPI wystąpią błędy, upewnij się, że został on wcześniej zweryfikowany przez jedną z następujących metod:

  • Korzystanie z projektanta w witrynie Azure Portal (Projektowanie > edytora specyfikacji interfejsu OpenAPI frontonu > ) lub
  • Za pomocą narzędzia innej firmy, takiego jak Swagger Editor.

Ogólne

Wymagania dotyczące szablonu adresu URL

Wymaganie opis
Unikatowe nazwy wymaganych parametrów ścieżki i zapytania W interfejsie OpenAPI:
  • Nazwa parametru musi być unikatowa tylko w obrębie lokalizacji, na przykład ścieżka, zapytanie, nagłówek.
W usłudze API Management:
  • Zezwalamy na rozróżnianie operacji zarówno przez parametry ścieżki, jak i zapytania.
  • Interfejs OpenAPI nie obsługuje tej dyskryminacji, dlatego nazwy parametrów muszą być unikatowe w całym szablonie adresu URL. Nazwy są niewrażliwe na wielkość liter.
Zdefiniowany parametr adresu URL Musi być częścią szablonu adresu URL.
Dostępny adres URL pliku źródłowego Dotyczy względnych adresów URL serwera.
\$ref Wskaźniki Nie można odwoływać się do plików zewnętrznych.

Specyfikacje interfejsu OpenAPI

Obsługiwane wersje

Usługa API Management obsługuje tylko:

  • OpenAPI wersja 2
  • OpenAPI w wersji 3.0.x (do wersji 3.0.3)
  • Interfejs OpenAPI w wersji 3.1 (tylko do importu)

Ograniczenia rozmiaru

Limit rozmiaru opis
Do 4 MB Gdy specyfikacja OpenAPI jest importowana bezpośrednio do zarządzania API.
Rozmiar żądania interfejsu API usługi Azure Resource Manager Gdy dokument OpenAPI jest dostarczany za pośrednictwem adresu URL do lokalizacji dostępnej z usługi API Management. Zobacz Limity subskrypcji platformy Azure.

Obsługiwane rozszerzenia

Jedynymi obsługiwanymi rozszerzeniami są:

Rozszerzenie opis
x-ms-paths
  • Umożliwia definiowanie ścieżek, które są rozróżniane przez parametry zapytania w adresie URL.
  • Opisano to w dokumentacji AutoRest.
x-servers Backport obiektu OpenAPI 3 servers dla interfejsu OpenAPI 2.

Nieobsługiwane rozszerzenia

Rozszerzenie opis
Recursion Usługa API Management nie obsługuje definicji zdefiniowanych rekursywnie.
Na przykład schematy odwołujące się do siebie.
Server obiekt Nie jest obsługiwane na poziomie operacyjnym API.
Produces słowo kluczowe Opisuje typy MIME zwracane przez interfejs API.
Niewspierane

Rozszerzenia niestandardowe

  • Są ignorowane podczas importowania.
  • Nie są zapisywane ani zachowywane dla eksportu.

Nieobsługiwane definicje

Wbudowane definicje schematu dla operacji interfejsu API nie są obsługiwane. Definicje schematu:

  • Są definiowane w obszarze interfejsu API.
  • Można odwoływać się w kontekście żądań lub odpowiedzi operacji interfejsu API.

Ignorowane definicje

Definicje zabezpieczeń są ignorowane.

Ograniczenia definicji

Podczas importowania parametrów zapytania obsługiwana jest tylko domyślna metoda serializacji tablicy (style: form, explode: true). Aby uzyskać więcej informacji na temat parametrów zapytania w specyfikacji interfejsu OpenAPI, zapoznaj się ze specyfikacją serializacji.

Parametry zdefiniowane w plikach cookie nie są obsługiwane. Nadal można użyć zasad do dekodowania i sprawdzania poprawności zawartości plików cookie.

Interfejs OpenAPI w wersji 2

Obsługa interfejsu OpenAPI w wersji 2 jest ograniczona tylko do formatu JSON.

Parametry typu "Formularz" nie są obsługiwane. Nadal można użyć polityki, aby dekodować i weryfikować ładunki application/x-www-form-urlencoded i application/form-data.

Interfejs OpenAPI w wersji 3.x

Usługa API Management obsługuje następujące wersje specyfikacji:

Adresy URL protokołu HTTPS

  • Jeśli określono wiele servers, usługa API Management będzie używać pierwszego napotkanego adresu URL HTTPS.
  • Jeśli nie ma żadnych adresów URL protokołu HTTPS, adres URL serwera jest pusty.

Obsługiwane

  • example

Nieobsługiwane

Następujące pola są uwzględniane w interfejsie OpenAPI w wersji 3.0.x lub OpenAPI w wersji 3.1.x, ale nie są obsługiwane:

Objekt Pole
Interfejs OpenAPI externalDocs
Informacje summary
Elementy
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
Element ścieżki
  • trace
  • servers
Operacja
  • externalDocs
  • callbacks
  • security
  • servers
Parametr
  • allowEmptyValue
  • style
  • explode
  • allowReserved
Tworzenie szablonów serwera
  • API Server and Base URL

Mechanizmy importowania, aktualizowania i eksportowania interfejsu OpenAPI

Ogólne

Definicje interfejsu API wyeksportowane z usługi API Management to:

  • Przeznaczone głównie dla aplikacji zewnętrznych, które muszą wywoływać interfejs API hostowany w usłudze API Management.
  • Nie ma być importowany do tej samej lub innej usługi API Management.

Aby uzyskać informacje na temat zarządzania konfiguracją definicji interfejsu API w różnych usługach/środowiskach, zapoznaj się z dokumentacją dotyczącą korzystania z usługi API Management z usługą Git.

Dodaj nowy interfejs API przez import OpenAPI

Dla każdej operacji znalezionej w dokumencie OpenAPI zostanie utworzona nowa operacja z:

  • Nazwa zasobu platformy Azure ustawiona na operationId.

    • operationId wartość jest znormalizowana.
    • Jeśli operationId nie zostanie określona (nie jest obecna, nulllub pusta), wartość nazwy zasobu platformy Azure jest generowana przez połączenie metody HTTP i szablonu ścieżki.
      • Na przykład get-foo.

  • Nazwa wyświetlana ustawiona na summary.

    • summary wartość:
      • Zaimportowane w obecnym stanie.
      • Długość jest ograniczona do 300 znaków.
    • Jeśli summary nie jest określone (nie występuje, null lub jest puste), wartość nazwy wyświetlanej zostanie ustawiona na wartość operationId.

Reguły normalizacji dla operationId

  • Przekonwertuj na małe litery.
  • Zastąp każdą sekwencję znaków innych niż alfanumeryczne pojedynczą kreską.
    • Na przykład GET-/foo/{bar}?buzz={quix} jest przekształcany w get-foo-bar-buzz-quix-.
  • Przytnij kreski po obu stronach.
    • Na przykład get-foo-bar-buzz-quix- staje się get-foo-bar-buzz-quix
  • Skróć do 76 znaków, o cztery znaki mniej niż maksymalny limit dla nazwy zasobu.
  • W razie potrzeby użyj pozostałych czterech znaków dla sufiksu deduplikacji w postaci -1, -2, ..., -999.

Aktualizowanie istniejącego interfejsu API za pomocą importowania interfejsu OpenAPI

Podczas importowania istniejąca operacja interfejsu API:

  • Zmiany zgodne z interfejsem API opisanym w dokumencie OpenAPI.
  • Dopasowuje operację w dokumencie OpenAPI, porównując wartość operationId operacji do nazwy zasobu platformy Azure dla istniejącej operacji.
    • Jeśli zostanie znalezione dopasowanie, właściwości istniejącej operacji zostaną zaktualizowane "w miejscu".
    • Jeśli dopasowanie nie zostanie znalezione:
      • Nowa operacja jest tworzona przez połączenie metody HTTP i szablonu ścieżki, na przykład get-foo.
      • W przypadku każdej nowej operacji import podejmie próbę skopiowania zasad z istniejącej operacji przy użyciu tej samej metody HTTP i szablonu ścieżki.

Wszystkie istniejące niepasowane operacje są usuwane.

Aby zwiększyć przewidywalność importu, postępuj zgodnie z następującymi wytycznymi:

  • Określ operationId właściwość dla każdej operacji.
  • Powstrzymaj się od zmiany operationId po pierwszym zaimportowaniu.
  • Nigdy nie zmieniaj operationId oraz metody HTTP lub szablonu ścieżki w tym samym czasie.

Reguły normalizacji dla operationId

  • Przekonwertuj na małe litery.
  • Zastąp każdą sekwencję znaków innych niż alfanumeryczne pojedynczą kreską.
    • Na przykład GET-/foo/{bar}?buzz={quix} jest przekształcany w get-foo-bar-buzz-quix-.
  • Przytnij kreski po obu stronach.
    • Na przykład get-foo-bar-buzz-quix- staje się get-foo-bar-buzz-quix
  • Skróć do 76 znaków, o cztery znaki mniej niż maksymalny limit dla nazwy zasobu.
  • W razie potrzeby użyj pozostałych czterech znaków dla sufiksu deduplikacji w postaci -1, -2, ..., -999.

Eksportowanie API jako OpenAPI

Dla każdej operacji jest to:

  • Nazwa zasobu platformy Azure jest eksportowana jako .operationId
  • Nazwa wyświetlana jest eksportowana jako summary.

Należy pamiętać, że normalizacja elementu operationId odbywa się podczas importowania, a nie eksportu.

Biblioteka WSDL

Można tworzyć interfejsy API typu SOAP pass-through oraz SOAP-to-REST przy użyciu plików WSDL.

Powiązania protokołu SOAP

  • Obsługiwane są tylko wiązania SOAP w stylu kodowania "document" i "literalny".
  • Brak obsługi stylu "rpc" ani kodowania SOAP.

Importy i dodatki

  • Dyrektywy wsdl:import, xsd:importi xsd:include nie są obsługiwane. Zamiast tego scal zależności w jeden dokument.

  • Aby narzędzie open source mogło rozwiązywać i scalać wsdl:importzależności, xsd:import oraz xsd:include w pliku WSDL, zapoznaj się z tym repozytorium GitHub.

Specyfikacje WS-*

Pliki WSDL zawierające specyfikacje WS-* nie są obsługiwane.

Komunikaty z wieloma częściami

Ten typ komunikatu nie jest obsługiwany.

WCF wsHttpBinding

  • Usługi SOAP utworzone za pomocą programu Windows Communication Foundation powinny używać polecenia basicHttpBinding.
  • wsHttpBinding nie jest obsługiwany.

Minimalna cena transferowa (MT

  • Usługi korzystające z MTOMmogą działać.
  • Oficjalna pomoc techniczna nie jest obecnie oferowana.

Rekursja

  • Typy zdefiniowane rekursywnie nie są obsługiwane przez usługę API Management.
  • Na przykład odwołaj się do tablicy z elementami tego samego typu.

Wiele przestrzeni nazw

Chociaż w schemacie można używać wielu przestrzeni nazw, tylko docelowa przestrzeń nazw może służyć do definiowania części komunikatów. Te przestrzenie nazw służą do definiowania innych elementów wejściowych lub wyjściowych.

Przestrzenie nazw inne niż obiekt docelowy nie są zachowywane podczas eksportowania. Chociaż można zaimportować dokument WSDL definiujący części komunikatów z innymi przestrzeniami nazw, wszystkie części komunikatów będą miały docelową przestrzeń nazw WSDL podczas eksportowania.

Wiele punktów końcowych

Pliki WSDL mogą definiować jedną lub więcej usług oraz punktów końcowych (portów) za pomocą elementów wsdl:service i wsdl:port. Brama usługi API Management może jednak importować żądania serwera proxy i wysyłać je tylko do jednej usługi i punktu końcowego. Jeśli w pliku WSDL zdefiniowano wiele usług lub punktów końcowych, zidentyfikuj nazwę usługi docelowej i punkt końcowy podczas importowania interfejsu API przy użyciu właściwości wsdlSelector .

Napiwek

Jeśli chcesz równoważyć żądania w wielu usługach i punktach końcowych, rozważ skonfigurowanie puli zaplecza o zrównoważonym obciążeniu.

Tablice

Transformacja soap-to-REST obsługuje tylko zawinięte tablice pokazane w poniższym przykładzie:

    <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 (Waga)

Obecnie nie ma znanych problemów z importowaniem WADL.