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

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

I den här handledningen beskrivs hur du kan självhosta API Management-utvecklarportalen. Självhosting är ett av flera alternativ för att utöka funktionaliteten hos 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. Utvecklarportalen kräver API Management REST API för att hantera innehållet.

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:

• En API Management-tjänstinstans. Om du inte har någon kan du läsa Snabbstart – Skapa en Azure API Management-instans.

  Om du har skapat din instans på en v2-tjänstnivå aktiverar du först utvecklarportalen.

  1. I sidomenyn går du till Utvecklarportalen och väljer Portalinställningar.
  2. I fönstret Portalinställningar väljer du Aktiverad. Välj Spara. Det kan ta några minuter att aktivera utvecklarportalen.

• Ett Azure Blob Storage-konto som du använder för att aktivera funktionen för statiska webbplatser. Se Skapa ett lagringskonto.

• Git på din dator Installera det genom att följa den här Git-handledningen.

• Node.js (versions v10.15.0 eller senare med Long Term Support (LTS)) och npm på datorn. Se Ladda ned och installera Node.js och npm.

• Azure CLI. Följ installationsstegen för Azure CLI.

• Behörigheter för att skapa en Microsoft Entra-appregistrering.

Steg 1: Konfigurera lokal miljö

Om du vill konfigurera din lokala miljö klonar du lagringsplatsen, växlar till den senaste versionen av utvecklarportalen och installerar 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
   

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

config.design.json fil

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

{
    "environment": "development",
    "subscriptionId": "< subscription ID >",
    "resourceGroupName": "< resource group name >",
    "serviceName": "< API Management service name >"
}

I subscriptionId, resourceGroupNameoch serviceNameanger du värden för prenumerationen, resursgruppen och tjänstnamnet för din API Management-instans. I

Valfria inställningar i config.design.json

Du kan också konfigurera följande inställningar i config.design.json filen:

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

   {
       ...
       "useHipCaptcha": true
       ...
   }
   

2. I integration, under googleFonts, kan du valfritt ange apiKey som en Google API-nyckel vilken ger åtkomst till webbutvecklarnas teckensnitts-API. Den här nyckeln behövs bara om du vill lägga till Google-teckensnitt i avsnittet Format i utvecklarportalredigeraren.

   {
       ...
       "integration": {
           "googleFonts": {
               "apiKey": "< your Google API key >"
           }
       }
       ...
   }
   
   

3. Om du inte redan har en nyckel kan du konfigurera en med hjälp av Google Cloud-konsolen. Följ dessa steg:

   1. Öppna Google Cloud-konsolen.
   2. Kontrollera om API:et för webbteckensnittsutvecklare är aktiverat. Om det inte är aktiverat, aktiverar du det.
   3. Välj SkapaAPI-nyckel>.
   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",
    "subscriptionId":"<service subscription>",
    "resourceGroupName":"<service resource group>",
    "serviceName":"<service name>"
}

Kopiera och klistra in subscriptionIdvärdena , resourceGroupNameoch serviceName från den tidigare konfigurationsfilen.

config.runtime.json fil

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

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

Ersätt < service name > med namnet på din API Management-instans som användes i de tidigare konfigurationsfilerna.

Konfigurera den statiska webbplatsen

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

1. I Azure-portalen går du till ditt lagringskonto i Azure-portalen.

2. I sidomenyn väljer duStatisk webbplats>.

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

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

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

6. Välj Spara.

Anteckna URL:en för den primära slutpunkten . Du konfigurerar den senare för att få åtkomst till din egen värdbaserade portal.

Konfigurera CORS-inställningar för lagringskonto

Så här konfigurerar du CORS-inställningarna (cross-origin resource sharing) för lagringskontot:

1. Gå till ditt lagringskonto i Azure-portalen.

2. Välj Resursdelning (CORS) under Inställningar på sidomenyn.

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

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

4. 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 portalfilen config.runtime.json ) för att aktivera flera funktioner, inklusive:

• CAPTCHA-verifiering
• OAuth 2.0-auktorisering i testkonsolen
• Delegering av användarautentisering och produktprenumeration

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

1. Gå till din API Management-instans i Azure-portalen.
2. I sidomenyn väljer duInställningar för >.
3. 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://contoso.developer.azure-api.net
   • localhost för lokal utveckling (om tillämpligt), till exempel http://localhost:8080 eller https://localhost:8080
4. 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.

1. Kör följande kommando:

   npm run start
   

2. Du uppmanas att autentisera via webbläsaren. Välj dina Microsoft-autentiseringsuppgifter för att fortsätta.

3. Efter en tid ö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. När du gör ändringar i projektets kodbas utlöser det en återskapande och uppdaterar 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 portalen lokalt

1. Kör npm run publish. Du uppmanas att autentisera via webbläsaren. Välj dina Microsoft-autentiseringsuppgifter för att fortsätta.

2. Efter en tid publiceras innehållet i dist/website mappen.

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 az storage blog upload-batch kommando. Ersätt <connection-string> med en anslutningssträng för ditt lagringskonto. Du kan hämta den från avsnittetÅtkomstnycklar för > i ditt lagringskonto.

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

Steg 7: Gå till din webbplats

Webbplatsen är nu live under det värdnamn som anges i dina Azure Storage-egenskaper. Gå till Datahantering>Statisk webbplats i sidofältets meny. Värdnamnet är värdet för primär slutpunkt.

Värd för webbplatsens redigeringsverktyg

När du gör ändringar i webbplatskoden kan du behöva uppdatera koden för webbplatsredigeraren för att kunna stödja redigering av dina ändrade widgetar korrekt. I det här fallet, förutom att vara värd för portalen, kanske du också vill vara värd för redigeringsprogrammet. För detta måste du skapa den och konfigurera för åtkomst till DIN API Management-tjänst.

För detta behöver du ett Microsoft Entra-ID-program i din klientorganisation:

1. Registrera en applikation i din Microsoft Entra ID-klient. Anteckna applikations-ID (klient-ID) och katalog-ID (tenant-ID). Du konfigurerar dem i ett senare steg.
2. Konfigurera en omdirigerings-URI för webben (svars-URL) i den här applikationen så att den pekar på slutpunkten för webbappen där designern är värd. Det här är vanligtvis platsen för den bloblagringsbaserade webbplatsen. Exempel: https://<your-storage-account-name>z13.web.core.windows.net/.
3. Om du vill publicera portalen i pipelines (GitHub Actions) skapar du även en klienthemlighet för det här programmet. Anteckna det genererade hemliga värdet och lagra det på en säker plats.

Följ sedan de här stegen för att vara värd för webbplatsredigeraren:

1. Lägg till clientId och tenantId fält i config.design.json filen.

   {
       ...
       "clientId": "< Entra ID app ID >",
       "tenantId": "< Entra ID tenant ID >"
       ...
   }
   

2. npm run build-designer Kör kommandot för att skapa designern.

3. Gå till den genererade /dist/designer mappen som innehåller en fil config.json med följande innehåll:

   {
       "subscriptionId": "< subscription ID >",
       "resourceGroupName": "< resource group name >",
       "serviceName": "< API Management service name >",
       "clientId": "< Entra ID client ID >",
       "tenantId": "< Entra ID tenant ID >"
   }
   

4. Bekräfta konfigurationen av subscriptionId, resourceGroupName och serviceName, som behövs för att ansluta till din API Management-tjänst med hjälp av Azure Resource Manager-API:er.

Publicera portalen i pipelines (GitHub Actions)

Du kan publicera den lokalt installerade portalen i en pipeline, till exempel GitHub Actions.

Pipelinen behöver också inloggningsuppgifter för Entra ID-programmet för att genomföra publicering via pipelines. Du kan använda samma Entra-ID-program som beskrivs i föregående steg. tenantId, clientId och särskilt clientSecret måste behållas i respektive nyckellagringsutrymmen. Mer information finns i Använda hemligheter i GitHub Actions .

Exempel på YAML för GitHub Actions-pipeline:

name: Portal-Publishing-Pipeline

on:
  pull_request:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
      AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
      AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Set up Node.js
        uses: actions/setup-node@v5
        with:
          node-version: '20.x'

      - name: Install dependencies
        run: npm install

      - name: Run publish command
        run: npm run publish

Ä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:

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>

Uppdaterad

<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>

Uppdaterad

<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>

Uppdaterad

<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!

Uppdaterad

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

Uppdaterad

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>

Uppdaterad

<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>

Uppdaterad

<!--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>

Uppdaterad

<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>

Uppdaterad

<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 hanterade 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 utförde i den hanterade versionen av portalen. Se till att du säkerhetskopierar portalens innehåll i förväg. Du hittar säkerhetskopieringsskriptet scripts.v3 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.

Relaterat innehåll

• Lär dig mer om alternativa metoder för självhosting