Kurz: Použití a přizpůsobení nového vývojářského portálu

  • Článek

Portál pro vývojáře je automaticky generovaný plně přizpůsobitelný web s dokumentací vašich rozhraní API. V této lokalitě můžou uživatelé rozhraní API zjišťovat vaše rozhraní API, učit se je používat a požádat o přístup.

V tomto kurzu se naučíte:

  • Přístup ke spravované verzi portálu pro vývojáře
  • Navigace v rozhraní pro správu
  • Přizpůsobení obsahu
  • Publikování změn
  • Zobrazení publikovaného portálu

Další podrobnosti najdete na portálu pro vývojáře v přehledu portálu pro vývojáře služby Azure API Management.

Screenshot of the API Management developer portal - administrator mode.

Předpoklady

Dostupnost

Důležité

Tato funkce je dostupná na úrovních Premium, Standard, Basic a Developer služby API Management.

Dostupnost funkcí na úrovních v2 (Preview) najdete v přehledu úrovní v2.

Přístup k portálu jako správce

Pokud chcete získat přístup ke spravované verzi portálu, postupujte podle následujících kroků.

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

  2. Pokud jste instanci vytvořili na úrovni služby v2, která podporuje portál pro vývojáře, nejprve povolte portál pro vývojáře.

    1. V nabídce vlevo v části Portál pro vývojáře vyberte nastavení portálu.
    2. V okně nastavení portálu vyberte Povoleno. Zvolte Uložit.

    Povolení portálu pro vývojáře může trvat několik minut.

  3. V nabídce vlevo v části Portál pro vývojáře vyberte Přehled portálu. Pak na horním navigačním panelu vyberte tlačítko Portál pro vývojáře . Otevře se nová karta prohlížeče s verzí pro správu portálu.

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 obsah služby API Management.

Obsah portálu je specifický pro portál 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é se shodují s adresou URL a definují způsob zobrazení stránek

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

Obsah služby API Management zahrnuje entity, jako jsou rozhraní API, operace, produkty, předplatná.

Vysvětlení rozhraní pro správu portálu

Výchozí obsah

Pokud k portálu přistupujete poprvé, výchozí obsah se automaticky zřídí na pozadí. Výchozí obsah byl navržen tak, aby předváděl možnosti portálu a minimalizoval přizpůsobení potřebná k přizpůsobení portálu. Další informace o tom, co je součástí obsahu portálu, najdete v přehledu vývojářského portálu služby Azure API Management.

Vizuální editor

Obsah portálu můžete přizpůsobit pomocí editoru vizuálů.

  • Oddíly nabídek na levé straně umožňují vytvářet nebo upravovat stránky, média, rozložení, nabídky, styly nebo nastavení webu.
  • Položky nabídky v dolní části umožňují přepínat mezi oblastmi zobrazení (například mobilní nebo desktopové), zobrazit prvky portálu viditelné pro uživatele v různých skupinách nebo uložit nebo vrátit zpět akce.
  • Kliknutím na modrou ikonu se znaménkem plus přidejte oddíly na stránku.
  • Widgety (například text, obrázky nebo seznam rozhraní API) je možné přidat stisknutím šedé ikony se znaménkem plus.
  • Změňte uspořádání položek na stránce pomocí interakce přetažení myší.

Rozložení a stránky

Screenshot of the visual editor in the developer portal.

Rozložení definují způsob zobrazení stránek. Ve výchozím obsahu jsou například dvě rozložení: jedno platí pro domovskou stránku a druhé pro všechny zbývající stránky.

Rozložení se použije na stránku tím, že se shoduje se šablonou adresy URL stránky 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 předchozím obrázku je obsah, který patří do rozložení, označen modře, zatímco stránka je označená červeně. Oddíly nabídek jsou označené v uvedeném pořadí.

Průvodce styly

Screenshot of the styling guide in the developer portal.

Průvodce styly je panel vytvořený s ohledem na návrháře. Umožňuje řídit a stylizovat všechny vizuální prvky na portálu. 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 ikonu tužky, která se zobrazí nad ní. Po provedení změn v automaticky otevíraných otevíraných oknech ho zavřete.

Tlačítko Uložit

Screenshot of the Save button in the developer portal.

Kdykoli na portálu provedete změnu, musíte ji uložit ručně tak, že v nabídce dole vyberete tlačítko Uložit nebo stisknete [Ctrl]+[S]. Když změny uložíte, upravený obsah se automaticky nahraje do služby API Management.

Přizpůsobení obsahu portálu

Než zpřístupníte portál návštěvníkům, měli byste automaticky vygenerovaný obsah přizpůsobit. Mezi doporučené změny patří rozložení, styly a obsah domovské stránky. Určité prvky obsahu můžete zpřístupnit jenom vybraným uživatelům nebo skupinám.

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, , , /change-password/captcha, /confirm/invitation/config.json, /confirm-v2/identities/basic/signup, /publish/internal-status-0123456789abcdef/confirm-v2/password, /signin, , . /signin-sso/signup. .

Domovská stránka

Výchozí domovská stránka je vyplněna zástupným obsahem. Můžete buď odebrat celé oddíly obsahující tento obsah, nebo zachovat strukturu a upravit prvky o jeden po druhém. Vygenerovaný text a obrázky nahraďte vlastním textem a ujistěte se, že odkazy odkazují na požadovaná umístění. Strukturu a obsah domovské stránky můžete upravit pomocí následujících možností:

  • Přetažení prvků stránky na požadované umístění na webu
  • Výběr prvků textu a nadpisu pro úpravy a formátování obsahu
  • Ověření tlačítek ukazují na správná místa.

Rozložení

Nahraďte automaticky vygenerované logo na navigačním panelu vlastním obrázkem.

  1. Na portálu pro vývojáře vyberte v levém horním rohu navigačního panelu výchozí logo Contoso .
  2. Vyberte ikonu Upravit.
  3. V části Hlavní vyberte Zdroj.
  4. V automaticky otevíraných otevíraných oknech médií vyberte:
    • Obrázek, který jste už nahráli do knihovny, nebo
    • Nahrání souboru pro nahrání nového souboru obrázku, který chcete použít, nebo
    • Pokud chcete použít logo, vyberte Možnost Žádné .
  5. Logo se aktualizuje v reálném čase.
  6. Výběrem mimo automaticky otevíraná okna ukončete knihovnu médií.
  7. Klikněte na Uložit.

Formátování

I když nemusíte upravovat žádné styly, můžete zvážit úpravu konkrétních prvků. Změňte například primární barvu tak, aby odpovídala barvě vaší značky. Můžete to udělat dvěma způsoby:

Celkový styl webu

  1. Na portálu pro vývojáře vyberte na levém panelu nástrojů ikonu Styly .
  2. V části Barvy vyberte položku stylu barvy, kterou chcete upravit.
  3. Klikněte na ikonu Upravit pro tuto položku stylu.
  4. Vyberte barvu z nástroje pro výběr barev nebo zadejte šestnáctkový kód barvy.
  5. Kliknutím na Přidat barvu přidejte a pojmenujte jinou položku barvy.
  6. Klikněte na Uložit.

Styl kontejneru

  1. Na hlavní stránce portálu pro vývojáře vyberte pozadí kontejneru.
  2. Klikněte na ikonu Upravit .
  3. V automaticky otevíraných oknech nastavte:
    • Pozadí, které chcete vymazat, obrázek, určitou barvu nebo přechod.
    • Velikost kontejneru, okraj a odsazení.
    • Umístění a výška kontejneru
  4. Výběrem mimo automaticky otevíraná okna ukončete nastavení kontejneru.
  5. Klikněte na Uložit.

Viditelnost a řízení přístupu

Podle jejich identity můžete určit, který obsah portálu se zobrazuje různým uživatelům. 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 nebo upravíte stránku, vyberte kartu Přístup , abyste mohli řídit uživatele nebo skupiny, které mají přístup k této stránce.

    Screenshot of the page access control settings in the developer portal.

  • Když přizpůsobíte obsah stránky, jako je například oddíl stránky, nabídka nebo tlačítko, vyberte ikonu Změnit viditelnost , která řídí uživatele nebo skupiny, které vidí prvek na stránce.

    Screenshot of the change visibility button in the developer portal.

    • 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í, způsobí chybu 404 Nenalezena.

Tip

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ě tak , že v nabídce dole vyberete ikonu Zosobnit.

Příklad přizpůsobení

V následujícím videu si ukážeme, jak upravit obsah portálu, přizpůsobit vzhled webu a publikovat změny.

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 můžete publikovat v rozhraní pro správu portálu nebo na webu Azure Portal.

Publikování z rozhraní pro správu

  1. Vyberte ikonu Uložit a ujistěte se, že jste změny uložili.

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

    Screenshot of the Publish website button in the developer portal.

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.

    Publish portal from Azure portal

Poznámka:

Po změně konfigurace služby API Management je potřeba portál znovu publikovat. 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.

Navštivte publikovaný portál.

Po publikování portálu k němu můžete přistupovat na stejné adrese URL jako na panelu pro správu, například https://contoso-api.developer.azure-api.net. Můžete ho zobrazit v samostatné relaci prohlížeče (pomocí anonymního nebo privátního režimu procházení) jako externí návštěvník.

Použití zásad CORS na rozhraních API

Pokud chcete návštěvníkům portálu umožnit testování rozhraní API prostřednictvím integrované interaktivní konzoly, povolte CORS (sdílení prostředků mezi zdroji) ve vašich rozhraních API. Podrobnosti najdete v nejčastějších dotazech k portálu pro vývojáře služby Azure API Management.

Další kroky

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