Importowanie specyfikacji interfejsu OpenAPI

DOTYCZY: Wszystkich poziomów zarządzania API

W tym artykule pokazano, jak zaimportować do usługi Azure API Management zaplecze API określone specyfikacją OpenAPI przy użyciu różnych narzędzi. W tym artykule pokazano również, jak przetestować interfejs API w usłudze API Management.

W tym artykule dowiesz się, jak:

• Importowanie specyfikacji interfejsu OpenAPI przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell
• Testowanie interfejsu API w witrynie Azure Portal

Uwaga / Notatka

Ograniczenia importu interfejsu API są udokumentowane w temacie Ograniczenia importu interfejsu API i znane problemy.

Wymagania wstępne

• Instancja zarządzania API. Jeśli jeszcze go nie masz, wykonaj czynności opisane w następującym szybkim przewodniku: Tworzenie wystąpienia usługi Azure API Management.

• Interfejs wiersza polecenia platformy Azure

  • Użyj środowiska Bash w Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Get started with Azure Cloud Shell.

    

  • Jeśli wolisz uruchamiać polecenia referencyjne interfejsu wiersza polecenia lokalnie, zainstaluj Azure CLI. Jeśli korzystasz z systemu Windows lub macOS, rozważ uruchomienie Azure CLI w kontenerze Docker. Aby uzyskać więcej informacji, zobacz Jak uruchomić Azure CLI w kontenerze Docker.

    • Jeśli korzystasz z instalacji lokalnej, zaloguj się do Azure CLI za pomocą polecenia az login. Aby zakończyć proces uwierzytelniania, wykonaj kroki wyświetlane na Twoim terminalu. Aby uzyskać inne opcje logowania, zobacz Uwierzytelnianie na platformie Azure przy użyciu interfejsu wiersza polecenia platformy Azure.

    • Gdy zostaniesz o to poproszony/a, zainstaluj rozszerzenie Azure CLI przy pierwszym użyciu. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Używanie rozszerzeń i zarządzanie nimi za pomocą interfejsu wiersza polecenia platformy Azure.

    • Uruchom az version, aby sprawdzić zainstalowaną wersję i biblioteki zależne. Aby zaktualizować do najnowszej wersji, uruchom az upgrade.

• Azure PowerShell

  • Jeśli zdecydujesz się używać programu Azure PowerShell lokalnie:
    • Zainstaluj najnowszą wersję modułu Az programu PowerShell.
    • Połącz się z kontem platformy Azure przy użyciu polecenia cmdlet Connect-AzAccount .
  • Jeśli zdecydujesz się używać usługi Azure Cloud Shell:
    • Aby uzyskać więcej informacji, zobacz Omówienie usługi Azure Cloud Shell .

Zaimportuj interfejs API zaplecza

W tym przykładzie zaimportujesz specyfikację OpenAPI dla open source Petstore API, ale możesz zastąpić ją wybraną specyfikacją OpenAPI.

Portal

1. Na portalu Azure przejdź do instancji zarządzania API.

2. W lewym menu wybierz API> + Dodaj API.

3. W obszarze Utwórz na podstawie definicji wybierz pozycję OpenAPI.

   

4. Wprowadź ustawienia interfejsu API. Wartości można ustawić podczas tworzenia lub skonfigurować później, przechodząc do karty Ustawienia . Ustawienia zostały wyjaśnione w samouczku Importowanie i publikowanie pierwszego interfejsu API .

5. Wybierz Utwórz.

Interfejs wiersza polecenia platformy Azure

W poniższym przykładzie użyto polecenia az apim api import w celu zaimportowania specyfikacji interfejsu OpenAPI z określonego adresu URL do wystąpienia usługi API Management o nazwie apim-hello-world. Aby zaimportować przy użyciu ścieżki do specyfikacji zamiast adresu URL, użyj parametru --specification-path .

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

Po zaimportowaniu interfejsu API w razie potrzeby możesz zaktualizować ustawienia przy użyciu polecenia az apim api update .

PowerShell

W poniższym przykładzie użyto polecenia cmdlet Import-AzApiManagementApi programu Azure PowerShell, aby zaimportować specyfikację interfejsu OpenAPI z określonego adresu URL do wystąpienia usługi API Management o nazwie apim-hello-world. Aby zaimportować przy użyciu ścieżki do specyfikacji zamiast adresu URL, użyj parametru -SpecificationPath .

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

Po zaimportowaniu interfejsu API w razie potrzeby możesz zaktualizować ustawienia przy użyciu polecenia cmdlet Set-AzApiManagementApi .

Wyświetlanie i edytowanie specyfikacji interfejsu OpenAPI

W portalu użyj edytora specyfikacji interfejsu OpenAPI, aby wyświetlić, zweryfikować lub edytować specyfikację zaimportowanych interfejsów API.

Aby użyć edytora specyfikacji interfejsu OpenAPI:

1. W portalu Azure przejdź do wystąpienia usługi API Management.
2. W menu po lewej stronie w obszarze Interfejsy API wybierz pozycję Interfejsy API><twój API>>Wszystkie operacje.
3. Na karcie Projektowanie w frontonie wybierz pozycję Edytor specyfikacji Interfejsu OpenAPI (ikona ołówka). Specyfikację można otworzyć w formacie JSON lub YAML.
4. Przejrzyj lub zmodyfikuj specyfikację zgodnie z potrzebami. Zapisz swoje zmiany.

Walidacja względem schematu specyfikacji OpenAPI

Można skonfigurować zasady walidacji usługi API Management w celu walidacji żądań i odpowiedzi (lub ich elementów) względem schematu zawartego w specyfikacji OpenAPI. Na przykład użyj zasad validate-content , aby zweryfikować rozmiar lub zawartość treści żądania lub odpowiedzi.

Testowanie nowego interfejsu API w portalu

Operacje można wywoływać bezpośrednio z portalu, co zapewnia wygodny sposób wyświetlania i testowania operacji interfejsu API przez administratorów.

1. Wybierz interfejs API utworzony w poprzednim kroku.

2. Wybierz kartę Test.

3. Wybierz operację. Na stronie zostaną wyświetlone pola parametrów zapytania i pola nagłówków.

   Uwaga / Notatka

   W konsoli testowej usługa API Management automatycznie wypełnia nagłówek Ocp-Apim-Subscription-Key i konfiguruje klucz subskrypcji dla wbudowanej subskrypcji o pełnym dostępie. Ten klucz umożliwia dostęp do wszystkich interfejsów API w instancji zarządzania API. Opcjonalnie wyświetl nagłówek Ocp-Apim-Subscription-Key, wybierając ikonę "oko" znajdującą się obok żądania HTTP.

4. W zależności od operacji wprowadź wartości parametrów zapytania, wartości nagłówka lub treść żądania. Wybierz Wyślij.

   Po pomyślnym zakończeniu testu zaplecze odpowiada z pomyślnym kodem odpowiedzi HTTP i pewnymi danymi.

   Wskazówka

   Domyślnie konsola testowa wysyła żądanie do serwera proxy CORS usługi API Management, który przekazuje żądanie do wystąpienia usługi API Management, które następnie przekazuje je do zaplecza. Ten serwer proxy używa publicznego adresu IP 13.91.254.72 i może uzyskiwać dostęp tylko do publicznych punktów końcowych. Jeśli chcesz wysłać żądanie bezpośrednio z przeglądarki do usługi API Management, wybierz pozycję Pomiń serwer proxy CORS. Użyj tej opcji, jeśli chcesz użyć konsoli testowej, a brama usługi API Management jest odizolowana od sieci lub nie zezwala na ruch z serwera proxy CORS.

Aby debugować interfejs API, zobacz Samouczek: debugowanie interfejsów API przy użyciu śledzenia żądań.

Dołączanie innych interfejsów API

Interfejs API można zbudować z API, które są udostępniane przez różne usługi, w tym:

• Specyfikacja interfejsu OpenAPI
• Interfejs SOAP
• API GraphQL
• Aplikacja internetowa hostowana w usłudze Azure App Service
• Funkcje platformy Azure
• Azure Logic Apps
• Azure Service Fabric

Uwaga / Notatka

Podczas importowania interfejsu API operacje są dołączane do bieżącego interfejsu API.

Aby dodać interfejs API do istniejącego:

1. Przejdź do instancji Azure API Management w portalu Azure.

   

2. Wybierz interfejsy API na stronie Przegląd lub wybierz interfejsy API>interfejsy API w menu po lewej stronie.

   Zrzut ekranu przedstawiający wybór interfejsów API na stronie przeglądowej.

3. Wybierz wielokropek (...) obok interfejsu API, do którego chcesz dołączyć inny.

4. Wybierz Importuj z menu rozwijanego:

   Zrzut ekranu przedstawiający polecenie Importuj.

5. Wybierz usługę, z której chcesz zaimportować interfejs API.

Powiązana zawartość

• Ograniczenia importu interfejsu API
• Importowanie specyfikacji interfejsu OpenAPI
• Importuj API SOAP
• Importowanie interfejsu API protokołu SOAP i przekształcenie go na interfejs API REST
• Importowanie API usługi aplikacji
• Importowanie interfejsu API aplikacji kontenera
• Importuj WebSocket API
• Zaimportuj GraphQL API
• Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól
• Zaimportuj API aplikacji funkcji
• Importowanie interfejsu API aplikacji logicznej
• Importowanie usługi Service Fabric
• Importowanie interfejsu API usługi Azure AI Foundry
• Importowanie interfejsu API usługi Azure OpenAI
• Importowanie interfejsu API LLM
• Importowanie interfejsu API OData
• Importowanie metadanych sap OData
• Zaimportuj API gRPC
• Edytowanie interfejsu API