Samoobslužné hostování portálu Centra rozhraní API

Tento článek ukazuje, jak sami hostovat portál API Center, web, který můžou vývojáři a další účastníci ve vaší organizaci používat ke zjišťování rozhraní API v centru rozhraní API . Nasaďte referenční implementaci portálu z úvodního úložiště portálu API Center.

Návod

Nový! Teď můžete nastavit verzi portálu API Center spravovanou v Azure. Další informace najdete v tématu Nastavení portálu API Center.

Informace o vlastním hostování portálu

Referenční implementaci portálu můžete sestavit a nasadit pomocí kódu v počátečním úložišti portálu API Center. Portál používá Azure API Center data plane API k načtení dat z vašeho centra rozhraní API.

Referenční implementace portálu API Center poskytuje:

• Architektura pro publikování a údržbu portálu rozhraní API spravovaného zákazníkem pomocí GitHub Actions
• Portálová platforma, kterou můžou zákazníci upravit nebo rozšířit tak, aby vyhovovala jejich potřebám
• Flexibilita hostování v různých infrastrukturách, včetně nasazení do služeb, jako je Azure Static Web Apps.

Poznámka:

Když portál API Center hostujete sami, stanete se jeho správcem a zodpovídáte za jeho upgrady. Podpora Azure je omezená.

Požadavky

• Centrum rozhraní API ve vašem předplatném Azure. Pokud jste ho ještě nevytvořili, přečtěte si článek Rychlý start: Vytvoření centra rozhraní API.

• Oprávnění k vytvoření registrace aplikace v tenantovi Microsoft Entra přidruženém k vašemu předplatnému Azure a oprávnění k udělení přístupu k datům ve vašem centru rozhraní API.

• K sestavení a nasazení portálu potřebujete účet GitHub a následující nástroje nainstalované na místním počítači:

  • Node.js a npm
  • balíček Vite

Vytvoření registrace aplikace Microsoft Entra

Nejprve nakonfigurujte registraci aplikace v tenantovi Microsoft Entra ID. Registrace aplikace umožňuje portálu API Center přistupovat k datům z centra rozhraní API jménem přihlášeného uživatele.

Centrum API může registraci aplikace nastavit automaticky nebo můžete registraci aplikace vytvořit ručně.

Automatické nastavení registrace aplikace

Pokud chcete registraci aplikace nastavit automaticky, postupujte takto:

1. Na webu Azure Portal přejděte do centra rozhraní API.
2. V nabídce vlevo vyberteNastavení> API Center.
3. Na kartě zprostředkovatele identity vyberte Zahájit nastavení.
4. Na kartě Rychlé nastavení vyberte Uložit a publikovat.

Pokud potřebujete později získat přístup k registraci aplikace, najdete ji na portálu v části Registrace aplikací. Aplikace má následující formát: <api-center-name-apic-aad>.

Ruční nastavení registrace aplikace

Pokud chcete registraci aplikace vytvořit ručně, postupujte takto:

1. Na webu Azure Portal přejděte do části Správaregistrací aplikací>>.

2. Vyberte + Nová registrace.

3. Na stránce Zaregistrovat aplikaci nastavte hodnoty následujícím způsobem:

   1. Nastavte Název na smysluplný název, například api-center-portal
   2. V části Podporované typy účtů vyberte Účty pouze v tomto adresáři organizace (<název> adresáře – jeden tenant).
   3. V URI přesměrovánívyberte jednostránkovou aplikaci (SPA) a nastavte URI. Zadejte identifikátor URI nasazení portálu API Center v následujícím formátu: https://<service-name>.portal.<location>.azure-apicenter.ms. Nahraďte <service name> a <location> názvem centra rozhraní API a umístěním, kam je nasazený, příklad: https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Vyberte Zaregistrovat.

Konfigurace dalších identifikátorů URI přesměrování pro rozšíření VS Code

Při povolování zobrazení portálu API Center v rozšíření Visual Studio Code pro api Center nakonfigurujte také následující identifikátory URI přesměrování v registraci aplikace:

1. Na webu Azure Portal přejděte k registraci aplikace.

2. Na stránce Spravovat>ověřování vyberte Přidat platformu a vyberte Mobilní a desktopové aplikace.

3. Nakonfigurujte následující tři vlastní adresy URL pro přesměrování:
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Nahraďte <application-client-id> ID klienta této aplikace. Tuto hodnotu najdete na stránce Přehled registrace aplikace.

Poznámka:

Pokud portál hostujete sami a chcete ho před nasazením do Azure otestovat místně, nastavte identifikátor URI přesměrování v registraci aplikace na https://localhost:5173.

Konfigurace místního prostředí

Podle těchto kroků sestavte a otestujte místně portál API Center.

1. Naklonujte počáteční úložiště portálu API Center do místního počítače.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. Přejděte do APICenter-Portal-Starter adresáře.

   cd APICenter-Portal-Starter
   

3. Podívejte se na hlavní větev.

   git checkout main
   

4. Chcete-li nakonfigurovat službu, zkopírujte nebo přejmenujte soubor public/config.example na public/config.json.

5. Potom upravte soubor public/config.json tak, aby odkazovat na vaši službu. Aktualizujte hodnoty v souboru následujícím způsobem:

   1. Nahraďte <service name> a <location> názvem centra rozhraní API a umístěním, kde je nasazená.
   2. Nahraďte <client ID> a <tenant ID> ve své registraci aplikace ID aplikace (klienta) a ID adresáře (tenanta) , kterou jste vytvořili v předchozí části.
   3. Aktualizujte hodnotu title na název, který se má zobrazit v horním panelu portálu.

   {
     "dataApiHostName": "<service name>.data.<location>.azure-apicenter.ms/workspaces/default",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/user_impersonation"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. Nainstalujte požadované balíčky.

   npm install
   

7. Spusťte vývojový server. Následující příkaz spustí portál v místním režimu vývoje:

   npm start
   

   Přejděte na portál na https://localhost:5173.

Nasazení do Azure

Postup nasazení portálu do Azure Static Web Apps najdete v úvodním úložišti portálu API Center.

Povolení přihlášení k portálu uživateli a skupinami Microsoft Entra

Pokud chcete povolit přihlášení k portálu SLUŽBY API Center pro přístup k rozhraním API, přiřaďte uživatelům nebo skupinám ve vaší organizaci roli Čtenář dat služby Azure API Center , která je vymezená na centrum rozhraní API.

Důležité

Ve výchozím nastavení se vy a další správci centra rozhraní API musíte přihlásit, abyste měli přístup k rozhraním API na portálu API Center. Nezapomeňte přiřadit roli Čtenář dat ve službě Azure API Center sobě a dalším správcům.

Podrobné požadavky a kroky pro přiřazení role uživatelům a skupinám najdete v tématu Přiřazení rolí Azure pomocí webu Azure Portal. Stručné kroky:

1. Na webu Azure Portal přejděte do centra rozhraní API.
2. V nabídce vlevo vyberte Řízení přístupu (IAM)>+ Přidat přiřazení role.
3. V podokně Přidat přiřazení role nastavte hodnoty následujícím způsobem:
   1. Na stránce Role vyhledejte a vyberte Čtečku dat Azure API Center. Vyberte Další.
   2. Na stránce Členové v části Přiřadit přístup k vyberte Uživatele, skupinu nebo instanční objekt>+ Vybrat členy.
   3. Na stránce Vyberte členy vyhledejte a vyberte uživatele nebo skupiny, ke kterému chcete roli přiřadit. Klikněte na Vybrat a pak na Další.
   4. Zkontrolujte přiřazení role a vyberte Zkontrolovat a přiřadit.

Poznámka:

Pokud chcete zjednodušit konfiguraci přístupu pro nové uživatele, doporučujeme přiřadit roli skupině Microsoft Entra a nakonfigurovat pravidlo dynamického členství ve skupině. Další informace najdete v tématu Vytvoření nebo aktualizace dynamické skupiny vMicrosoft Entra ID .

Po nakonfigurování přístupu k portálu se nakonfigurovaní uživatelé můžou přihlásit k portálu a zobrazit rozhraní API v centru rozhraní API.

Poznámka:

První uživatel, který se přihlásí k portálu, se zobrazí výzva k vyjádření souhlasu s oprávněními požadovanými registrací aplikace portálu API Center. Další nakonfigurovaní uživatelé pak nebudou vyzváni k vyjádření souhlasu.

Řešení problémů

Chyba: Nemáte oprávnění k přístupu k tomuto portálu

Za určitých podmínek se uživateli může po přihlášení k portálu API Center s nakonfigurovaným uživatelským účtem zobrazit následující chybová zpráva:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Nejprve ověřte, že má uživatel přiřazenou roli Data Readeru služby Azure API Center ve vašem centru rozhraní API.

Pokud je uživateli přiřazena role, může dojít k potížím s registrací Microsoft.ApiCenter poskytovatele prostředků ve vašem předplatném a možná budete muset poskytovatele prostředků znovu zaregistrovat. Provedete to spuštěním následujícího příkazu v Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Nejde se přihlásit k portálu

Pokud uživatelé, kteří mají přiřazenou roli Azure API Center Data Reader, nemůžou dokončit tok přihlášení po výběru přihlášení na portálu API Center, může dojít k potížím s konfigurací zprostředkovatele identity Microsoft Entra ID.

V registraci aplikace Microsoft Entra zkontrolujte a v případě potřeby aktualizujte nastavení přesměrovacího identifikátoru URI, aby tento identifikátor URI odpovídal URI nasazení portálu API Center.

V registraci aplikace Microsoft Entra nejde vybrat oprávnění azure API Center

Pokud nemůžete v registraci aplikace Microsoft Entra požádat o oprávnění k rozhraní API pro Azure API Center na portálu API Center, zkontrolujte, zda hledáte Azure API Center (nebo ID aplikace c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Pokud aplikace není přítomna, může nastat problém s registrací poskytovatele prostředků Microsoft.ApiCenter v rámci vašeho předplatného. Možná budete muset poskytovatele prostředků znovu zaregistrovat. Provedete to spuštěním následujícího příkazu v Azure CLI:

az provider register --namespace Microsoft.ApiCenter

Po opětovné registraci poskytovatele prostředků zkuste znovu požádat o oprávnění rozhraní API.

Zásady podpory

Poskytněte zpětnou vazbu, požádejte o funkce a získejte podporu pro referenční implementaci portálu API Center v úvodním úložišti portálu API Center.

Související obsah

• Nastavení portálu API Center
• Co je řízení přístupu na základě role (RBAC) v Azure?
• Osvědčené postupy pro Azure RBAC
• Registrace poskytovatele prostředků