Utöka utvecklarportalen med anpassade widgetar

  • Artikel

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

Utvecklarportalen för API Management innehåller en visuell redigerare och inbyggda widgetar så att du kan anpassa och formatera portalens utseende. Du kan dock behöva anpassa utvecklarportalen ytterligare med anpassade funktioner. Du kanske till exempel vill integrera utvecklarportalen med ett supportsystem som innebär att du lägger till ett anpassat gränssnitt. Den här artikeln beskriver hur du lägger till anpassade funktioner, till exempel anpassade widgetar i api Management-utvecklarportalen.

I följande tabell sammanfattas två alternativ med länkar till mer information.

Metod beskrivning
Anpassad HTML-kodwidget – Enkel lösning för API-utgivare för att lägga till anpassad logik för grundläggande användningsfall

– Kopiera och klistra in anpassad HTML-kod i ett formulär, och utvecklarportalen renderar den i en iframe
Skapa och ladda upp anpassad widget – Utvecklarlösning för mer avancerade användningsfall för widgetar

– Kräver lokal implementering i React, Vue eller plain TypeScript

– Widgetställningar och verktyg som tillhandahålls för att hjälpa utvecklare att skapa widgetar och ladda upp till utvecklarportalen

– Skapande, testning och distribution av widgetar kan skriptas via öppen källkod React Component Toolkit

– Stöder arbetsflöden för källkontroll, versionshantering och återanvändning av kod

Kommentar

Självvärdering av utvecklarportalen är ett utökningsalternativ för kunder som behöver anpassa källkoden för hela portalkärnan. Det ger fullständig flexibilitet för att anpassa portalupplevelsen, men kräver avancerad konfiguration. Med självvärdering ansvarar du för att hantera hela kodlivscykeln: förgrena kodbas, utveckla, distribuera, vara värd, korrigera och uppgradera.

Använda anpassad HTML-kodwidget

Portalen för hanterad utvecklare innehåller en anpassad HTML-kodwidget där du kan infoga HTML-kod för små portalanpassningar. Du kan till exempel använda anpassad HTML för att bädda in en video eller lägga till ett formulär. Portalen renderar den anpassade widgeten i en infogad ram (iframe).

  1. I det administrativa gränssnittet för utvecklarportalen går du till sidan eller avsnittet där du vill infoga widgeten.

  2. Välj den grå plusikonen (+) som visas när du hovrar pekaren över sidan.

  3. I fönstret Lägg till widget väljer du Anpassad HTML-kod.

    Skärmbild som visar hur du lägger till en widget för anpassad HTML-kod i utvecklarportalen.

  4. Välj pennikonen för att anpassa widgeten.

  5. Ange bredd och höjd (i bildpunkter) för widgeten.

  6. Om du vill ärva formatmallar från utvecklarportalen (rekommenderas) väljer du Använd design för utvecklarportalen.

    Kommentar

    Om den här inställningen inte är markerad är de inbäddade elementen vanliga HTML-kontroller, utan formatmallarna i utvecklarportalen.

    Skärmbild som visar hur du konfigurerar anpassad HTML-kod i utvecklarportalen.

  7. Ersätt HTML-exempelkoden med ditt anpassade innehåll.

  8. När konfigurationen är klar stänger du fönstret.

  9. Spara ändringarna och publicera portalen igen.

Kommentar

Microsoft stöder inte HTML-koden som du lägger till i widgeten anpassad HTML-kod.

Skapa och ladda upp anpassad widget

För mer avancerade användningsfall kan du skapa och ladda upp en anpassad widget till utvecklarportalen. API Management tillhandahåller en kodram för utvecklare för att skapa anpassade widgetar i React, Vue eller plain TypeScript. Ställningen innehåller verktyg som hjälper dig att utveckla och distribuera widgeten till utvecklarportalen.

Förutsättningar

  • Installera Node.JS körning lokalt
  • Grundläggande kunskaper om programmering och webbutveckling

Skapa widget

Varning

Din anpassade widgetkod lagras i offentlig Azure Blob Storage som är associerad med din API Management-instans. När du lägger till en anpassad widget i utvecklarportalen läss kod från den här lagringen via en slutpunkt som inte kräver autentisering, även om utvecklarportalen eller en sida med den anpassade widgeten endast är tillgänglig för autentiserade användare. Inkludera inte känslig information eller hemligheter i den anpassade widgetkoden.

  1. I det administrativa gränssnittet för utvecklarportalen väljer du Anpassade widgetar>Skapa ny anpassad widget.

  2. Ange ett widgetnamn och välj en teknik. Mer information finns i Widget-mallar senare i den här artikeln.

  3. Välj Skapa widget.

  4. Öppna en terminal, navigera till den plats där du vill spara widgetkoden och kör följande kommando för att ladda ned kodställningen:

    npx @azure/api-management-custom-widgets-scaffolder

  5. Navigera till den nyligen skapade mappen som innehåller widgetens kodställning.

    cd <name-of-widget>

  6. Öppna mappen i valfri kodredigerare, till exempel VS Code.

  7. Installera beroendena och starta projektet:

    npm install 
npm start

    Webbläsaren bör öppna en ny flik med utvecklarportalen ansluten till widgeten i utvecklingsläge.

    Kommentar

    Om fliken inte öppnas gör du följande:

    1. Kontrollera att utvecklingsservern har startats. Det gör du genom att kontrollera utdata i konsolen där du startade servern i föregående steg. Den ska visa den port som servern körs på (till exempel http://127.0.0.1:3001).
    2. Gå till API Management-tjänsten i Azure-portalen och öppna utvecklarportalen med det administrativa gränssnittet.
    3. Lägg till /?MS_APIM_CW_localhost_port=3001 i URL:en. Ändra portnumret om servern körs på en annan port.

  8. Implementera koden för widgeten och testa den lokalt. Koden för widgeten finns i src mappen i följande undermappar:

    • app – Kod för widgetkomponenten som besökare på den publicerade utvecklarportalen ser och interagerar med
    • editor – Kod för widgetkomponenten som du använder i det administrativa gränssnittet i utvecklarportalen för att redigera widgetinställningar

    Filen values.ts innehåller standardvärdena och typerna av widgetens anpassade egenskaper som du kan aktivera för redigering.

    Skärmbild av sidan anpassade egenskaper i utvecklarportalen.

    Med anpassade egenskaper kan du justera värden i den anpassade widgetens instans från det administrativa användargränssnittet i utvecklarportalen, utan att ändra koden eller distribuera om den anpassade widgeten. Det här objektet måste skickas till några av widgetarnas hjälpfunktioner.

Distribuera den anpassade widgeten till utvecklarportalen

  1. Ange följande värden i deploy.js filen som finns i projektets rot:

    • resourceId – Resurs-ID för din API Management-tjänst i följande format: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint – Azure Management API-slutpunkt (beror på din miljö, vanligtvis management.azure.com)

    • apiVersion – Valfritt, använd för att åsidosätta standardversionen av API:et för hantering

  2. Kör följande kommando:

    npm run deploy

    Logga in på ditt Azure-konto om du uppmanas att göra det.

    Kommentar

    När du uppmanas att logga in måste du använda ett medlemskonto från Microsoft Entra ID-klientorganisationen som är associerad med Den Azure-prenumeration där DIN API Management-tjänst finns. Kontot får inte vara en gäst eller ett federerat konto och måste ha rätt behörighet att komma åt portalens administrativa gränssnitt.

Den anpassade widgeten distribueras nu till utvecklarportalen. Med hjälp av portalens administrativa gränssnitt kan du lägga till det på sidor i utvecklarportalen och ange värden för alla anpassade egenskaper som konfigurerats i widgeten.

Publicera utvecklarportalen

När du har konfigurerat widgeten i det administrativa gränssnittet publicerar du portalen igen för att göra widgeten tillgänglig i produktion.

Kommentar

  • Om du distribuerar uppdaterad widgetkod vid ett senare tillfälle uppdateras inte widgeten som används i produktionen förrän du publicerar om utvecklarportalen.
  • Widgetens kompilerade kod är associerad med en specifik portalrevision. Om du gör en tidigare portalrevision aktuell används den anpassade widgeten som är associerad med den revisionen.

Widgetmallar

Vi tillhandahåller mallar för följande tekniker som du kan använda för widgeten:

  • TypeScript (ren implementering utan ramverk)
  • React
  • Vue

Alla mallar baseras på programmeringsspråket TypeScript.

React-mallen innehåller förberedda anpassade krokar i hooks.ts filen och etablerade leverantörer för delningskontext via komponentträdet med dedikerade useSecrets, useValuesoch useEditorValues krokar.

@azure/api-management-custom-widgets-tools Använda paketet

Det här npm-paketet innehåller följande funktioner som hjälper dig att utveckla din anpassade widget och tillhandahåller funktioner som kommunikation mellan utvecklarportalen och widgeten:

Function beskrivning
getValues Returnerar ett JSON-objekt som innehåller värden som angetts i widgetredigeraren kombinerat med standardvärden
getEditorValues Returnerar ett JSON-objekt som endast innehåller värden som angetts i widgetredigeraren
buildOnChange Accepterar en TypeScript-typ och returnerar en funktion för att uppdatera widgetvärdena. Den returnerade funktionen tar som parameter ett JSON-objekt med uppdaterade värden och returnerar ingenting.

Används internt i widgetredigeraren
askForSecrets Returnerar ett JavaScript-löfte som efter matchningen returnerar ett JSON-objekt med data som behövs för att kommunicera med serverdelen
deployNodeJs Distribuerar widget till bloblagring
getWidgetData Returnerar alla data som skickas till din anpassade widget från utvecklarportalen

Används internt i mallar

@azure/api-management-custom-widgets-tools/getValues

Funktion som returnerar ett JSON-objekt som innehåller de värden som du har angett i widgetredigeraren kombinerat med standardvärden, som skickas som ett argument.

Import {getValues} from "@azure/api-management-custom-widgets-tools/getValues" 
import {valuesDefault} from "./values" 
const values = getValues(valuesDefault)

Den är avsedd att användas i körningsdelen (app) i widgeten.

@azure/api-management-custom-widgets-tools/getEditorValues

Funktion som fungerar på samma sätt som getValues, men som endast returnerar värden som du har angett i redigeraren.

Den är avsedd att användas i redigeringsprogrammet för widgeten men fungerar även i körning.

@azure/api-management-custom-widgets-tools/buildOnChange

Kommentar

Den här funktionen är avsedd att endast användas i widgetredigeraren.

Accepterar en TypeScript-typ och returnerar en funktion för att uppdatera widgetvärdena. Den returnerade funktionen tar som parameter ett JSON-objekt med uppdaterade värden och returnerar ingenting.

import {Values} from "./values"
const onChange = buildOnChange<Values>()
onChange({fieldKey: 'newValue'})

@azure/api-management-custom-widgets-tools/askForSecrets

Den här funktionen returnerar ett JavaScript-löfte som efter upplösningen returnerar ett JSON-objekt med data som behövs för att kommunicera med serverdelen. token krävs för autentisering. userId krävs för att köra frågor mot användarspecifika resurser. Dessa värden kan vara odefinierade när portalen visas av en anonym användare. Objektet Secrets innehåller managementApiUrlockså , vilket är URL:en för portalens serverdel och apiVersion, som är den apiVersion som för närvarande används av utvecklarportalen.

Varning

Hantera och använd token noggrant. Alla som har den kan komma åt data i din API Management-tjänst.

@azure/api-management-custom-widgets-tools/deployNodeJs

Den här funktionen distribuerar widgeten till bloblagringen. I alla mallar är den förkonfigurerad i deploy.js filen.

Den accepterar tre argument som standard:

  • serviceInformation – Information om din Azure-tjänst:

    • resourceId – Resurs-ID för din API Management-tjänst i följande format: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>

    • managementApiEndpoint – Azure Management API-slutpunkt (beror på din miljö, vanligtvis management.azure.com)

  • ID för widgeten – Namnet på widgeten i "PC-vänligt" format (latinska alfanumeriska gemener och bindestreck; Contoso widget blir contoso-widget). Du hittar den i package.json under-nyckeln name .

  • fallbackConfigPath – Sökväg för den lokala config.msapim.json filen, till exempel ./static/config.msapim.json

@azure/api-management-custom-widgets-tools/getWidgetData

Kommentar

Den här funktionen används internt i mallar. I de flesta implementeringar bör du inte behöva det annars.

Den här funktionen returnerar alla data som skickas till din anpassade widget från utvecklarportalen. Den innehåller andra data som kan vara användbara vid felsökning eller i mer avancerade scenarier. Det här API:et förväntas ändras med potentiella icke-bakåtkompatibla ändringar. Den returnerar ett JSON-objekt som innehåller följande nycklar:

  • values – Alla värden som du har angett i redigeraren, samma objekt som returneras av getEditorData
  • instanceId – ID för den här instansen av widgeten

Lägga till eller ta bort anpassade egenskaper

Med anpassade egenskaper kan du justera värden i den anpassade widgetens kod från det administrativa användargränssnittet i utvecklarportalen, utan att ändra koden eller distribuera om den anpassade widgeten. Som standard definieras indatafält för fyra anpassade egenskaper. Du kan lägga till eller ta bort andra anpassade egenskaper efter behov.

Varning

Lagra inte hemliga eller känsliga värden i anpassade egenskaper.

Så här lägger du till en anpassad egenskap:

  1. I filen src/values.tslägger du till Values i typen namnet på egenskapen och typen av data som sparas.
  2. I samma fil lägger du till ett standardvärde för den.
  3. Navigera till editor.html filen eller editor/index (exakt plats beror på vilket ramverk du har valt) och duplicera en befintlig indata eller lägg till en själv.
  4. Kontrollera att indatafältet rapporterar det ändrade värdet till onChange funktionen, som du kan hämta från buildOnChange.

(Valfritt) Använda ett annat ramverk

Om du vill implementera widgeten med ett annat JavaScript-gränssnittsramverk och bibliotek måste du konfigurera projektet själv med följande riktlinjer:

  • I de flesta fall rekommenderar vi att du börjar från TypeScript-mallen.
  • Installera beroenden som i andra npm-projekt.
  • Om ditt valfria ramverk inte är kompatibelt med Vite-byggverktyget konfigurerar du det så att det matar ut kompilerade filer till ./dist mappen. Du kan också omdefiniera var de kompilerade filerna finns genom att ange en relativ sökväg som det fjärde argumentet för deployNodeJs funktionen.
  • För lokal utveckling config.msapim.json måste filen vara tillgänglig på URL:en localhost:<port>/config.msapim.json när servern körs.

Skapa anpassade widgetar med hjälp av öppen källkod React Component Toolkit

Öppen källkod React Component Toolkit innehåller en uppsättning npm-paketskript som hjälper dig att konvertera ett React-program till det anpassade widgetramverket, testa det och distribuera den anpassade widgeten till utvecklarportalen. Om du har åtkomst till en Azure OpenAI-tjänst kan verktygslådan också skapa en widget från en textbeskrivning som du anger.

För närvarande kan du använda verktygslådan på två sätt för att distribuera en anpassad widget:

  • Manuellt genom att installera verktygslådan och köra npm-paketskripten lokalt. Du kör skripten sekventiellt för att skapa, testa och distribuera en React-komponent som en anpassad widget till utvecklarportalen.
  • Använda en Azure Developer CLI-mall (azd) för en distribution från slutpunkt till slutpunkt. Mallen azd distribuerar en Azure API Management-instans och en Azure OpenAI-instans. När resurser har etablerats hjälper ett interaktivt skript dig att skapa, testa och distribuera en anpassad widget till utvecklarportalen från en beskrivning som du anger.

Kommentar

Exempelmallen React Component Toolkit och Azure Developer CLI är öppen källkod projekt. Support tillhandahålls endast via GitHub-problem i respektive lagringsplatser.

Relaterat innehåll

Läs mer om utvecklarportalen: