Självvärd för API Management-utvecklarportalen

  • Artikel

GÄLLER FÖR: Utvecklare | Grundläggande | Standard | Premium

I den här självstudien beskrivs hur du själv är värd för API Management-utvecklarportalen. Självvärdering är ett av flera alternativ för att utöka funktionerna i utvecklarportalen. Du kan till exempel själv vara värd för flera portaler för din API Management-instans med olika funktioner. När du själv är värd för en portal blir du dess underhållare och du ansvarar för uppgraderingarna.

Viktigt!

Överväg endast självvärdering av utvecklarportalen när du behöver ändra kärnan i utvecklarportalens kodbas. Det här alternativet kräver avancerad konfiguration, inklusive:

  • Distribution till en värdplattform, som kan frontas av en lösning som CDN för ökad tillgänglighet och prestanda
  • Underhålla och hantera värdinfrastruktur
  • Manuella uppdateringar, inklusive för säkerhetskorrigeringar, som kan kräva att du löser kodkonflikter när du uppgraderar kodbasen

Kommentar

Den lokalt installerade portalen stöder inte synlighets- och åtkomstkontroller som är tillgängliga i den hanterade utvecklarportalen.

Om du redan har laddat upp eller ändrat mediefiler i den hanterade portalen kan du läsa Flytta från hanterad till lokalt installerad senare i den här artikeln.

Förutsättningar

Om du vill konfigurera en lokal utvecklingsmiljö måste du ha:

Steg 1: Konfigurera lokal miljö

För att konfigurera din lokala miljö måste du klona lagringsplatsen, växla till den senaste versionen av utvecklarportalen och installera npm-paket.

  1. Klona lagringsplatsen api-management-developer-portal från GitHub:

    git clone https://github.com/Azure/api-management-developer-portal.git

  2. Gå till din lokala kopia av lagringsplatsen:

    cd api-management-developer-portal

  3. Kolla in den senaste versionen av portalen.

    Innan du kör följande kod kontrollerar du den aktuella versionstaggen i avsnittet Versioner på lagringsplatsen och ersätter <current-release-tag> värdet med den senaste versionstaggen.

    git checkout <current-release-tag>

  4. Installera alla tillgängliga npm-paket:

    npm install

Dricks

Använd alltid den senaste portalversionen och håll den förgrenade portalen uppdaterad. Programvarutekniker använder grenen av den master här lagringsplatsen för daglig utveckling. Den har instabila versioner av programvaran.

Steg 2: Konfigurera JSON-filer, statiska webbplatser och CORS-inställningar

Utvecklarportalen kräver API Management REST API för att hantera innehållet.

config.design.json fil

Gå till src mappen och öppna config.design.json filen.

{
  "environment": "development",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature ...",
  "backendUrl": "https://<service-name>.developer.azure-api.net",
  "useHipCaptcha": false,
  "integration": {
      "googleFonts": {
          "apiKey": "..."
      }
  }
}

Konfigurera filen:

  1. I värdet managementApiUrl ersätter du <service-name> med namnet på din API Management-instans. Om du har konfigurerat en anpassad domän använder du den i stället (till exempel https://management.contoso.com).

    {
...
"managementApiUrl": "https://contoso-api.management.azure-api.net"
...

  2. Skapa en SAS-token manuellt för att aktivera direkt REST API-åtkomst till din API Management-instans.

  3. Kopiera den genererade token och klistra in den som managementApiAccessToken värde.

  4. I värdet backendUrl ersätter du <service-name> med namnet på din API Management-instans. Om du har konfigurerat en anpassad domän använder du den i stället (till exempel https://portal.contoso.com).

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

  5. Om du vill aktivera CAPTCHA i utvecklarportalen anger du "useHipCaptcha": true. Se till att konfigurera CORS-inställningar för serverdelen för utvecklarportalen.

  6. I integration, under googleFonts, kan du ange apiKey en Google API-nyckel som ger åtkomst till API:et för webbteckensnittsutvecklare. Den här nyckeln behövs bara om du vill lägga till Google-teckensnitt i avsnittet Format i utvecklarportalredigeraren.

    Om du inte redan har en nyckel kan du konfigurera en med hjälp av Google Cloud-konsolen. Följ de här stegen:

    1. Öppna Google Cloud-konsolen.
    2. Kontrollera om API:et för webbteckensnittsutvecklare är aktiverat. Om det inte är det aktiverar du det.
    3. Välj Skapa API-nyckel för autentiseringsuppgifter>.
    4. I den öppna dialogrutan kopierar du den genererade nyckeln och klistrar in den som värdet apiKey för config.design.json i filen.
    5. Välj Redigera API-nyckel för att öppna nyckelredigeraren.
    6. I redigeraren går du till API-begränsningar och väljer Begränsa nyckel. I listrutan väljer du API för webbteckensnittsutvecklare.
    7. Välj Spara.

config.publish.json fil

Gå till src mappen och öppna config.publish.json filen.

{
  "environment": "publishing",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "managementApiAccessToken": "SharedAccessSignature...",
  "useHipCaptcha": false
}

Konfigurera filen:

  1. Kopiera och klistra in managementApiUrl värdena och managementApiAccessToken från den tidigare konfigurationsfilen.

  2. Om du vill aktivera CAPTCHA i utvecklarportalen anger du "useHipCaptcha": true. Se till att konfigurera CORS-inställningar för serverdelen för utvecklarportalen.

config.runtime.json fil

Gå till src mappen och öppna config.runtime.json filen.

{
  "environment": "runtime",
  "managementApiUrl": "https://<service-name>.management.azure-api.net",
  "backendUrl": "https://<service-name>.developer.azure-api.net"
}

Konfigurera filen:

  1. Kopiera och klistra in managementApiUrl värdet från den tidigare konfigurationsfilen.

  2. I värdet backendUrl ersätter du <service-name> med namnet på din API Management-instans. Om du har konfigurerat en anpassad domän använder du den i stället (till exempel ). https://portal.contoso.com

    {
...
"backendUrl": "https://contoso-api.developer.azure-api.net"
...

Konfigurera den statiska webbplatsen

Konfigurera funktionen Statisk webbplats i ditt lagringskonto genom att ange vägar till index- och felsidorna:

  1. Gå till ditt lagringskonto i Azure-portalen och välj Statisk webbplats på menyn till vänster.

  2. På sidan Statisk webbplats väljer du Aktiverad.

  3. I fältet Indexdokumentnamn anger du index.html.

  4. I fältet Felsökväg för dokument anger du 404/index.html.

  5. Välj Spara.

Konfigurera CORS-inställningar för lagringskonto

Konfigurera CORS-inställningarna (Cross-Origin Resource Sharing) för lagringskontot:

  1. Gå till ditt lagringskonto i Azure-portalen och välj CORS på menyn till vänster.

  2. På fliken Blob-tjänst konfigurerar du följande regler:

    Regel Värde
    Tillåtna ursprung *
    Tillåtna metoder Markera alla HTTP-verb.
    Tillåtna rubriker *
    Exponerade rubriker *
    Max ålder 0

  3. Välj Spara.

Konfigurera CORS-inställningar för serverdelen för utvecklarportalen

Konfigurera CORS-inställningar för serverdelen för utvecklarportalen så att begäranden som kommer från din lokala utvecklarportal tillåts. Utvecklarportalen med egen värd förlitar sig på utvecklarportalens serverdelsslutpunkt (som anges i backendUrl portalkonfigurationsfilerna) för att aktivera flera funktioner, inklusive:

Så här lägger du till CORS-inställningar:

  1. Gå till din API Management-instans i Azure-portalen och välj Inställningar för utvecklarportalportalen>på menyn till vänster.
  2. På konfigurationsfliken Lokalt installerad portal lägger du till ett eller flera Origin-domänvärden . Till exempel:
    • Domänen där den lokalt installerade portalen finns, till exempel https://www.contoso.com
    • localhost för lokal utveckling (om tillämpligt), till exempel http://localhost:8080 eller https://localhost:8080
  3. Välj Spara.

Steg 3: Kör portalen

Nu kan du skapa och köra en lokal portalinstans i utvecklingsläget. I utvecklingsläge inaktiveras alla optimeringar och källkartorna aktiveras.

Kör följande kommando:

npm start

Efter en kort stund öppnas standardwebbläsaren automatiskt med din lokala instans av utvecklarportalen. Standardadressen är http://localhost:8080, men porten kan ändras om 8080 den redan är upptagen. Eventuella ändringar i projektets kodbas utlöser en återskapande och uppdatering av webbläsarfönstret.

Steg 4: Redigera via det visuella redigeringsprogrammet

Använd den visuella redigeraren för att utföra följande uppgifter:

  • Anpassa portalen
  • Skapa innehåll
  • Organisera webbplatsens struktur
  • Stilisera dess utseende

Se Självstudie: Få åtkomst till och anpassa utvecklarportalen. Den beskriver grunderna i det administrativa användargränssnittet och visar rekommenderade ändringar av standardinnehållet. Spara alla ändringar i den lokala miljön och tryck på Ctrl+C för att stänga den.

Steg 5: Publicera lokalt

Portaldata har sitt ursprung i form av starkt skrivna objekt. Följande kommando översätter dem till statiska filer och placerar utdata i ./dist/website katalogen:

npm run publish

Steg 6: Ladda upp statiska filer till en blob

Använd Azure CLI för att ladda upp de lokalt genererade statiska filerna till en blob och se till att dina besökare kan komma åt dem:

  1. Öppna Windows-kommandotolken, PowerShell eller något annat kommandogränssnitt.

  2. Kör följande Azure CLI-kommando.

    Ersätt <account-connection-string> med anslutningssträng för ditt lagringskonto. Du kan hämta den från avsnittet Åtkomstnycklar i ditt lagringskonto.

    az storage blob upload-batch --source dist/website \
    --destination '$web' \
    --connection-string <account-connection-string>

Steg 7: Gå till din webbplats

Webbplatsen är nu live under det värdnamn som anges i dina Azure Storage-egenskaper (primär slutpunkt på statiska webbplatser).

Steg 8: Ändra API Management-meddelandemallar

Ersätt url:en för utvecklarportalen i API Management-meddelandemallarna så att den pekar på din egen värdbaserade portal. Se Konfigurera aviseringar och e-postmallar i Azure API Management.

I synnerhet utför du följande ändringar i standardmallarna:

Kommentar

Värdena i följande uppdaterade avsnitt förutsätter att du är värd för portalen på https://portal.contoso.com/.

Bekräftelse av e-poständring

Uppdatera utvecklarportalens URL i mallen e-poständringsbekräftelsemeddelande :

Ursprungligt innehåll

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Uppdaterat

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Bekräftelse av nytt utvecklarkonto

Uppdatera utvecklarportalens URL i mallen bekräftelsemeddelande för nytt utvecklarkonto :

Ursprungligt innehåll

<a id="confirmUrl" href="$ConfirmUrl" style="text-decoration:none">
  <strong>$ConfirmUrl</strong></a>

Uppdaterat

<a id="confirmUrl" href="https://portal.contoso.com/signup?$ConfirmQuery" style="text-decoration:none">
  <strong>https://portal.contoso.com/signup?$ConfirmQuery</strong></a>

Bjud in användare

Uppdatera utvecklarportalens URL i mallen Bjud in användarmeddelande :

Ursprungligt innehåll

<a href="$ConfirmUrl">$ConfirmUrl</a>

Uppdaterat

<a href="https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery">https://portal.contoso.com/confirm-v2/identities/basic/invite?$ConfirmQuery</a>

Ny prenumeration aktiverad

Uppdatera url:en för utvecklarportalen i meddelandemallen Ny prenumeration aktiverad :

Ursprungligt innehåll

Thank you for subscribing to the <a href="http://$DevPortalUrl/products/$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Uppdaterat

Thank you for subscribing to the <a href="https://portal.contoso.com/product#product=$ProdId"><strong>$ProdName</strong></a> and welcome to the $OrganizationName developer community. We are delighted to have you as part of the team and are looking forward to the amazing applications you will build using our API!

Ursprungligt innehåll

Visit the developer <a href="http://$DevPortalUrl/developer">profile area</a> to manage your subscription and subscription keys

Uppdaterat

Visit the developer <a href="https://portal.contoso.com/profile">profile area</a> to manage your subscription and subscription keys

Ursprungligt innehåll

<a href="http://$DevPortalUrl/docs/services?product=$ProdId">Learn about the API</a>

Uppdaterat

<a href="https://portal.contoso.com/product#product=$ProdId">Learn about the API</a>

Ursprungligt innehåll

<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/applications">Feature your app in the app gallery</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">You can publish your application on our gallery for increased visibility to potential new users.</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
  <strong>
    <a href="http://$DevPortalUrl/issues">Stay in touch</a>
  </strong>
</p>
<p style="font-size:12pt;font-family:'Segoe UI'">
      If you have an issue, a question, a suggestion, a request, or if you just want to tell us something, go to the <a href="http://$DevPortalUrl/issues">Issues</a> page on the developer portal and create a new topic.
</p>

Uppdaterat

<!--Remove the entire block of HTML code above.-->

Bekräftelse av lösenordsändring

Uppdatera utvecklarportalens URL i mallen för bekräftelse av lösenordsändring :

Ursprungligt innehåll

<a href="$DevPortalUrl">$DevPortalUrl</a>

Uppdaterat

<a href="https://portal.contoso.com/confirm-password?$ConfirmQuery">https://portal.contoso.com/confirm-password?$ConfirmQuery</a>

Alla mallar

Uppdatera utvecklarportalens URL i alla mallar som har en länk i sidfoten:

Ursprungligt innehåll

<a href="$DevPortalUrl">$DevPortalUrl</a>

Uppdaterat

<a href="https://portal.contoso.com/">https://portal.contoso.com/</a>

Gå från hanterad till lokalt installerad utvecklarportal

Med tiden kan dina affärskrav ändras. Du kan hamna i en situation där den hanterade versionen av API Management-utvecklarportalen inte längre uppfyller dina behov. Ett nytt krav kan till exempel tvinga dig att skapa en anpassad widget som integreras med en dataprovider från tredje part. Till skillnad från den bemannade versionen ger den lokalt installerade versionen av portalen fullständig flexibilitet och utökningsbarhet.

Övergångsprocess

Du kan övergå från den hanterade versionen till en egen värdbaserad version inom samma API Management-tjänstinstans. Processen bevarar de ändringar som du har utfört i den hanterade versionen av portalen. Se till att du säkerhetskopierar portalens innehåll i förväg. Du hittar säkerhetskopieringsskriptet scripts i mappen på GITHub-lagringsplatsen för API Management-utvecklarportalen.

Konverteringsprocessen är nästan identisk med att konfigurera en allmän lokalt installerad portal, som du ser i föregående steg i den här artikeln. Det finns ett undantag i konfigurationssteget. Lagringskontot i config.design.json filen måste vara samma som lagringskontot för den hanterade versionen av portalen. Se Självstudie: Använda en systemtilldelad identitet för virtuella Linux-datorer för att få åtkomst till Azure Storage via en SAS-autentiseringsuppgift för att få instruktioner om hur du hämtar SAS-URL:en.

Dricks

Vi rekommenderar att du använder ett separat lagringskonto i config.publish.json filen. Den här metoden ger dig mer kontroll och förenklar hanteringen av värdtjänsten i portalen.

Nästa steg