Extensión del portal para desarrolladores con widgets personalizados

SE APLICA A: Desarrollador | Básico | Estándar | Premium

El portal para desarrolladores de API Management cuenta con un editor visual y widgets integrados para que pueda personalizar y diseñar la apariencia del portal. Sin embargo, es posible que tenga que personalizar aún más el portal para desarrolladores con funciones personalizadas. Por ejemplo, puede que quiera integrar el portal para desarrolladores con un sistema de soporte técnico que implique agregar una interfaz personalizada. En este artículo se explican las formas de agregar funcionalidad personalizada, como widgets personalizados, al portal para desarrolladores de API Management.

En la tabla siguiente se resumen dos opciones, con vínculos a más detalles.

Uso del widget de código HTML personalizado

El portal para desarrolladores administrado incluye un widget de código HTML personalizado que permite insertar código HTML para personalizaciones de portal pequeñas. Por ejemplo, use HTML personalizado para insertar un vídeo o para agregar un formulario. El portal representa el widget personalizado en un marco en línea (iframe).

1. En la interfaz administrativa del portal para desarrolladores, vaya a la página o sección donde desea insertar el widget.

2. Seleccione el icono gris "más" (+) que aparece al mantener el puntero sobre la página.

3. En la ventana Agregar widget, seleccione Código HTML personalizado.

   

4. Seleccione el icono de "lápiz" para personalizar el widget.

5. Escriba valores de ancho y alto (en píxeles) para el widget.

6. Para heredar estilos del portal para desarrolladores (recomendado), seleccione Aplicar estilo del portal para desarrolladores.

   Nota

   Si no se selecciona esta configuración, los elementos incrustados serán controles HTML sin formato, sin los estilos del portal para desarrolladores.

   

7. Reemplace el código HTML de ejemplo por el contenido personalizado.

8. Una vez completada la configuración, cierre la ventana.

9. Guarde los cambios y vuelva a publicar el portal.

Creación y carga de un widget personalizado

Para casos de uso más avanzados, puede crear y cargar un widget personalizado en el portal para desarrolladores. API Management proporciona un andamiaje de código para que los desarrolladores creen widgets personalizados en React, Vue o TypeScript sin formato. El andamiaje incluye herramientas que le ayudarán a desarrollar e implementar el widget en el portal para desarrolladores.

Requisitos previos

• Instalación local del entorno de ejecución de Node.JS.
• Conocimientos básicos de programación y desarrollo web.

Crear widget

1. En la interfaz administrativa del portal para desarrolladores, seleccione Custom widgets>Create new custom widget.

2. Escriba un nombre de widget y elija una tecnología. Para más información, consulte Plantillas de widget, más adelante en este artículo.

3. Seleccione Crear widget.

4. Abra un terminal, vaya a la ubicación donde quiere guardar el código del widget y ejecute el siguiente comando para descargar el andamiaje del código:

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

5. Vaya a la carpeta recién creada que contiene el andamiaje del código del widget.

   cd <name-of-widget>
   

6. Abra la carpeta en el editor de código que prefiera, como VS Code.

7. Instale las dependencias e inicie el proyecto:

   npm install 
   npm start
   

   El explorador debe abrir una nueva pestaña con el portal para desarrolladores conectado al widget en modo de desarrollo.

   Nota

   Si la pestaña no se abre, haga lo siguiente:

   1. Asegúrese de que el servidor de desarrollo se haya iniciado. Para ello, compruebe la salida en la consola donde inició el servidor en el paso anterior. Debe mostrar el puerto en el que se ejecuta el servidor (por ejemplo, http://127.0.0.1:3001).
   2. Vaya al servicio API Management en Azure Portal y abra el portal para desarrolladores con la interfaz administrativa.
   3. Anexe /?MS_APIM_CW_localhost_port=3001 a la dirección URL. Cambie el número de puerto si el servidor se ejecuta en un puerto diferente.

8. Implemente el código del widget y pruébelo localmente. El código del widget se encuentra en la carpeta src, en las subcarpetas siguientes:

   • app: código del componente de widget que ven los visitantes del portal para desarrolladores publicado y con el que interactúan.
   • editor: código del componente de widget que se usa en la interfaz administrativa del portal para desarrolladores para editar la configuración del widget

   El archivo values.ts contiene los valores predeterminados y los tipos de las propiedades personalizadas del widget que puede habilitar para su edición.

   

   Las propiedades personalizadas permiten ajustar los valores de la instancia del widget personalizado desde la interfaz de usuario administrativa del portal para desarrolladores, sin cambiar el código ni volver a implementar el widget personalizado. Este objeto debe pasarse a algunas de las funciones auxiliares de los widgets.

Implementación del widget personalizado en el portal para desarrolladores

1. Especifique los valores siguientes en el archivo deploy.js ubicado en la raíz del proyecto:

   • resourceId: identificador de recurso del servicio API Management, en el siguiente formato: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>.

   • managementApiEndpoint: punto de conexión de Azure API Management (depende del entorno, normalmente management.azure.com).

   • apiVersion: opcional, se usa para invalidar la versión predeterminada de API Management.

2. Ejecute el siguiente comando:

   npm run deploy
   

   Si se le pide, inicie sesión en su cuenta de Azure.

   Nota:

   Cuando se le pida que inicie sesión, debe usar una cuenta de miembro del inquilino de Microsoft Entra ID asociado a la suscripción de Azure donde reside el servicio API Management. La cuenta no debe ser una cuenta de invitado o federada, y debe tener el permiso adecuado para acceder a la interfaz administrativa del portal.

El widget personalizado ahora se implementa en el portal para desarrolladores. Con la interfaz administrativa del portal, puede agregarlo a las páginas del portal para desarrolladores y establecer valores para las propiedades personalizadas configuradas en el widget.

Publicación del portal para desarrolladores

Después de configurar el widget en la interfaz administrativa, vuelva a publicar el portal para que el widget esté disponible en producción.

Plantillas de widget

Proporcionamos plantillas para las siguientes tecnologías que puede usar para el widget:

• TypeScript (implementación pura sin ningún marco)
• React
• Vue

Todas las plantillas se basan en el lenguaje de programación TypeScript.

La plantilla de React contiene enlaces personalizados preparados en el archivo hooks.ts y proveedores establecidos para compartir contexto mediante el árbol de componentes con enlaces useSecrets, useValues y useEditorValues dedicados.

Uso del paquete @azure/api-management-custom-widgets-tools

Este paquete de npm contiene las siguientes funciones para ayudarle a desarrollar su widget personalizado y proporciona características que incluyen la comunicación entre el portal para desarrolladores y el widget:

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

Función que devuelve un objeto JSON que contiene los valores que ha establecido en el editor de widgets junto con valores predeterminados, pasados como argumento.

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

Está pensada para usarse en la parte en tiempo de ejecución (app) del widget.

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

Función que funciona del mismo modo que getValues, pero devuelve solo los valores que ha establecido en el editor.

Está pensada para usarse en el editor del widget, pero también funciona en tiempo de ejecución.

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

Acepta un tipo TypeScript y devuelve una función para actualizar los valores del widget. La función devuelta toma como parámetro un objeto JSON con valores actualizados y no devuelve nada.

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

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

Esta función devuelve una promesa de JavaScript, que, después de la resolución, devuelve un objeto JSON de los datos necesarios para comunicarse con el back-end. token es necesario para la autenticación. userId es necesario para consultar recursos específicos del usuario. Esos valores pueden no estar definidos cuando un usuario anónimo visita el portal. El objeto Secrets también contiene managementApiUrl, que es la dirección URL del back-end del portal y apiVersion, que es la apiVersion que se usa actualmente en el portal para desarrolladores.

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

Esta función implementa el widget en el almacenamiento de blobs. En todas las plantillas, está preconfigurada en el archivo deploy.js.

Acepta tres argumentos de forma predeterminada:

• serviceInformation: información sobre el servicio de Azure:

  • resourceId: identificador de recurso del servicio API Management, en el siguiente formato: subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ApiManagement/service/<api-management service-name>.

  • managementApiEndpoint: punto de conexión de Azure API Management (depende del entorno, normalmente management.azure.com).

• Identificador del widget: nombre del widget en formato "compatible con PC" (caracteres en minúscula alfanuméricos latinos y guiones; Contoso widget se convierte en contoso-widget). Puede encontrarlo en package.json bajo la clave name.

• fallbackConfigPath: ruta de acceso del archivo config.msapim.json local, por ejemplo, ./static/config.msapim.json

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

Esta función devuelve todos los datos pasados al widget personalizado desde el portal para desarrolladores. Contiene otros datos que podrían ser útiles en la depuración o en escenarios más avanzados. Se espera que esta API cambie con posibles cambios importantes. Devuelve un objeto JSON que contiene las claves siguientes:

• values: todos los valores que ha establecido en el editor, el mismo objeto devuelto por getEditorData.

• instanceId: identificador de esta instancia del widget.

Agregar o quitar propiedades personalizadas

Las propiedades personalizadas permiten ajustar los valores en el código del widget personalizado desde la interfaz de usuario administrativa del portal para desarrolladores, sin cambiar el código ni volver a implementar el widget personalizado. De forma predeterminada, se definen los campos de entrada de cuatro propiedades personalizadas. Puede agregar o quitar otras propiedades personalizadas según sea necesario.

Para agregar una propiedad personalizada:

1. En el archivo src/values.ts, agregue al tipo Values el nombre de la propiedad y el tipo de los datos que guardará.
2. En el mismo archivo, agregue un valor predeterminado para él.
3. Vaya al archivo editor.html o editor/index (la ubicación exacta depende del marco que haya elegido) y duplique una entrada existente o agregue una usted mismo.
4. Asegúrese de que el campo de entrada notifica el valor cambiado a la función onChange, que puede obtener de buildOnChange.

(Opcional) Uso de otro marco

Para implementar el widget con otro marco de interfaz de usuario de JavaScript y otras bibliotecas, debe configurar el proyecto usted mismo con las siguientes directrices:

• En la mayoría de los casos, se recomienda empezar a partir de la plantilla de TypeScript.
• Instale las dependencias como en cualquier otro proyecto de npm.
• Si el marco que prefiere no es compatible con la herramienta de compilación Vite, configúrelo para que genere archivos compilados en la carpeta ./dist. Opcionalmente, vuelva a definir dónde se encuentran los archivos compilados proporcionando una ruta de acceso relativa como cuarto argumento para la función deployNodeJs.
• Para el desarrollo local, el archivo config.msapim.json debe ser accesible en la dirección URL localhost:<port>/config.msapim.json cuando se ejecuta el servidor.

Creación de widgets personalizados mediante el kit de herramientas de componentes de React de código abierto

El kit de herramientas de componentes de React de código abierto proporciona un conjunto de scripts de paquetes de npm para ayudarle a convertir una aplicación de React al marco de widget personalizado, probarla e implementar el widget personalizado en el portal para desarrolladores. Si tiene acceso a un servicio Azure OpenAI, el kit de herramientas también puede crear un widget a partir de una descripción de texto.

Actualmente, puede usar el kit de herramientas para implementar un widget personalizado de dos maneras:

• Manualmente, instalando el kit de herramientas y ejecutando los scripts del paquete npm localmente. Los scripts se ejecutan secuencialmente para crear, probar e implementar un componente de React como un widget personalizado en el portal para desarrolladores.
• Uso de una plantilla Azure Developer CLI (azd) para una implementación de un extremo a otro. La plantilla azd implementa una instancia de Azure API Management y una instancia de Azure OpenAI. Una vez aprovisionados los recursos, un script interactivo le ayuda a crear, probar e implementar un widget personalizado en el portal para desarrolladores desde la descripción que proporcione.

Contenido relacionado

Obtenga más información sobre el portal para desarrolladores:

• Introducción al portal para desarrolladores de Azure API Management
• Preguntas más frecuentes
• Proveedor de andamiaje de un widget personalizado para el portal para desarrolladores del servicio Azure API Management
• Herramientas para trabajar con widgets personalizados del portal para desarrolladores del servicio Azure API Management