Kurz: Použití revizí k bezpečným změnám rozhraní API

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

Když vaše rozhraní API používají vývojáři, budete nakonec muset provést změny tohoto rozhraní API bez narušení volajících vašeho rozhraní API. Také je užitečné informovat vývojáře o prováděných změnách.

Pomocí revizí ve službě Azure API Management provádějte změny rozhraní API bez přerušení. Můžete bezpečně modelovat a testovat změny. Až budete připraveni, proveďte aktuální revizi a nahraďte aktuální rozhraní API.

Další informace naleznete v tématu Verze a revize.

Tip

Týmy rozhraní API můžou tuto funkci používat v pracovních prostorech. Pracovní prostory poskytují izolovaný přístup pro správu k rozhraním API a vlastním prostředím runtime rozhraní API.

V tomto kurzu se naučíte:

• Přidání nové revize
• Proveďte změny revize, které se neprobíjely.
• Nastavení revize jako aktuální a přidání položky protokolu změn
• Procházení portálu pro vývojáře a zobrazení změn a protokolu změn
• Přístup k revizi rozhraní API

Požadavky

• Seznamte se s terminologií služby Azure API Management.
• Projděte si následující rychlý start: Vytvoření instance Azure API Managementu.
• Dokončete následující kurz: Import a publikování prvního rozhraní API.

Přidání nové revize

1. Přihlaste se k webu Azure Portal a přejděte do instance služby API Management.

2. V nabídce vlevo v části Rozhraní API vyberte rozhraní API.

3. Ze seznamu rozhraní API vyberte Swagger Petstore nebo jiné rozhraní API, do kterého chcete přidat revize.

4. Vyberte kartu Revize.

5. Vyberte + Přidat revizi.

   

   Tip

   V místní nabídce rozhraní API (...) můžete také vybrat Možnost Přidat revizi.

6. Zadejte popis nové revize, abyste si mohli zapamatovat, k čemu se používá.

7. Vyberte Vytvořit.

   Teď se vytvoří vaše nová revize.

   Poznámka:

   Původní rozhraní API zůstane v Revizi 1. Toto je revize, na kterou uživatelé budou nadále odkazovat, dokud se nerozhodnete nastavit jinou revizi jako aktuální.

Proveďte změny revize, které se neprobíjely.

1. Ze seznamu rozhraní API vyberte Swagger Petstore .

2. Vyberte Návrh v horní části obrazovky.

   Selektor revizí nad kartou Návrh zobrazuje revize 2, která je aktuálně vybrána.

   Tip

   Pomocí selektoru revize můžete přepínat mezi revizemi, na kterých chcete pracovat.

3. Vyberte + Přidat operaci.

4. Nastavte novou operaci na POST a zobrazovaný název, název a adresu URL operace jako test.

5. Uložte novou operaci.

   

   Teď jste provedli změnu revize 2.

6. Pomocí selektorurevizí v horní části stránky přepněte zpět na revizi 1.

   Všimněte si, že nová operace se nezobrazuje v revizi 1.

Nastavení revize jako aktuální a přidání položky protokolu změn

Azure Portal

1. V nabídce v horní části stránky vyberte Revize.

2. Otevřete místní nabídku (...) pro Revizi 2.

3. Vyberte Nastavit jako aktuální.

4. Pokud chcete publikovat poznámky k této změně, vyberte Publikovat do veřejného protokolu změn pro toto rozhraní API. Zadejte popis změny, kterou můžou vývojáři vidět, například: Testování revizí. Přidání nové operace "test"

   Revize 2 je teď nastavená jako aktuální.

   

Azure CLI

Jak začít používat Azure CLI:

• 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.

Tento postup použijte k vytvoření a aktualizaci vydané verze.

1. Spuštěním příkazu az api list zobrazte ID rozhraní API:

   az apim api list --resource-group apim-hello-word-resource-group \
       --service-name apim-hello-world --output table
   

   ID rozhraní API, které se má použít v dalším příkazu, je Name hodnota. Revize rozhraní API je ve sloupci ApiRevision .

2. Pokud chcete vytvořit verzi s poznámkou k verzi, spusťte příkaz az apim api release create :

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   Revize, kterou vydáte, se stane aktuální revizí.

3. Pokud chcete zobrazit vaše vydané verze, použijte příkaz az apim api release list :

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --service-name apim-hello-world --output table
   

   Zadané poznámky se zobrazí v protokolu změn. Zobrazí se ve výstupu předchozího příkazu.

4. Při vytváření verze --notes je parametr volitelný. Poznámky můžete později přidat nebo změnit pomocí příkazu az apim api release update :

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id swagger-petstore --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Použijte hodnotu ve Name sloupci pro ID verze.

Libovolnou verzi můžete odebrat spuštěním příkazu az apim api release delete :

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Procházení portálu pro vývojáře a zobrazení změn a protokolu změn

Pokud vyzkoušíte portál pro vývojáře, můžete si projít změny rozhraní API a protokol změn v něm.

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.
3. V horní nabídce vyberte Portál pro vývojáře.
4. Na portálu pro vývojáře vyberte rozhraní API a pak vyberte Swagger Petstore.
5. Všimněte si, že je teď k dispozici vaše nová operace test.
6. V blízkosti názvu rozhraní API vyberte záznam změn.
7. Všimněte si, že položka protokolu změn se zobrazí v seznamu.

Přístup k revizi rozhraní API

Ke každé revizi rozhraní API se dostanete pomocí speciálně vytvořené adresy URL. Přidejte ;rev={revisionNumber} na konec cesty URL rozhraní API, ale před řetězec dotazu získejte přístup ke konkrétní revizi tohoto rozhraní API. Například pro přístup k revizi 2 rozhraní API Swagger Petstore můžete použít adresu URL podobnou následující:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

Cesty URL pro revize rozhraní API najdete na kartě Revize na webu Azure Portal.

Tip

K aktuální revizi rozhraní API můžete přistupovat pomocí cesty rozhraní API bez ;rev řetězce, a to kromě úplné adresy URL, která se připojí ;rev={revisionNumber} k cestě rozhraní API.

Shrnutí

V tomto kurzu jste se naučili, jak:

• Přidání nové revize
• Proveďte změny revize, které se neprobíjely.
• Nastavení revize jako aktuální a přidání položky protokolu změn
• Procházení portálu pro vývojáře a zobrazení změn a protokolu změn
• Přístup k revizi rozhraní API

Další krok

Přejděte k dalšímu kurzu:

Publikování několika verzí vašeho rozhraní API