Sdílet prostřednictvím

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

  • Článek

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

Snímek obrazovky portálu API Center po přihlášení uživatele

Informace o portálu API Center

Portál API Center je web, který můžete sestavit a hostovat a zobrazit inventář rozhraní API v centru rozhraní API. Portál umožňuje vývojářům a dalším zúčastněným stranám ve vaší organizaci zjišťovat rozhraní API a zobrazovat podrobnosti rozhraní API.

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á rozhraní API roviny dat Azure API Center k načtení dat z centra rozhraní API. Přístup uživatelů k informacím rozhraní API je založený na řízení přístupu na základě role v Azure.

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.

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:

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.

  1. Na webu Azure Portal přejděte na MICROSOFT Entra ID> Registrace aplikací.

  2. Vyberte + Nová registrace.

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

    • Nastavit název na smysluplný název, například api-center-portal

    • V části Podporované typy účtů vyberte Účty v tomto adresáři organizace (jeden tenant).

    • V identifikátoru URI přesměrování vyberte jednostránkové aplikace (SPA) a nastavte identifikátor URI.

      • Pro místní testování nastavte identifikátor URI na https://localhost:5173hodnotu .
      • V produkčním prostředí nastavte identifikátor URI na identifikátor URI nasazení portálu API Center.

    • Vyberte Zaregistrovat.

  4. Na stránce Přehled zkopírujte ID aplikace (klienta) a ID adresáře (tenanta). Tyto hodnoty nastavíte při vytváření portálu.

  5. Na stránce oprávnění rozhraní API vyberte + Přidat oprávnění.

    1. Na stránce Požádat o oprávnění rozhraní API vyberte rozhraní API, která moje organizace používá. Vyhledejte a vyberte Azure API Center. Můžete také vyhledat a vybrat ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573aplikace .
    2. Na stránce Požádat o oprávnění vyberte user_impersonation.
    3. Vyberte Přidat oprávnění.

    Oprávnění Azure API Center se zobrazí v části Nakonfigurovaná oprávnění.

    Snímek obrazovky s požadovanými oprávněními v registraci aplikace Microsoft Entra ID na portálu

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 public/config.example soubor na public/config.json.

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

    • Nahraďte <service name> a <region> nahraďte název vašeho centra rozhraní API a oblastí, ve které je nasazená.
    • Nahraďte <client ID> ID <tenant ID> aplikace (klienta) a ID adresáře (tenanta) registrace aplikace, kterou jste vytvořili v předchozí části.
    • Aktualizujte hodnotu title na název, který se má zobrazit na portálu.
    {
  "dataApiHostName": "<service name>.data.<region>.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 adrese 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

Uživatelé se musí přihlásit, aby se rozhraní API zobrazila ve vašem centru rozhraní API. Pokud chcete povolit přihlášení, přiřaďte uživatelům nebo skupinám ve vaší organizaci roli Čtenář dat v Centru rozhraní API, která je vymezená centrem rozhraní API.

Důležité

Ve výchozím nastavení nemáte vy a další správci centra rozhraní API 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:
    • Na stránce Role vyhledejte a vyberte Čtečku dat v Azure API Center. Vyberte Další.
    • Na stránce Členové v části Přiřadit přístup vyberte Uživatele, skupinu nebo instanční objekt>+ Vybrat členy.
    • Na stránce Vybrat členy vyhledejte a vyberte uživatele nebo skupiny, ke které chcete roli přiřadit. Klikněte na Vybrat a pak na Další.
    • 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 v Microsoft 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ému

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 je uživateli přiřazena role Čtenář dat v Centru rozhraní API.

Pokud má uživatel přiřazenou roli, může být problém s registrací poskytovatele prostředků Microsoft.ApiCenter 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 Čtenář dat ve službě Azure API Center, nemůžou po výběru možnosti Přihlásit se na portálu API Center dokončit tok přihlášení, 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í identifikátoru URI přesměrování, abyste zajistili, že identifikátor URI odpovídá identifikátoru URI nasazení portálu API Center.

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

Pokud nemůžete požádat o oprávnění rozhraní API ke službě Azure API Center v registraci aplikace Microsoft Entra na portálu SLUŽBY API Center, zkontrolujte, jestli hledáte Azure API Center (nebo ID c3ca1a77-7a87-4dba-b8f8-eea115ae4573aplikace).

Pokud aplikace není k dispozici, může být problém s registrací poskytovatele prostředků Microsoft.ApiCenter ve vašem předplatném. 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, žádosti o funkce a získejte podporu pro referenční implementaci portálu API Center v počátečním úložišti portálu API Center.

Související obsah