Ograniczenia importu interfejsu API i znane problemy

  • Artykuł

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.

Usługa API Management podczas importowania interfejsu OpenAPI

Podczas importowania interfejsu OpenAPI, usługa API Management:

  • 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ć przy użyciu interfejsów API — tworzenie lub aktualizowanie interfejsu API REST w celu ustawienia właściwości interfejsu API translateRequiredQueryParameters na querywartość .

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 Edytor struktury Swagger.

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.
Zdefiniowany parametr adresu URL Musi być częścią szablonu adresu URL.
Dostępny adres URL pliku źródłowego Zastosowano do 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:

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

Ograniczenia rozmiaru

Limit rozmiaru opis
Do 4 MB Gdy specyfikacja interfejsu OpenAPI jest importowana w tekście do usługi API Management.
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ą:

Numer wewnętrzny 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

Numer wewnętrzny opis
Recursion Usługa API Management nie obsługuje definicji zdefiniowanych rekursywnie.
Na przykład schematy odwołujące się do siebie.
Server Obiektu Nieobsługiwane na poziomie operacji interfejsu API.
Produces Słowa kluczowego Opisuje typy MIME zwracane przez interfejs API.
Nieobsługiwane.

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 zakresie interfejsu API.
  • Można odwoływać się do zakresu żądań operacji interfejsu API lub odpowiedzi.

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ć zasad, aby dekodować i weryfikować application/x-www-form-urlencoded i application/form-data ładować.

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 znalezionego 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
OpenAPI externalDocs
Informacji summary
Elementy
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operacja
  • externalDocs
  • callbacks
  • security
  • servers
Parametr
  • allowEmptyValue
  • style
  • explode
  • allowReserved

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.

Dodawanie nowego interfejsu API za pomocą importowania interfejsu 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 zgodnie z rzeczywistymi danymi.
      • Długość jest ograniczona do 300 znaków.
    • Jeśli summary nie określono wartości (nie ma wartości obecnej, nulllub pustej), wartość nazwy wyświetlanej zostanie ustawiona na operationIdwartość .

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} element jest przekształcany w get-foo-bar-buzz-quix-.
  • Przycinanie kreski po obu stronach.
    • Na przykład get-foo-bar-buzz-quix- staje się get-foo-bar-buzz-quix
  • Obcinanie do 76 znaków, cztery znaki mniejsze 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.
  • Pasuje do operacji w dokumencie OpenAPI, porównując jej operationId wartość z nazwą zasobu platformy Azure 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 metody lub szablonu ścieżki HTTP 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} element jest przekształcany w get-foo-bar-buzz-quix-.
  • Przycinanie kreski po obu stronach.
    • Na przykład get-foo-bar-buzz-quix- staje się get-foo-bar-buzz-quix
  • Obcinanie do 76 znaków, cztery znaki mniejsze 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 interfejsu API jako interfejsu 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.

WSDL

Interfejsy API SOAP przekazywane i SOAP-to-REST można tworzyć przy użyciu plików WSDL.

Powiązania protokołu SOAP

  • Obsługiwane są tylko powiązania PROTOKOŁU SOAP w stylu kodowania "document" i "literał".
  • Brak obsługi stylu "rpc" ani kodowania SOAP.

Importy i obejmuje

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

  • Aby narzędzie typu open source rozpoznawało i scalało wsdl:importzależności , xsd:importi w xsd:include pliku WSDL, zobacz to repozytorium GitHub.

Specyfikacje usług 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.

MTOM

  • Usługi korzystające z usługi 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 zapoznaj się z tablicą samych siebie.

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ć wiele usług i punktów końcowych (portów) przez co najmniej jeden wsdl:service element 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ć obciążenia żądania w wielu usługach i punktach końcowych, rozważ skonfigurowanie puli zaplecza ze zrównoważonym obciążeniem.

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

Obecnie nie ma znanych problemów z importowaniem wadL.