Import specifikace OpenAPI

PLATÍ PRO: Všechny úrovně služby API Management

Tento článek ukazuje, jak importovat back-endové rozhraní API specifikace OpenAPI do služby Azure API Management pomocí různých nástrojů. Tento článek také ukazuje, jak otestovat rozhraní API ve službě API Management. Informace o podpoře verzí OpenAPI najdete v tématu Omezení importu rozhraní API a známé problémy.

V tomto článku získáte informace o těchto tématech:

• Import specifikace OpenAPI pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu
• Testovat rozhraní API na portálu Azure Portal

Požadavky

• Instance správy API. Pokud ho ještě nemáte, proveďte následující rychlý start: Vytvořte instanci služby Azure API Management.

• Azure CLI (příkazový řádek nástroje Azure)

  • Použijte prostředí Bash v Azure Cloud Shellu. Další informace najdete v tématu Začínáme s Azure Cloud Shellem.

    

  • Pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Docker. Další informace najdete v tématu Jak spustit Azure CLI v kontejneru Dockeru.

    • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login. Pokud chcete dokončit proces ověřování, postupujte podle kroků zobrazených na terminálu. Další možnosti přihlášení najdete v tématu Ověřování v Azure pomocí Azure CLI.

    • Po zobrazení výzvy nainstalujte rozšíření Azure CLI při prvním použití. Další informace o rozšířeních najdete v tématu Použití a správa rozšíření pomocí Azure CLI.

    • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

• Azure PowerShell

  • Pokud se rozhodnete používat Azure PowerShell místně:
    • Nainstalujte nejnovější verzi modulu Az PowerShell.
    • Připojte se ke svému účtu Azure pomocí rutiny Connect-AzAccount .
  • Pokud se rozhodnete použít Azure Cloud Shell:
    • Další informace najdete v přehledu služby Azure Cloud Shell .

Importovat rozhraní API backendu

V tomto příkladu importujete specifikaci OpenAPI pro opensourcové rozhraní Petstore API. Můžete nahradit vámi zvolenou specifikaci OpenAPI.

Portál

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.

2. V nabídce vlevo vyberte rozhraní API> + Přidat rozhraní API.

3. V části Vytvořit z definice vyberte OpenAPI.

   

4. Zadejte nastavení rozhraní API. Hodnoty můžete nastavit při vytváření nebo je později nakonfigurovat tak, že přejdete na kartu Nastavení . Nastavení jsou vysvětlená v kurzu Import a publikování vašeho prvního kurzu rozhraní API .

5. Vyberte Vytvořit.

Azure CLI

Následující příklad používá příkaz az apim api import k importu specifikace OpenAPI ze zadané adresy URL do instance služby API Management s názvem apim-hello-world. Pokud chcete místo adresy URL importovat cestu ke specifikaci, použijte parametr --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 importu rozhraní API můžete nastavení aktualizovat pomocí příkazu az apim api update .

PowerShell

Následující příklad používá rutinu Azure PowerShellu Import-AzApiManagementApi k importu specifikace OpenAPI ze zadané adresy URL do instance služby API Management s názvem apim-hello-world. Pokud chcete místo adresy URL importovat cestu ke specifikaci, použijte parametr -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 importu rozhraní API můžete nastavení aktualizovat pomocí rutiny Set-AzApiManagementApi .

Zobrazení a úprava specifikace OpenAPI

Na webu Azure Portal můžete pomocí editoru specifikace OpenAPI zobrazit, ověřit nebo upravit specifikaci pro rozhraní API, které jste naimportovali.

Použití editoru specifikace OpenAPI:

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V nabídce vlevo, v části Rozhraní API, vyberte rozhraní API><vaše rozhraní API> a>Všechny operace.
3. Na kartě Návrh ve Frontend vyberte editor specifikace OpenAPI (ikona tužky). Specifikaci můžete otevřít ve formátu JSON nebo YAML.
4. Podle potřeby zkontrolujte nebo upravte specifikaci. Uloží změny.

Ověřte podle schématu specifikace OpenAPI

Zásady ověřování služby API Management můžete nakonfigurovat tak, aby ověřovaly požadavky a odpovědi nebo prvky na základě schématu ve specifikaci OpenAPI. Pomocí zásad ověření obsahu můžete například ověřit velikost nebo obsah požadavku nebo textu odpovědi.

Testování nového rozhraní API na portálu

Operace můžete volat přímo z webu Azure Portal, což poskytuje pohodlný způsob zobrazení a testování operací rozhraní API.

1. Vyberte rozhraní API, které jste vytvořili v předchozím kroku.

2. Vyberte kartu Test.

3. Vyberte operaci.

   Stránka zobrazí pole pro parametry dotazu a pole pro hlavičky.

   Poznámka:

   V testovací konzoli služba API Management automaticky naplní hlavičku Ocp-Apim-Subscription-Key klíčem předplatného a nakonfiguruje klíč předplatného integrovaného předplatného s plným přístupem. Tento klíč umožňuje přístup ke každému rozhraní API v instanci služby API Management. Volitelně můžete zobrazit hlavičku Ocp-Apim-Subscription-Key výběrem ikony oka vedle požadavku HTTP.

4. V závislosti na operaci zadejte hodnoty parametrů dotazu, hodnoty hlaviček nebo text požadavku. Vyberte Odeslat.

   Když je test úspěšný, back-end odpoví úspěšným kódem odpovědi HTTP a některými daty.

   Návod

   Ve výchozím nastavení testovací konzola odešle požadavek na proxy CORS služby API Management, která požadavek předá instanci služby API Management, která jej pak předá back-endu. Tento proxy server používá veřejnou IP adresu 13.91.254.72 a může se připojit pouze k veřejným koncovým bodům.

   Pokud chcete odeslat požadavek přímo z prohlížeče do služby API Management, vyberte Obejít proxy server CORS. Tuto možnost použijte, pokud chcete použít testovací konzolu a brána služby API Management je izolovaná v síti nebo nepovoluje provoz z proxy serveru CORS.

Pokud chcete ladit rozhraní API, podívejte se na Tutoriál: Ladění rozhraní API pomocí trasování požadavků.

Připojení dalších rozhraní API

Můžete vytvořit rozhraní API z rozhraní API, která jsou poskytovaná různými službami, včetně:

• Specifikace OpenAPI
• Rozhraní API SOAP
• Rozhraní GraphQL API
• Webová aplikace hostovaná ve službě Azure App Service
• Azure Functions
• Azure Logic Apps
• Azure Service Fabric

Poznámka:

Při importu rozhraní API se operace připojí k aktuálnímu rozhraní API.

Připojení API k existujícímu API:

1. Na webu Azure Portal přejděte do své instance služby Azure API Management:

   

2. Na stránce Přehled vyberte rozhraní API nebo v nabídce bočního panelu vyberte rozhraní API>.

   

3. Vyberte ikonu se třemi tečkami (...) vedle rozhraní API, k němuž chcete přidat další rozhraní API.

4. V místní nabídce vyberte Importovat :

   

5. Vyberte službu, ze které se má importovat rozhraní API.

Související obsah

• Omezení importu rozhraní API
• Import specifikace OpenAPI
• Importujte API SOAP
• Import rozhraní SOAP API a jeho převod na rozhraní REST
• Importujte API služby App Service
• Importujte API aplikace kontejneru
• Import rozhraní WEBSocket API
• Importujte GraphQL API
• Import schématu GraphQL a nastavení překladačů polí
• Importujte rozhraní API funkční aplikace
• Import rozhraní API aplikace logiky
• Importovat službu Service Fabric
• Importovat rozhraní Microsoft Foundry API
• Rozhraní API Azure OpenAI importovat
• Import rozhraní LLM API
• Import OData API
• Exportujte REST API jako MCP server
• Zveřejnění existujícího serveru MCP
• Import rozhraní API agenta A2A
• Import metadata SAP OData
• Import rozhraní API gRPC
• Úprava rozhraní API