Importowanie specyfikacji interfejsu OpenAPI

DOTYCZY: Wszystkie warstwy usługi API Management

W tym artykule pokazano, jak zaimportować interfejs API zaplecza "Specyfikacja interfejsu OpenAPI" do usługi Azure API Management 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 omówiono sposób wykonywania następujących zadań:

• 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

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

Wymagania wstępne

• Wystąpienie usługi API Management. Jeśli jeszcze go nie masz, wykonaj czynności opisane w następującym przewodniku Szybki start: Tworzenie wystąpienia usługi Azure API Management.

• Interfejs wiersza polecenia platformy Azure

  • Użyj środowiska powłoki Bash w usłudze Azure Cloud Shell. Aby uzyskać więcej informacji, zobacz Szybki start dotyczący powłoki Bash w usłudze Azure Cloud Shell.

    

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

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

    • Po wyświetleniu monitu zainstaluj rozszerzenie interfejsu wiersza polecenia platformy Azure podczas pierwszego użycia. Aby uzyskać więcej informacji na temat rozszerzeń, zobacz Korzystanie z rozszerzeń w interfejsie wiersza polecenia platformy Azure.

    • Uruchom polecenie az version, aby znaleźć zainstalowane wersje i biblioteki zależne. Aby uaktualnić do najnowszej wersji, uruchom polecenie 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 .

Importowanie interfejsu API zaplecza

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

Portal

1. W witrynie Azure Portal przejdź do wystąpienia usługi API Management.

2. W menu po lewej stronie wybierz pozycję Interfejsy> API+ Dodaj interfejs 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 pozycję 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 .

Program 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 witrynie Azure Portal przejdź do wystąpienia usługi API Management.
2. W menu po lewej stronie w obszarze Interfejsy API wybierz pozycję Interfejsy<>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.

Sprawdzanie poprawności względem schematu specyfikacji interfejsu OpenAPI

Zasady weryfikacji usługi API Management można skonfigurować tak, aby weryfikowały żądania i odpowiedzi (lub elementy) względem schematu w specyfikacji interfejsu 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

   W konsoli testowej usługa API Management automatycznie wypełnia nagłówek Ocp-Apim-Subscription-Key i konfiguruje klucz subskrypcji wbudowanej subskrypcji typu all-access. Ten klucz umożliwia dostęp do każdego interfejsu API w wystąpieniu usługi API Management. Opcjonalnie wyświetl nagłówek Ocp-Apim-Subscription-Key , wybierając ikonę "oko" 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.

   Napiwek

   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

Możesz utworzyć interfejs API interfejsów API udostępnianych przez różne usługi, w tym:

• Specyfikacja interfejsu OpenAPI
• Interfejs API PROTOKOŁU SOAP
• Interfejs API graphQL
• Aplikacja internetowa hostowana w usłudze aplikacja systemu Azure
• Aplikacja funkcji platformy Azure
• Azure Logic Apps
• Azure Service Fabric

Dołącz inny interfejs API do istniejącego interfejsu API, wykonując następujące kroki.

Uwaga

Po zaimportowaniu innego interfejsu API operacje są dołączane do bieżącego interfejsu API.

1. Przejdź do wystąpienia Azure API Management w Azure Portal.

   

2. Wybierz pozycję Interfejsy API na stronie Przegląd lub z menu po lewej stronie.

   

3. Kliknij przycisk ... obok interfejsu API, który chcesz dołączyć do innego interfejsu API.

4. Z menu rozwijanego wybierz pozycję Importuj.

   

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

   

Powiązane tematy

• Ograniczenia importu interfejsu API
• Importowanie specyfikacji interfejsu OpenAPI
• Importowanie interfejsu API SOAP
• Importowanie interfejsu API SOAP i konwertowanie go na interfejs API REST
• Importowanie interfejsu API usługi App Service
• Importowanie interfejsu API aplikacji kontenera
• Importowanie interfejsu API protokołu WebSocket
• Importowanie interfejsu GraphQL API
• Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól
• Importowanie aplikacji funkcji platformy Azure
• Importowanie usługi Azure Logic App
• Importowanie usługi Service Fabric
• Importowanie interfejsu API usługi Azure OpenAI
• Importowanie interfejsu API OData
• Importowanie metadanych sap OData
• Importowanie interfejsu API gRPC
• Edytowanie interfejsu API

Następne kroki

• Tworzenie i publikowanie produktu
• Przekształcanie i ochrona opublikowanego interfejsu API