Översikt över Azure API Management Developer-portalenAzure API Management developer portal overview

Developer Portal är en automatiskt genererad, helt anpassningsbar webbplats med dokumentationen för dina API: er.Developer portal is an automatically generated, fully customizable website with the documentation of your APIs. Det är där API-konsumenter kan identifiera dina API: er, lära sig hur de används, begära åtkomst och testa dem.It is where API consumers can discover your APIs, learn how to use them, request access, and try them out.

I den här artikeln beskrivs skillnaderna mellan egna värdbaserade och hanterade versioner av Developer-portalen i API Management.This article describes the differences between self-hosted and managed versions of the developer portal in API Management. Den förklarar också dess arkitektur och ger svar på vanliga frågor.It also explains its architecture and provides answers to frequently asked questions.

API Management Developer-portalen

TillgänglighetAvailability

Viktigt

Den här funktionen är tillgänglig på nivån Premium, standard, Basic och Developer för API Management.This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

Hanterade och egen värdbaserade versionerManaged and self-hosted versions

Du kan bygga din utvecklings Portal på två sätt:You can build your developer portal in two ways:

  • Hanterad version – genom att redigera och anpassa portalen, som är inbyggd i API Management-instansen och är tillgänglig <your-api-management-instance-name>.developer.azure-api.netvia URL: en.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. Läs den här dokumentations artikeln för att lära dig hur du får åtkomst till och anpassar den hanterade portalen.Refer to this documentation article to learn how to access and customize the managed portal.
  • Egen värd version – genom att distribuera och självbetjäning av portalen utanför en API Management-instans.Self-hosted version - by deploying and self-hosting your portal outside of an API Management instance. Med den här metoden kan du redigera portalens kodbas och utöka de tillhandahållna kärn funktionerna, till exempel implementera anpassade widgetar för integreringar med system från tredje part.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. I det här scenariot är du portalens underhållare och du ansvarar för att uppgradera portalen till den senaste versionen.In this scenario, you are the portal's maintainer and you are responsible for upgrading the portal to the latest version. Mer information och anvisningar finns i GitHub- lagringsplatsen med käll koden för portalen och självstudien om hur du implementerar en widget.For details and instructions, refer to the GitHub repository with the source code of the portal and the tutorial on implementing a widget. Självstudien för den hanterade versionen går igenom portalens administrations panel, som är gemensam för de hanterade och de egna värd versionerna.The tutorial for the managed version walks through the portal's administrative panel, which is common for the managed and the self-hosted versions.

Arkitektur koncept för portalenPortal architectural concepts

Portal komponenterna kan delas upp logiskt i två kategorier: kod och innehåll.The portal components can be logically divided into two categories: code and content.

Koden underhålls i GitHub-lagringsplatsen och inkluderar:Code is maintained in the GitHub repository and includes:

  • Widgetar – som representerar visuella element och kombinerar HTML, Java Script, format funktioner, inställningar och innehålls mappning.Widgets - which represent visual elements and combine HTML, JavaScript, styling ability, settings, and content mapping. Exempel är en bild, ett text stycke, ett formulär, en lista över API: er osv.Examples are an image, a text paragraph, a form, a list of APIs etc.
  • Format definitioner – som anger hur widgetar kan formaterasStyling definitions - which specify how widgets can be styled
  • Motor – som genererar statiska webb sidor från Portal innehåll och som är skrivet i Java ScriptEngine - which generates static webpages from portal content and is written in JavaScript
  • Visuell redigerare – som möjliggör anpassning och redigering i webbläsareVisual editor - which allows for in-browser customization and authoring experience

Innehållet är uppdelat i två under Kategorier: portal innehåll och API Management innehåll.Content is divided into two subcategories: portal content and API Management content.

Portal innehållet är särskilt för portalen och innehåller:Portal content is specific to the portal and includes:

  • Sidor – till exempel landnings sida, API-självstudier, blogg inläggPages - for example, landing page, API tutorials, blog posts
  • Media – bilder, animationer och annat filbaserat innehållMedia - images, animations, and other file-based content
  • Layout – mallar som matchas mot en URL och definierar hur sidor visasLayouts - templates, which are matched against a URL and define how pages are displayed
  • Stilar – värden för format definitioner, t. ex. teckensnitt, färger, kant linjerStyles - values for styling definitions, e.g. fonts, colors, borders
  • Inställningar – konfiguration, t. ex. favicon, webbplatsens metadataSettings - configuration, e.g. favicon, website metadata

Portal innehåll, förutom media, uttrycks som JSON-dokument.Portal content, except for media, is expressed as JSON documents.

API Management innehåll innehåller entiteter som API: er, åtgärder, produkter, prenumerationer.API Management content includes entities such as APIs, Operations, Products, Subscriptions.

Portalen baseras på en anpassad förgrening av Paperbits-ramverket.The portal is based on an adapted fork of the Paperbits framework. De ursprungliga Paperbits-funktionerna har utökats för att tillhandahålla API Management-/regionsspecifika widgetar (till exempel en lista över API: er, en lista över produkter) och en koppling till API Management tjänsten för att spara och hämta innehåll.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.

Vanliga frågor och svarFrequently asked questions

I det här avsnittet svarar vi på vanliga frågor om Developer-portalen, som är av allmän natur.In this section, we answer common questions about the developer portal, which are of general nature. För frågor som är speciella för den självbetjänings versionen, se wiki-avsnittet i GitHub-lagringsplatsen.For questions specific to the self-hosted version, refer to the wiki section of the GitHub repository.

Hur kan jag migrera från för hands versionen av portalen? How can I migrate from the preview version of the portal?

Med hjälp av för hands versionen av Developer-portalen etablerade du att förhands gransknings innehållet i API Managements tjänsten.By using the preview version of the developer portal, you provisioned the preview content in your API Management service. Standard innehållet har ändrats avsevärt i den allmänt tillgängliga versionen för bättre användar upplevelse.The default content has been significantly modified in the generally available version for better user experience. Den innehåller också nya widgetar.It also includes new widgets.

Om du använder den hanterade versionen återställer du portalens innehåll genom att klicka på Återställ innehåll i menyn åtgärder .If you're using the managed version, reset the content of the portal by clicking Reset content in the Operations menu section. Om du bekräftar åtgärden tas allt innehåll i portalen bort och det nya standard innehållet etableras.Confirming this operation will remove all the content of the portal and provision the new default content. Portalens motor har uppdaterats automatiskt i din API Management-tjänst.The portal's engine has been automatically updated in your API Management service.

Återställ Portal innehåll

Om du använder den själv värdbaserade versionen använder du scripts/cleanup.bat och scripts/generate.bat från GitHub-lagringsplatsen för att ta bort befintligt innehåll och etablera nytt innehåll.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. Se till att du uppgraderar din portal kod till den senaste versionen från GitHub-databasen i förväg.Make sure you upgrade your portal's code to the latest release from the GitHub repository beforehand.

Om du inte vill återställa portalens innehåll kan du överväga att använda nyligen tillgängliga widgetar på alla sidor.If you don't want to reset the content of the portal, you may consider using newly available widgets throughout your pages. Befintliga widgetar har uppdaterats automatiskt till de senaste versionerna.Existing widgets have been automatically updated to the latest versions.

Om portalen etablerades efter det allmänna tillgänglighets meddelandet bör den redan ha det nya standard innehållet.If your portal was provisioned after the general availability announcement, it should already feature the new default content. Ingen åtgärd krävs från din sida.No action is required from your side.

Hur kan jag migrera från den gamla Developer-portalen till Developer-portalen?How can I migrate from the old developer portal to the developer portal?

Portalerna är inkompatibla och du måste migrera innehållet manuellt.Portals are incompatible and you need to migrate the content manually.

Har portalen alla funktioner från den gamla portalen?Does the portal have all the features of the old portal?

Developer-portalen stöder inte längre program och problem.The developer portal no longer supports Applications and Issues.

Autentisering med OAuth i den interaktiva Developer-konsolen stöds inte ännu.Authentication with OAuth in the interactive developer console is not yet supported. Du kan följa förloppet genom GitHub-problemet.You can track the progress through the GitHub issue.

Har den gamla portalen föråldrats?Has the old portal been deprecated?

De gamla portarna för utvecklare och utgivare är nu äldre funktioner – de kommer endast att ta emot säkerhets uppdateringar.The old developer and publisher portals are now legacy features - they will be receiving security updates only. Nya funktioner kommer endast att implementeras i den nya Developer-portalen.New features will be implemented in the new developer portal only.

Utfasningen av äldre portaler kommer att meddelas separat.Deprecation of the legacy portals will be announced separately. Om du har frågor, rör eller kommentarer kan du höja dem i ett dedikerat GitHub-problem.If you have questions, concerns, or comments, raise them in a dedicated GitHub issue.

Funktioner jag behöver stöds inte i portalenFunctionality I need isn't supported in the portal

Du kan öppna en funktions förfrågan eller implementera de funktioner som saknas själv.You can open a feature request or implement the missing functionality yourself. Om du implementerar funktionerna själv, kan du antingen själv vara värd för Developer-portalen eller öppna en pull-begäran på GitHub för att inkludera ändringarna i den hanterade versionen.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.

Hur kan jag automatisera Portal distributioner?How can I automate portal deployments?

Du kan program mässigt komma åt och hantera Developer portalens innehåll via REST API, oavsett om du använder en hanterad eller en egen version.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.

API: et finns dokumenterat i GitHub-lagringsplatsens wiki-avsnitt.The API is documented in the GitHub repository's wiki section. Den kan användas för att automatisera migrering av Portal innehåll mellan miljöer, till exempel från en test miljö till produktions miljön.It can be used for automating migrations of portal content between environments - for example, from a test environment to the production environment. Du kan lära dig mer om den här processen i den här dokumentations artikeln på GitHub.You can learn more about this process in this documentation article on GitHub.

Stöder portalen Azure Resource Manager mallar och/eller är den kompatibel med API Management DevOps Resource Kit?Does the portal support Azure Resource Manager templates and/or is it compatible with API Management DevOps Resource Kit?

Nej.No.

Måste jag aktivera ytterligare VNet-anslutning för de hanterade portalernas beroenden?Do I need to enable additional VNet connectivity for the managed portal dependencies?

I de flesta fall – nej.In most cases - no.

Om din API Management-tjänst finns i ett internt virtuellt nätverk är din utvecklings Portal bara tillgänglig i nätverket.If your API Management service is in an internal VNet, your developer portal is only accessible from within the network. Värd namnet för hanterings slut punkten måste matcha den interna VIP för tjänsten från den dator som du använder för att få åtkomst till portalens administrations gränssnitt.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. Kontrol lera att hanterings slut punkten är registrerad i DNS.Make sure the management endpoint is registered in the DNS. I händelse av fel konfiguration visas ett fel meddelande: 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 (...).

Om din API Management-tjänst finns i ett internt virtuellt nätverk och du har åtkomst till den via Application Gateway från Internet, så se till att aktivera anslutningen till Developer-portalen och hanterings slut punkterna för API Management.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.

Jag har tilldelat en anpassad API Management domän och den publicerade portalen fungerar inteI have assigned a custom API Management domain and the published portal doesn't work

När du har uppdaterat domänen måste du publicera portalen igen för att ändringarna ska börja gälla.After you update the domain, you need to republish the portal for the changes to take effect.

Jag har lagt till en identitets leverantör och jag kan inte se den i portalenI have added an identity provider and I can't see it in the portal

När du har konfigurerat en identitets leverantör (till exempel AAD, AAD B2C) måste du publicera portalen igen för att ändringarna ska börja gälla.After you configure an identity provider (for example, AAD, AAD B2C), you need to republish the portal for the changes to take effect.

Jag har konfigurerat delegering och portalen använder den inteI have set up delegation and the portal doesn't use it

När du har konfigurerat delegering måste du publicera portalen igen för att ändringarna ska börja gälla.After you set up delegation, you need to republish the portal for the changes to take effect.

Mina andra API Management konfigurations ändringar har inte spridits i Developer-portalenMy other API Management configuration changes haven't been propagated in the developer portal

De flesta konfigurations ändringar (till exempel VNet, inloggning och produkt villkor) kräver att portalen publiceras om.Most configuration changes (for example, VNet, sign-in and product terms) require republishing the portal.

Jag får ett CORS-fel när jag använder den interaktiva konsolenI'm getting a CORS error when using the interactive console

Den interaktiva konsolen gör en API-begäran på klient sidan från webbläsaren.The interactive console makes a client-side API request from the browser. Lös CORS-problemet genom att lägga till en CORS-princip på dina API: er.Resolve the CORS problem by adding a CORS policy on your API(s).

Du kan kontrol lera status för CORS-principen i avsnittet Portal översikt i API Management tjänsten i Azure Portal.You can check the status of the CORS policy in the Portal overview section of your API Management service in the Azure portal. En varnings ruta anger att en princip saknas eller är felkonfigurerad.A warning box indicates an absent or misconfigured policy.

API Management Developer-portalen

Tillämpa CORS-principen automatiskt genom att klicka på knappen Aktivera CORS .Automatically apply the CORS policy by clicking on the Enable CORS button.

Du kan också aktivera CORS manuellt.You can also enable CORS manually.

  1. Klicka på den manuellt tillämpa den på länken global nivå för att se den genererade princip koden.Click on the Manually apply it on the global level link to see the generated policy code.
  2. Gå till alla API: er i avsnittet API: er i din API Management-tjänst i Azure Portal.Navigate to All APIs in the APIs section of your API Management service in the Azure portal.
  3. Klicka på </> ikonen i avsnittet inkommande bearbetning .Click on the </> icon in the Inbound processing section.
  4. Infoga principen i avsnittet i XML-filen.Insert the policy in the section of the XML file. Se till att värdet matchar din utvecklares Portal domän.Make sure the value matches your developer portal's domain.

Anteckning

Om du använder CORS-principen i produkt omfånget, i stället för API: erna och ditt API använder prenumerations nyckel autentisering via en rubrik, fungerar inte konsolen.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.

Webbläsaren utfärdar automatiskt ett alternativ HTTP-begäran, som inte innehåller något sidhuvud med prenumerations nyckeln.The browser automatically issues an OPTIONS HTTP request, which doesn't contain a header with the subscription key. På grund av den saknade prenumerations nyckeln kan API Management inte associera alternativ anropet med en produkt, så det går inte att använda CORS-principen.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.

Som en lösning kan du skicka prenumerations nyckeln i en frågeparameter.As a workaround you can pass the subscription key in a query parameter.

Vilka behörigheter behöver jag för att redigera Developer-portalen?What permissions do I need to edit the developer portal?

Om du ser Oops. Something went wrong. Please try again later. felet när du öppnar portalen i administrations läge, kan det hända att du saknar de nödvändiga behörigheterna (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).

De äldre portalerna krävde behörigheten Microsoft.ApiManagement/service/getssotoken/action för tjänst omfånget (/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ApiManagement/service/<apim-service-name>) för att ge användar administratörs åtkomst till portalerna.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. Den nya portalen kräver behörighet Microsoft.ApiManagement/service/users/token/action i omfånget /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.

Du kan använda följande PowerShell-skript för att skapa en roll med den behörighet som krävs.You can use the following PowerShell script to create a role with the required permission. Kom ihåg att ändra <subscription-id> parametern.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 

När rollen har skapats kan den beviljas till alla användare från avsnittet Access Control (IAM) i Azure Portal.Once the role is created, it can be granted to any user from the Access Control (IAM) section in the Azure portal. Om du tilldelar den här rollen till en användare tilldelas behörigheten på tjänstens omfång.Assigning this role to a user will assign the permission at the service scope. Användaren kommer att kunna generera SAS-token för en användares räkning i tjänsten.The user will be able to generate SAS tokens on behalf of any user in the service. Rollen måste ha tilldelats rollen som administratör för tjänsten.At the minimum, this role needs to be assigned to the administrator of the service. Följande PowerShell-kommando visar hur du tilldelar rollen till en användare user1 vid det lägsta omfånget för att undvika att ge användaren onödiga behörigheter: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" 

När behörigheterna har beviljats till en användare måste användaren logga ut och logga in igen till Azure Portal för att de nya behörigheterna ska börja gälla.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.

Jag ser Unable to start the portal. See if settings are specified correctly (...) feletI'm seeing the Unable to start the portal. See if settings are specified correctly (...) error

Det här felet visas när ett GET anrop https://<management-endpoint-hostname>/subscriptions/xxx/resourceGroups/xxx/providers/Microsoft.ApiManagement/service/xxx/contentTypes/document/contentItems/configuration?api-version=2018-06-01-preview Miss lyckas.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. Anropet utfärdas från webbläsaren av portalens administrations gränssnitt.The call is issued from the browser by the administrative interface of the portal.

Om din API Management-tjänst finns i ett VNet – hänvisa till den VNet-anslutningens fråga ovan.If your API Management service is in a VNet - refer to the VNet connectivity question above.

Anrops felen kan också orsakas av ett TLS/SSL-certifikat, som är tilldelat en anpassad domän och som inte är betrodd av webbläsaren.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. Som en minskning kan du ta bort den anpassade domänen för hanterings slut punkten – API Management kommer att återgå till standard slut punkten med ett betrott certifikat.As a mitigation, you can remove the management endpoint custom domain - API Management will fall back to the default endpoint with a trusted certificate.

Vad är webb läsar stöd för portalen?What's the browser support for the portal?

WebbläsareBrowser StödsSupported
Apple SafariApple Safari Ja1Yes1
Google ChromeGoogle Chrome Ja1Yes1
Microsoft EdgeMicrosoft Edge Ja1Yes1
Microsoft Internet ExplorerMicrosoft Internet Explorer NejNo
Mozilla FirefoxMozilla Firefox Ja1Yes1

1 stöds i de två senaste produktions versionerna.1 Supported in the two latest production versions.

Nästa stegNext steps

Läs mer om den nya Developer-portalen:Learn more about the new developer portal:

Bläddra bland andra resurser:Browse other resources: