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

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

Až bude vaše rozhraní API připravené a bude ho používat vývojáři, budete nakonec muset provést změny tohoto rozhraní API a zároveň nenarušovat volající rozhraní API. Také je užitečné informovat vývojáře o prováděných změnách.

Ve službě Azure API Management pomocí revizí proveďte nefunkční změny rozhraní API, abyste mohli bezpečně modelovat a testovat změny. Až budete připraveni, můžete provést revizi jako aktuální a nahradit aktuální rozhraní API.

Pozadí najdete 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.
• Projděte si také následující kurz: Navíc kurzu: Import a publikování vašeho 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.

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

   Poznámka

   Původní rozhraní API zůstane v Revizi 1. Vaši uživatelé nadále volají tuto revizi, dokud se nerozhodnete nastavit jako aktuální jinou revizi.

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

1. Ze seznamu rozhraní API vyberte Swagger Petstore .

2. V horní části obrazovky vyberte kartu Návrh.

3. Všimněte si, že jako aktuálně vybraná revize v selektoru revize (přímo nad kartou Návrh) se zobrazí Revize 2.

   Tip

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

4. Vyberte + Přidat operaci.

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

6. Uložte novou operaci.

   

7. Teď jste provedli změnu revize 2. Pomocí selektorurevizí v horní části stránky přepněte zpět na revizi 1.

8. 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 kartu 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ě, zaškrtněte políčko 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"

5. 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 Rychlý start pro Bash v Azure Cloud Shellu.

  

• 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 Přihlášení 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 Využití rozšíření v 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:

   Azure CLI

   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 :

   Azure CLI

   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 :

   Azure CLI

   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 :

   Azure CLI

   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 :

Azure CLI

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 jste vyzkoušeli portál pro vývojáře, můžete si projít změny rozhraní API a protokol změn tam.

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 Protokol 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ší kroky

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

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