Přehled portálu pro vývojáře

PLATÍ PRO: Vývojář | Základní | Basic v2 | Standardní | Standard v2 | Premium | Premium v2

Portál pro vývojáře služby API Management je automaticky generovaný plně přizpůsobitelný web s dokumentací vašich rozhraní API. Uživatelé rozhraní API na něm můžou najít vaše rozhraní API, zjistit, jak je používat, požádat o přístup a vyzkoušet si je.

Tento článek představuje funkce portálu pro vývojáře, typy obsahu, které portál představuje, a možnosti správy a rozšíření portálu pro vývojáře pro konkrétní uživatele a scénáře.

Návod

Azure API Management i Azure API Center poskytují prostředí portálu API pro vývojáře. Porovnání portálů

Koncepty architektury portálu pro vývojáře

Komponenty portálu je možné logicky rozdělit do dvou kategorií: kód a obsah.

Kód

Kód se udržuje v úložišti GitHubu na portálu pro vývojáře služby API Management a zahrnuje:

• Widgety – představují vizuální prvky a kombinují HTML, JavaScript, možnosti stylů, nastavení a mapování obsahu. Příklady jsou obrázek, textový odstavec, formulář, seznam rozhraní API atd.
• Definice stylů – určení způsobu, jakým lze widgety stylovat
• Modul , který generuje statické webové stránky z obsahu portálu a je napsaný v JavaScriptu
• Vizuální editor – umožňuje přizpůsobení v prohlížeči a prostředí pro vytváření obsahu.

Obsah

Obsah je rozdělený do dvou podkategorií: obsah portálu a data služby API Management.

• Obsah portálu je specifický pro web portálu a zahrnuje:

  • Stránky – například cílová stránka, kurzy k rozhraní API, blogové příspěvky

  • Multimédia – obrázky, animace a další obsah založený na souborech

  • Rozložení – šablony, které odpovídají adrese URL a určují, jak se stránky zobrazují

  • Styly – hodnoty pro definice stylů, jako jsou písma, barvy, ohraničení

  • Nastavení – konfigurace, jako je favicon, metadata webu

    Obsah portálu s výjimkou médií se vyjadřuje jako dokumenty JSON.

• Data služby API Management zahrnují entity, jako jsou rozhraní API, operace, produkty a předplatná spravovaná v instanci služby API Management.

Přizpůsobení a styl portálu

Poznámka:

• Vylepšujeme portál pro vývojáře pomocí webových komponent Fluent UI v rámci Reactu. Aktualizujeme také zástupný obsah zobrazený při prvním otevření portálu. Vzhled portálu se může mírně lišit od snímků obrazovky v tomto článku, ale funkce zůstávají konzistentní.
• Pokud používáte verzi portálu postavenou na předchozích součástech, uvidíte v dolní části nabídky vlevo nové nastavení návrhu uživatelského rozhraní Preview . Pokud chcete vyzkoušet nejnovější prostředí, povolte toto nastavení.
  
  

Portál pro vývojáře je již vyplněný publikovanými rozhraními API a produkty a připravenými k přizpůsobení vašim potřebám. Jako vydavatel rozhraní API použijete rozhraní pro správu portálu pro vývojáře k přizpůsobení vzhledu a funkčnosti portálu pro vývojáře.

Pokud k portálu přistupujete poprvé, portál obsahuje zástupné stránky, obsah a navigační nabídky. Zobrazený zástupný obsah byl navržen tak, aby zobrazoval možnosti portálu a minimalizoval přizpůsobení potřebná k přizpůsobení portálu.

Podrobný návod k přizpůsobení a publikování portálu pro vývojáře najdete v tématu Kurz: Přístup a přizpůsobení portálu pro vývojáře.

Důležité

• Přístup k portálu pro vývojáře vydavateli a uživateli rozhraní API vyžaduje síťové připojení ke koncovému bodu portálu pro vývojáře (výchozí nastavení: https://<apim-instance-name>.portal.azure-api.net).
• Publikování portálu pro vývojáře vyžaduje další připojení k úložišti objektů blob spravovanému službou API Management v oblasti USA – západ.
• Pokud je instance služby API Management nasazená ve virtuální síti, ujistěte se, že se správně přeloží název hostitele portálu pro vývojáře a že povolíte připojení k požadovaným závislostem pro portál pro vývojáře. Další informace.

Vizuální editor

Rozhraní pro správu portálu pro vývojáře poskytuje vydavatelům vizuální editor pro přizpůsobení obsahu a stylu portálu. Pomocí vizuálního editoru můžete přidávat, odebírat a měnit uspořádání stránek, oddílů a widgetů. Můžete také změnit styl prvků portálu, jako jsou písma, barvy a mezery.

Jako správce můžete obsah portálu přizpůsobit pomocí editoru vizuálů.

• Pomocí možností nabídky vlevo můžete vytvářet nebo upravovat stránky, média, rozložení, nabídky, styly nebo nastavení webu.

• Nahoře můžete přepínat mezi oblastmi zobrazení (pro obrazovky různých velikostí) nebo zobrazit prvky portálu viditelné pro uživatele v různých skupinách. Můžete například chtít zobrazit určité stránky jenom skupinám přidruženým k určitým produktům nebo uživatelům, kteří mají přístup ke konkrétním rozhraním API.

• Uložte nebo vraťte změny, které provedete, nebo publikujte web.

Návod

Pro ještě větší flexibilitu při přizpůsobení portálu můžete použít opensourcový modul plug-in vývojářského portálu pro WordPress. Využijte možnosti webu ve WordPressu k lokalizaci obsahu, přizpůsobení nabídek, použití vlastních šablon stylů a dalších možností.

• Vyberte existující prvky textu a nadpisu a upravte a naformátujte obsah.

• Přidejte sekci na stránku tak, že najedete myší na prázdnou oblast a poté kliknete na modrou ikonu se znaménkem plus. Vyberte si z několika rozložení oddílů.

  

• Přidejte widget (například text, obrázek, vlastní widget nebo seznam rozhraní API) tak, že najedete myší na prázdnou oblast a kliknete na šedou ikonu se znaménkem plus.

  

• Přeuspořádat položky na stránce přetažením a puštěním.

Stránky a rozložení

Předem zřízený obsah na portálu pro vývojáře předvádí stránky s běžně používanými funkcemi. Najděte je na panelu Stránky . Obsah těchto stránek můžete upravit nebo přidat nové tak, aby vyhovovaly vašim potřebám.

Výběrem Rozložení na panelu Stránky definujete, jak se stránky zobrazují. Portál pro vývojáře má výchozí rozložení použité na stránkách. Toto rozložení můžete upravit a přidat další rozložení tak, aby vyhovovalo vašim potřebám.

Rozložení se na stránku aplikuje spárováním šablony adresy URL s adresou URL stránky. Například rozložení se šablonou /wiki/* adresy URL se použije na každou stránku se segmentem /wiki/ v adrese URL: /wiki/getting-started, /wiki/stylesatd.

Na následujícím obrázku je obsah, který patří do rozložení, modrý, zatímco obsah specifický pro stránku je vyznačen červeně.

Poznámka:

Vzhledem k aspektům integrace není možné odebrat ani přesunout následující stránky pod jinou adresou URL: /404, /500, , , /captcha/change-password, /config.json/confirm/invitation, /confirm-v2/identities/basic/signup, /confirm-v2/password/internal-status-0123456789abcdef/publish, /signin, , . /signin-sso/signup. .

Styly

Panel Styly se vytváří s ohledem na návrháře. Pomocí stylů můžete spravovat a přizpůsobovat všechny vizuální prvky na portálu, jako jsou písma použitá v nadpisech a nabídkách a barvách tlačítek. Styl je hierarchický – mnoho prvků dědí vlastnosti z jiných prvků. Například prvky tlačítka používají barvy pro text a pozadí. Pokud chcete změnit barvu tlačítka, musíte změnit původní barevnou variantu.

Pokud chcete upravit variantu, vyberte ji a vyberte Upravit styl v možnostech, které se zobrazí nad ním. Po provedení změn ve vyskakovacím okně ho zavřete.

Rozšíření funkcí portálu

V některých případech možná budete potřebovat funkce nad rámec možností přizpůsobení a stylu, které jsou k dispozici na spravovaném portálu pro vývojáře. Pokud potřebujete implementovat vlastní logiku, která není k dispozici, máte několik možností:

• Vlastní HTML můžete přidat přímo prostřednictvím widgetu vývojářského portálu navrženého pro malá přizpůsobení – například přidat HTML pro formulář nebo vložit videopřehrávku. Vlastní kód se vykreslí ve vloženém rámečku ("IFrame").
• Vytvoření a nahrání vlastního widgetu pro vývoj a přidání složitějších vlastních funkcí portálu
• Samoobslužné hostování portálu, pouze pokud potřebujete upravit jádro základu kódu portálu pro vývojáře. Tato možnost vyžaduje pokročilou konfiguraci. Pomoc podpory Azure je omezená jenom na základní nastavení samoobslužných portálů.

Poznámka:

Vzhledem k tomu, že základ kódu portálu pro vývojáře služby API Management se udržuje na GitHubu, můžete kdykoli nahlásit problémy a vyžádat pull request pro tým služby API Management, aby sloučil nové funkce.

Řízení přístupu k obsahu portálu

Portál pro vývojáře se synchronizuje s vaší instancí služby API Management a zobrazí obsah, jako jsou rozhraní API, operace, produkty, předplatná a profily uživatelů. Rozhraní API a produkty musí být ve stavu publikovaném, aby byla viditelná na portálu pro vývojáře.

Viditelnost obsahu a přístup

Ve službě API Management se skupiny uživatelů používají ke správě viditelnosti produktů a jejich přidružených rozhraní API pro vývojáře. Kromě použití předdefinovaných skupin můžete vytvářet vlastní skupiny podle svých potřeb. Produkty se nejprve zviditelní skupinám a potom vývojáři v těchto skupinách můžou zobrazit produkty přidružené ke skupinám a přihlásit se k jejich odběru.

Můžete také určit, jak se ostatním uživatelům zobrazuje jiný obsah portálu (například stránky a oddíly) na základě jejich identity. Můžete například chtít zobrazit určité stránky jenom uživatelům, kteří mají přístup ke konkrétnímu produktu nebo rozhraní API. Nebo se oddíl stránky zobrazí jenom pro určité skupiny uživatelů. Portál pro vývojáře má integrované ovládací prvky pro tyto potřeby.

Poznámka:

Viditelnost a řízení přístupu se podporují jenom na spravovaném vývojářském portálu. Nejsou podporované na místním portálu.

• Když přidáte stránku nebo upravíte nastavení existující stránky, proveďte výběr v části Přístup , abyste mohli řídit uživatele nebo skupiny, které tuto stránku uvidí.

  

  Návod

  Pokud chcete upravit nastavení existující stránky, vyberte ikonu ozubeného kolečka vedle názvu stránky na kartě Stránky .

• Když vyberete obsah stránky, jako je oddíl stránky, nabídka nebo tlačítko pro úpravy, vyberte ikonu Změnit přístup , abyste mohli řídit uživatele nebo skupiny, které vidí prvek na stránce.

  

  • Viditelnost tohoto obsahu stránky můžete změnit: oddíly, nabídky, tlačítka a přihlášení pro autorizaci OAuth.

  • Multimediální soubory, jako jsou obrázky na stránce, dědí viditelnost prvků, které je obsahují.

Když uživatel navštíví portál pro vývojáře s použitými ovládacími prvky viditelnosti a přístupu:

• Portál pro vývojáře automaticky skryje tlačítka nebo navigační položky, které odkazují na stránky, ke kterým uživatel nemá přístup.

• Pokus uživatele o přístup ke stránce, ke které nemá oprávnění k přístupu, způsobí chybu 404 Nenalezena.

Návod

Pomocí rozhraní pro správu můžete zobrazit náhled stránek jako uživatel přidružený k jakékoli předdefinované nebo vlastní skupině výběrem Zobrazit jako v nabídce nahoře.

Zásady zabezpečení obsahu

Můžete povolit zásadu zabezpečení obsahu, která přidá na portál pro vývojáře vrstvu zabezpečení a pomůže zmírnit určité typy útoků, včetně skriptování mezi weby a injektáže dat. Pomocí zásad zabezpečení obsahu portál pro vývojáře v prohlížeči načte jenom prostředky z důvěryhodných umístění, která zadáte, například z podnikového webu nebo jiných důvěryhodných domén.

Chcete-li povolit zásadu zabezpečení obsahu:

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V nabídce vlevo v části Portál pro vývojáře vyberte nastavení portálu.
3. Na kartě Zásady zabezpečení obsahu vyberte Povoleno.
4. V části Povolené zdroje přidejte jeden nebo více názvů hostitelů, které určují důvěryhodná umístění, ze kterých může portál pro vývojáře načíst prostředky. Můžete také zadat zástupný znak, který povolí všechny subdomény domény. Například *.contoso.com umožňuje všechny subdomény .contoso.com
5. Zvolte Uložit.

Interaktivní testovací konzola

Portál pro vývojáře nabízí možnost Vyzkoušet na referenčních stránkách rozhraní API, aby návštěvníci portálu mohli vaše rozhraní API testovat přímo prostřednictvím interaktivní konzoly.

Testovací konzola podporuje rozhraní API s různými autorizačními modely – například rozhraní API, která nevyžadují žádnou autorizaci nebo vyžadují klíč předplatného nebo autorizaci OAuth 2.0. V druhém případě můžete testovací konzolu nakonfigurovat tak, aby vygenerovala platný token OAuth jménem uživatele testovací konzoly. Další informace najdete v tématu Autorizace testovací konzoly portálu pro vývojáře konfigurací autorizace uživatelů OAuth 2.0.

Důležité

Pokud chcete návštěvníkům portálu umožnit testování rozhraní API prostřednictvím integrované interaktivní konzoly, povolte ve svých rozhraních API zásady CORS (sdílení prostředků mezi zdroji). Podrobnosti najdete v tématu Povolení CORS pro interaktivní konzolu na portálu pro vývojáře služby API Management.

Správa registrace a přihlašování uživatelů

Portál pro vývojáře ve výchozím nastavení povoluje anonymní přístup. To znamená, že každý může zobrazit portál a jeho obsah bez přihlášení, i když přístup k určitému obsahu a funkcím, jako je použití testovací konzoly, může být omezený. Můžete povolit nastavení webu portálu pro vývojáře, které vyžaduje, aby se uživatelé přihlásili pro přístup k portálu.

Portál podporuje několik možností registrace a přihlašování uživatelů:

• Základní ověřování pro vývojáře, kteří se přihlašují pomocí přihlašovacích údajů pro uživatelské účty služby API Management. Vývojáři se můžou k účtu zaregistrovat přímo prostřednictvím portálu, nebo pro ně můžete vytvářet účty.

• V závislosti na vašich scénářích omezte přístup k portálu tím, že uživatelé vyžadují, aby se zaregistrovali nebo přihlásili pomocí účtu Microsoft Entra ID nebo externího ID Microsoft Entra .

• Pokud už spravujete registraci a přihlašování vývojářů prostřednictvím existujícího webu, delegujte ověřování místo použití integrovaného ověřování portálu pro vývojáře.

Přečtěte si další informace o možnostech zabezpečení registrace uživatelů a přihlášení k portálu pro vývojáře.

Zprávy pro uživatele

Portál pro vývojáře generuje sestavy, které ověřeným uživatelům umožňují zobrazit jejich individuální využití API, přenos dat a dobu odezvy, včetně souhrnného použití podle konkrétních produktů a předplatných. Uživatelé můžou zobrazit sestavy výběrem Sestavy ve výchozí navigační nabídce pro ověřené uživatele. Uživatelé můžou filtrovat zprávy podle časového intervalu, pouze do posledních 90 dnů.

Poznámka:

Zprávy na portálu pro vývojáře zobrazují pouze data pro ověřeného uživatele. Vydavatelé rozhraní API a správci mají přístup k datům o využití pro všechny uživatele instance služby API Management – například nastavením monitorovacích funkcí, jako je Azure Application Insights v portálu.

Uložení a publikování obsahu webu

Po aktualizaci obsahu nebo konfigurace vývojářského portálu je potřeba uložit a publikovat změny, aby byly dostupné návštěvníkům portálu. Portál pro vývojáře udržuje záznam publikovaného obsahu a v případě potřeby se můžete vrátit k předchozí revizi portálu.

Uložení změn

Kdykoli na portálu provedete změnu, musíte ji uložit ručně tak, že v nabídce nahoře vyberete tlačítko Uložit nebo stisknete [Ctrl]+[S]. Pokud potřebujete, můžete vrátit zpět poslední uložené změny. Uložené změny jsou viditelné jenom pro vás a nejsou viditelné pro návštěvníky portálu, dokud je nepublikujete.

Poznámka:

Spravovaný vývojářský portál přijímá a automaticky používá aktualizace softwaru. Změny, které jste uložili, ale nepublikovali na portálu pro vývojáře, zůstanou během aktualizace v daném stavu.

Publikování portálu

Pokud chcete portál a jeho nejnovější změny zpřístupnit návštěvníkům, musíte ho publikovat . Portál publikujete v rozhraní pro správu portálu nebo na webu Azure Portal.

Důležité

Portál musíte publikovat kdykoliv, když chcete zveřejnit změny obsahu nebo stylu portálu. Portál je také potřeba znovu publikovat po změnách konfigurace služby API Management, které ovlivňují portál pro vývojáře. Například znovu publikujte portál po přiřazení vlastní domény, aktualizaci zprostředkovatelů identity, nastavení delegování nebo zadání přihlašovacích podmínek a podmínek produktu.

Publikování z rozhraní pro správu

1. Vyberte tlačítko Uložit a ujistěte se, že jste změny uložili.

2. V nabídce v horní části vyberte Publikovat web. Tato operace může trvat několik minut.

   

Publikování z webu Azure Portal

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

2. V nabídce vlevo v části Portál pro vývojáře vyberte Přehled portálu.

3. V okně přehledu portálu vyberte Publikovat.

   

Obnovení předchozí revize portálu

Pokaždé, když publikujete portál pro vývojáře, se uloží odpovídající revize portálu. Předchozí revizi portálu můžete kdykoli znovu publikovat. Můžete například chtít vrátit zpět změnu, kterou jste zavedli při posledním publikování portálu.

Poznámka:

Aktualizace softwaru portálu pro vývojáře se použijí automaticky při obnovení revize. Změny uložené, ale nepublikovaná v rozhraní pro správu zůstanou v daném stavu, když publikujete revizi.

Obnovení předchozí revize portálu:

1. Na webu Azure Portal přejděte k vaší instanci služby API Management.
2. V nabídce vlevo v části Portál pro vývojáře vyberte Přehled portálu.
3. Na kartě Revize vyberte místní nabídku (...) pro revizi, kterou chcete obnovit, a pak vyberte Provést aktuální a publikovat.

Resetování portálu

Pokud chcete zahodit všechny změny, které jste provedli na portálu pro vývojáře, můžete web obnovit do výchozího stavu. Resetováním portálu se odstraní všechny změny, které jste provedli na stránkách portálu pro vývojáře, rozložení, přizpůsobení a nahraném médiu.

Poznámka:

• Resetováním portálu pro vývojáře se neodstraní publikovaná verze portálu pro vývojáře.
• Resetováním portálu můžete portál aktualizovat na novější verzi základu kódu portálu pro vývojáře s aktualizovanými komponentami. Zástupný obsah, který se zobrazí, se může také změnit. Funkce portálu pro vývojáře a možnosti přizpůsobení zůstávají konzistentní.

Resetování portálu pro vývojáře:

1. V rozhraní pro správu v nabídce na levé straně editoru vizuálů vyberte Nastavení.
2. Na kartě Upřesnit vyberte Ano, obnovte web do výchozího stavu.
3. Zvolte Uložit.

Portály pro správu API a centrum API

Služby Azure API Management a azure API Center poskytují portály pro vývojáře ke zjišťování a využívání rozhraní API:

• Portál pro vývojáře API Management umožňuje uživatelům najít spravovaná rozhraní API, zjistit, jak je používat, požádat o přístup a otestovat je.
• Portál API Center (Preview) je portál s více bránami, kde můžou uživatelé zjišťovat a filtrovat kompletní inventář rozhraní API organizace.

I když tyto dva portály sdílejí některé funkce, mají také odlišné rozdíly. Následující tabulka porovnává aktuální možnosti a pomáhá určit, který portál se má použít. Některé organizace můžou preferovat jeden portál, zatímco jiné můžou potřebovat obojí.

Vlastnost	Portál pro vývojáře služby API Management	Portál API Center (náhled)
Vyhledávání a filtrování inventáře rozhraní API	Pouze instance služby API Management	Všechna rozhraní API1
Zobrazení podrobností a definic rozhraní API	✔️	✔️
Zobrazit dokumentaci k rozhraní API	✔️	✔️
Přizpůsobení podle brandingu	✔️	Pouze název
Integrace s Microsoft Entra ID	✔️	✔️
Přidání vlastních widgetů	✔️	❌
Přizpůsobení pomocí WordPressu	✔️	❌
Testujte rozhraní API v testovací konzoli	✔️	✔️
Přihlásit se k odběru rozhraní API	✔️	❌
Zobrazení analýzy využití rozhraní API	✔️	❌

¹ portál API Center může obsahovat všechna rozhraní API ve vaší organizaci, včetně rozhraní API spravovaných ve službě Azure API Management a dalších platforem, stejně jako nespravovaných rozhraní API a rozhraní API v rámci vývoje.

Související obsah

Další informace o portálu pro vývojáře:

• Přístup a přizpůsobení spravovaného portálu pro vývojáře
• Rozšíření funkcí spravovaného portálu pro vývojáře
• Povolení protokolování využití portálu pro vývojáře
• Nastavení místní verze portálu

Procházet další zdroje informací:

• Úložiště GitHub se zdrojovým kódem
• Nejčastější dotazy k portálu pro vývojáře