Az Azure API Management fejlesztői portál áttekintéseAzure API Management developer portal overview

A fejlesztői portál egy automatikusan létrehozott, teljesen testreszabható webhely, amely az API-k dokumentációját tartalmazza.Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. Ahol az API-felhasználók felfedezhetik az API-kat, megtudhatják, hogyan használhatják őket, hozzáférést igényelhetnek, és kipróbálhatja őket.It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

Ez a cikk a API Management fejlesztői portál saját üzemeltetésű és felügyelt verziói közötti különbségeket ismerteti.This article describes the differences between self-hosted and managed versions of the developer portal in API Management. Emellett ismerteti az architektúráját, és választ ad a gyakori kérdésekre.It also explains its architecture and provides answers to frequently asked questions.

API Management fejlesztői portál

Rendelkezésre állásAvailability

Fontos

Ez a funkció a API Management prémium, standard, alapszintű és fejlesztői szintjein érhető el.This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Felügyelt és saját üzemeltetésű verziókManaged and self-hosted versions

A fejlesztői portált kétféleképpen is létrehozhatja:You can build your developer portal in two ways:

  • Felügyelt verzió – a portál szerkesztésével és testreszabásával, amely a API Management-példányba van beépítve, <your-api-management-instance-name>.developer.azure-api.netés az URL-címen keresztül érhető el.Managed version - by editing and customizing the portal, which is built into your API Management instance and is accessible through the URL <your-api-management-instance-name>.developer.azure-api.net. A jelen dokumentációs cikkből megtudhatja, hogyan érheti el és szabhatja testre a felügyelt portált.Refer to this documentation article to learn how to access and customize the managed portal.
  • Saját üzemeltetésű verzió – a portál API Management-példányon kívüli üzembe helyezésével és önálló üzemeltetésével.Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. Ezzel a módszerrel szerkesztheti a portált, és kiterjesztheti a megadott alapfunkciókat – például egyéni widgeteket valósíthat meg a külső rendszerekkel való integrációhoz.This approach allows you to edit the portal's codebase and extend the provided core functionality - for example, implement custom widgets for integrations with third party systems. Ebben az esetben Ön a portál karbantartója, és Ön felelős a portál legújabb verzióra való frissítéséhez.In this scenario, you are the portal's maintainer and you are responsible for upgrading the portal to the latest version. A részletekért és az utasításokért tekintse meg a GitHub-tárházat a portál forráskódját és a widget megvalósítását ismertető oktatóanyagot.For details and instructions, refer to the GitHub repository with the source code of the portal and the tutorial on implementing a widget. A felügyelt verzióhoz tartozó oktatóanyag végigvezeti a portál felügyeleti paneljén, amely a felügyelt és a saját üzemeltetésű verziók esetében gyakori.The tutorial for the managed version walks through the portal's administrative panel, which is common for the managed and the self-hosted versions.

Portál építészeti fogalmakPortal architectural concepts

A portál összetevői logikailag két kategóriába sorolhatók: kód és tartalom.The portal components can be logically divided into two categories: code and content.

A kód a GitHub-tárházban van fenntartva, és a következőket tartalmazza:Code is maintained in the GitHub repository and includes:

  • Widgetek – amelyek vizuális elemeket és HTML-, JavaScript-, formázási képességeket, beállításokat és tartalom-hozzárendelést képviselnek.Widgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. Ilyenek például a képek, a szöveges bekezdések, az űrlapok, az API-k listája stb.Examples are an image, a text paragraph, a form, a list of APIs etc.
  • Formázási definíciók – a widgetek stílusának meghatározásaStyling definitions - which specify how widgets can be styled
  • Motor – amely statikus weblapokat hoz létre a portál tartalmából, és JavaScript nyelven íródottEngine - which generates static webpages from portal content and is written in JavaScript
  • Vizuális szerkesztő – lehetővé teszi a böngészőn belüli testreszabást és a szerzői műveletek elvégzésétVisual editor - which allows for in-browser customization and authoring experience

A tartalom két alkategóriára oszlik: a portál tartalma és a API Management tartalma.Content is divided into two subcategories: portal content and API Management content.

A portál tartalma a portálra vonatkozik, és a következőket tartalmazza:Portal content is specific to the portal and includes:

  • Lapok – például Kezdőlap, API-oktatóanyagok, blogbejegyzésekPages - for example, landing page, API tutorials, blog posts
  • Média – képek, animációk és egyéb fájl alapú tartalmakMedia - images, animations, and other file-based content
  • Elrendezések – sablonok, amelyek megfelelnek egy URL-címnek, és megadják a lapok megjelenítésének módjátLayouts - templates, which are matched against a URL and define how pages are displayed
  • Stílusok – a formázási definíciók értékei, például betűtípusok, színek, szegélyekStyles - values for styling definitions, e.g. fonts, colors, borders
  • Beállítások – konfiguráció, például favicon, webhely metaadatainakSettings - configuration, e.g. favicon, website metadata

A portál tartalma, a média kivételével, JSON-dokumentumként van megadva.Portal content, except for media, is expressed as JSON documents.

API Management tartalom olyan entitásokat tartalmaz, mint az API-k, a műveletek, a termékek és az előfizetések.API Management content includes entities such as APIs, Operations, Products, Subscriptions.

A portál a Paperbits-keretrendszeradaptált villáján alapul.The portal is based on an adapted fork of the Paperbits framework. Az eredeti Paperbits funkció ki lett bővítve API Management-specifikus widgetek (például az API-k listája, a termékek listája) és egy összekötő API Management szolgáltatás számára a tartalom mentéséhez és lekéréséhez.The original Paperbits functionality has been extended to provide API Management-specific widgets (for example, a list of APIs, a list of Products) and a connector to API Management service for saving and retrieving content.

Gyakori kérdésekFrequently asked questions

Ebben a szakaszban a fejlesztői portál általános jellegű kérdéseit választjuk.In this section, we answer common questions about the developer portal, which are of general nature. A saját üzemeltetésű verzióra vonatkozó kérdésekért tekintse meg a GitHub-adattár wiki szakaszát.For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

Hogyan lehet áttérni a portál előzetes verziójáról? How can I migrate from the preview version of the portal?

A fejlesztői portál előzetes verziójának használatával kiépített egy előnézeti tartalmat a API Management szolgáltatásban.By using the preview version of the developer portal, you provisioned the preview content in your API Management service. Az alapértelmezett tartalom jelentősen módosult az általánosan elérhető verzióban a jobb felhasználói élmény érdekében.The default content has been significantly modified in the generally available version for better user experience. Emellett új widgeteket is tartalmaz.It also includes new widgets.

Ha felügyelt verziót használ, állítsa alaphelyzetbe a portál tartalmát az Operations ( tartalom visszaállítása ) lehetőségre kattintva.If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. A művelet megerősítése eltávolítja a portál összes tartalmát, és kiépíti az új alapértelmezett tartalmat.Confirming this operation will remove all the content of the portal and provision the new default content. A portál motorja automatikusan frissült a API Management szolgáltatásban.The portal's engine has been automatically updated in your API Management service.

Portál tartalmának visszaállítása

Ha a saját üzemeltetésű verziót használja, a scripts/cleanup.bat és scripts/generate.bat a GitHub-tárházból távolítsa el a meglévő tartalmakat, és hozzon létre új tartalmat.If you're using the self-hosted version, use the scripts/cleanup.bat and scripts/generate.bat from the GitHub repository to remove existing content and provision new content. Győződjön meg róla, hogy a legújabb kiadásra frissíti a portál kódját a GitHub-adattárból.Make sure you upgrade your portal's code to the latest release from the GitHub repository beforehand.

Ha nem szeretné alaphelyzetbe állítani a portál tartalmát, érdemes lehet az újonnan elérhető widgeteket használni az összes oldalon.If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. A meglévő widgetek automatikusan frissültek a legújabb verzióra.Existing widgets have been automatically updated to the latest versions.

Ha a portál az általános elérhetőségi bejelentés után lett kiépítve, akkor már az új alapértelmezett tartalmat is be kell építenie.If your portal was provisioned after the general availability announcement, it should already feature the new default content. Az oldaláról nincs szükség beavatkozásra.No action is required from your side.

Hogyan telepíthetek át a régi fejlesztői portálról a fejlesztői portálra?How can I migrate from the old developer portal to the developer portal?

A portálok nem kompatibilisek, és manuálisan kell áttelepíteni a tartalmat.Portals are incompatible and you need to migrate the content manually.

A portál rendelkezik a régi portál összes szolgáltatásával?Does the portal have all the features of the old portal?

A fejlesztői portál már nem támogatja az alkalmazásokat és a problémákat.The developer portal no longer supports Applications and Issues.

Az interaktív Fejlesztői konzolon az OAuth-mel való hitelesítés még nem támogatott.Authentication with OAuth in the interactive developer console is not yet supported. Az előrehaladás nyomon követhető a GitHub-problémahasználatával.You can track the progress through the GitHub issue.

Elavult a régi portál?Has the old portal been deprecated?

A régi fejlesztői és közzétevői portálok már örökölt funkciók – csak a biztonsági frissítéseket kapják meg.The old developer and publisher portals are now legacy features - they will be receiving security updates only. Az új szolgáltatások csak az új fejlesztői portálon lesznek implementálva.New features will be implemented in the new developer portal only.

Az örökölt portálok elavulása külön lesz bejelentve.Deprecation of the legacy portals will be announced separately. Ha kérdése, problémája vagy megjegyzése van, emelje fel őket egy dedikált GitHub-problémával.If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

A portálon nem támogatottak a szükséges funkciókFunctionality I need isn't supported in the portal

Megnyithat egy szolgáltatási kérelmet , vagy saját maga is megvalósíthatja a hiányzó funkciókat.You can open a feature request or implement the missing functionality yourself. Ha saját maga hajtja végre a funkciót, a fejlesztői portált saját maga is futtathatja, vagy megnyithatja a GitHubon a lekéréses kérelmet, hogy tartalmazza a kezelt verzióban történt módosításokat.If you implement the functionality yourself, you can either self-host the developer portal or open a pull request on GitHub to include the changes in the managed version.

Hogyan automatizálható a portál üzembe helyezése?How can I automate portal deployments?

A REST API keresztül programozott módon érheti el és kezelheti a fejlesztői portál tartalmát, függetlenül attól, hogy felügyelt vagy saját üzemeltetésű verziót használ-e.You can programmatically access and manage the developer portal's content through the REST API, regardless if you're using a managed or a self-hosted version.

Az API-t a GitHub-adattár wiki szakasza ismerteti.The API is documented in the GitHub repository's wiki section. A portál tartalmának a környezetek közötti áttelepítésének automatizálására is használható – például egy tesztkörnyezetben az éles környezetbe.It can be used for automating migrations of portal content between environments - for example, from a test environment to the production environment. Erről a folyamatról a GitHubról szóló cikkben olvashat bővebben.You can learn more about this process in this documentation article on GitHub.

Támogatja a portál a Azure Resource Manager sablonokat, és/vagy kompatibilis-e a API Management DevOps Resource Kit-vel?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

Nem.No.

Engedélyezni kell további VNet-kapcsolatot a felügyelt portál függőségeihez?Do I need to enable additional VNet connectivity for the managed portal dependencies?

A legtöbb esetben – nem.In most cases - no.

Ha a API Management szolgáltatás belső VNet található, a fejlesztői portál csak a hálózaton belülről érhető el.If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. A felügyeleti végpont állomásneve fel kell oldania a szolgáltatás belső VIP-címére a portál felügyeleti felületének elérésére használt gépről.The management endpoint's host name must resolve to the internal VIP of the service from the machine you use to access the portal's administrative interface. Győződjön meg arról, hogy a felügyeleti végpont regisztrálva van a DNS-ben.Make sure the management endpoint is registered in the DNS. Helytelen konfiguráció esetén a következő hibaüzenet jelenik meg: Unable to start the portal. See if settings are specified correctly in the configuration (...).In case of misconfiguration, you will see an error: Unable to start the portal. See if settings are specified correctly in the configuration (...).

Ha a API Management szolgáltatás belső VNet van, és az internetről Application Gateway keresztül fér hozzá, ügyeljen arra, hogy engedélyezze a kapcsolatot a fejlesztői portálon és a API Management felügyeleti végpontján.If your API Management service is in an internal VNet and you're accessing it through Application Gateway from the Internet, make sure to enable connectivity to the developer portal and the management endpoints of API Management.

Egyéni API Management tartományt rendeltem hozzá, és a közzétett portál nem működikI have assigned a custom API Management domain and the published portal doesn't work

A tartomány frissítése után újra közzé kell tennie a portált , hogy a módosítások életbe lépnek.After you update the domain, you need to republish the portal for the changes to take effect.

Felvettem egy identitás-szolgáltatót, és nem látom a portálonI have added an identity provider and I can't see it in the portal

Miután konfigurálta az identitás-szolgáltatót (például HRE, AAD B2C), újra közzé kell tennie a portált , hogy a módosítások életbe lépnek.After you configure an identity provider (for example, AAD, AAD B2C), you need to republish the portal for the changes to take effect.

Beállítottam a delegálást, és a portál nem használjaI have set up delegation and the portal doesn't use it

A delegálás beállítása után újra közzé kell tennie a portált , hogy a módosítások életbe lépnek.After you set up delegation, you need to republish the portal for the changes to take effect.

A többi API Management konfiguráció módosítása nem lett propagálva a fejlesztői portálonMy other API Management configuration changes haven't been propagated in the developer portal

A legtöbb konfigurációs módosítás (például a VNet, a bejelentkezés és a termék kifejezés) a portál újbóli közzétételétigényli.Most configuration changes (for example, VNet, sign-in and product terms) require republishing the portal.

CORS hibaüzenetet kapok az interaktív konzol használatakorI'm getting a CORS error when using the interactive console

Az interaktív konzol ügyféloldali API-kérést tesz elérhetővé a böngészőből.The interactive console makes a client-side API request from the browser. Javítsa ki a CORS-problémát úgy, hogy hozzáad egy CORS-szabályzatot az API (ok) hoz.Resolve the CORS problem by adding a CORS policy on your API(s).

A CORS szabályzat állapotát a Azure Portal API Management szolgáltatásának portál áttekintés szakaszában tekintheti meg.You can check the status of the CORS policy in the Portal overview section of your API Management service in the Azure portal. A figyelmeztetési mező egy hiányzó vagy helytelenül konfigurált szabályzatot jelez.A warning box indicates an absent or misconfigured policy.

API Management fejlesztői portál

A CORS házirend automatikus alkalmazása a CORS engedélyezése gombra kattintva.Automatically apply the CORS policy by clicking on the Enable CORS button.

A CORS is engedélyezheti manuálisan is.You can also enable CORS manually.

  1. Kattintson a manuálisan alkalmazza a globális szinten hivatkozásra a generált szabályzat megjelenítéséhez.Click on the Manually apply it on the global level link to see the generated policy code.
  2. A Azure Portal a API Management szolgáltatás API -k szakaszában navigáljon az összes API -hoz.Navigate to All APIs in the APIs section of your API Management service in the Azure portal.
  3. Kattintson az </> ikonra a bejövő feldolgozás szakaszban.Click on the </> icon in the Inbound processing section.
  4. Szúrja be a szabályzatot az XML-fájl szakaszában.Insert the policy in the section of the XML file. Győződjön meg arról , hogy az érték megegyezik a fejlesztői portál tartományával.Make sure the value matches your developer portal's domain.

Megjegyzés

Ha a CORS szabályzatot a termék hatókörében alkalmazza, az API-k hatóköre helyett, és az API az előfizetés-kulcs hitelesítését használja egy fejlécen keresztül, a konzol nem fog működni.If you apply the CORS policy in the Product scope, instead of the API(s) scope, and your API uses subscription key authentication through a header, your console won't work.

A böngésző automatikusan kiadja a beállítások HTTP-kérését, amely nem tartalmaz az előfizetési kulccsal rendelkező fejlécet.The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. A hiányzó előfizetési kulcs miatt API Management nem tudja hozzárendelni a beállításokat a termékhez, így nem tudja alkalmazni a CORS házirendet.Because of the missing subscription key, API Management can't associate the OPTIONS call with a Product, so it can't apply the CORS policy.

Megkerülő megoldásként átadhatja az előfizetési kulcsot egy lekérdezési paraméterben.As a workaround you can pass the subscription key in a query parameter.

Milyen engedélyekre van szükségem a fejlesztői portál szerkesztéséhez?What permissions do I need to edit the developer portal?

Ha úgy látja a Oops. Something went wrong. Please try again later. hibát, amikor a portált felügyeleti módban nyitja meg, előfordulhat, hogy nem rendelkezik a szükséges engedélyekkel (RBAC).If you're seeing the Oops. Something went wrong. Please try again later. error when you open the portal in the administrative mode, you may be lacking the required permissions (RBAC).

Az örökölt portáloknak a Microsoft.ApiManagement/service/getssotoken/action szolgáltatás hatókörében (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) kell megadniuk az engedélyt ahhoz, hogy a felhasználói rendszergazda hozzáférjen a portálokhoz.The legacy portals required the permission Microsoft.ApiManagement/service/getssotoken/action at the service scope (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) to allow the user administrator access to the portals. Az új portálon engedély Microsoft.ApiManagement/service/users/token/action szükséges a hatókörben /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.The new portal requires the permission Microsoft.ApiManagement/service/users/token/action at the scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1.

A következő PowerShell-parancsfájl használatával létrehozhat egy szerepkört a szükséges engedélyekkel.You can use the following PowerShell script to create a role with the required permission. Ne felejtse el <subscription-id> módosítani a paramétert.Remember to change the <subscription-id> parameter.

#New Portals Admin Role 
Import-Module Az 
Connect-AzAccount 
$contributorRole = Get-AzRoleDefinition "API Management Service Contributor" 
$customRole = $contributorRole 
$customRole.Id = $null
$customRole.Name = "APIM New Portal Admin" 
$customRole.Description = "This role gives the user ability to log in to the new Developer portal as administrator" 
$customRole.Actions = "Microsoft.ApiManagement/service/users/token/action" 
$customRole.IsCustom = $true 
$customRole.AssignableScopes.Clear() 
$customRole.AssignableScopes.Add('/subscriptions/<subscription-id>') 
New-AzRoleDefinition -Role $customRole 

A szerepkör létrehozása után bármely felhasználó számára megadható a Azure Portal Access Control (iam) szakasza.Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Ha ezt a szerepkört hozzárendeli a felhasználóhoz, az engedélyt a szolgáltatás hatókörében kell kiosztania.Assigning this role to a user will assign the permission at the service scope. A felhasználó a szolgáltatás bármely felhasználója nevében képes sas-jogkivonatokat előállítani.The user will be able to generate SAS tokens on behalf of any user in the service. Legalább ezt a szerepkört a szolgáltatás rendszergazdájához kell rendelni.At the minimum, this role needs to be assigned to the administrator of the service. A következő PowerShell-parancs bemutatja, hogyan rendelhető hozzá a szerepkör a user1 legalacsonyabb hatókörű felhasználóhoz, hogy ne kelljen felesleges engedélyeket biztosítani a felhasználónak:The following PowerShell command demonstrates how to assign the role to a user user1 at the lowest scope to avoid granting unnecessary permissions to the user:

New-AzRoleAssignment -SignInName "user1@contoso.com" -RoleDefinitionName "APIM New Portal Admin" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>/users/1" 

Miután megadta az engedélyeket egy felhasználó számára, a felhasználónak ki kell jelentkeznie, majd újra be kell jelentkeznie a Azure Portal az új engedélyek érvénybe léptetéséhez.After the permissions have been granted to a user, the user must sign out and sign in again to the Azure portal for the new permissions to take effect.

Unable to start the portal. See if settings are specified correctly (...) Hibaüzenetet látokI'm seeing the Unable to start the portal. See if settings are specified correctly (...) error

Ez a hiba akkor jelenik meg GET , https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview ha sikertelen hívás történik.This error is shown when a GET call to https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview fails. A hívást a böngésző a portál felügyeleti felülete adja ki.The call is issued from the browser by the administrative interface of the portal.

Ha a API Management szolgáltatás VNet található – tekintse meg a fenti VNet-kapcsolat kérdését.If your API Management service is in a VNet - refer to the VNet connectivity question above.

A hívási hibát a TLS/SSL-tanúsítvány is okozhatja, amely egy egyéni tartományhoz van rendelve, és a böngésző nem tartja megbízhatónak.The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. Enyhítő megoldásként eltávolíthatja a felügyeleti végpont egyéni tartományát – API Management a megbízható tanúsítvánnyal rendelkező alapértelmezett végpontra kerül vissza.As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

Milyen böngésző-támogatást nyújt a portál?What's the browser support for the portal?

BöngészőBrowser TámogatottSupported
Apple SafariApple Safari Igen1Yes1
Google ChromeGoogle Chrome Igen1Yes1
Microsoft EdgeMicrosoft Edge Igen1Yes1
Microsoft Internet ExplorerMicrosoft Internet Explorer NemNo
Mozilla FirefoxMozilla Firefox Igen1Yes1

1 támogatott a két legújabb üzemi verzióban.1 Supported in the two latest production versions.

További lépésekNext steps

További információ az új fejlesztői portálról:Learn more about the new developer portal:

Egyéb erőforrások tallózása:Browse other resources: