Autohospedaje del portal para desarrolladores de API Management

  • Artículo

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

En este tutorial se describe cómo autohospedar el portal para desarrolladores de API Management. El autohospedaje es una de las varias opciones para ampliar la funcionalidad del portal para desarrolladores. Por ejemplo, puede autohospedar varios portales para la instancia de API Management, con características diferentes. Al autohospedar un portal, el usuario se convierte en su administrador y es responsable de las actualizaciones.

Importante

Considere la posibilidad de autohospedar el portal para desarrolladores solo cuando necesite modificar el núcleo del código base del portal para desarrolladores. Esta opción requiere configuración avanzada, como por ejemplo:

  • Implementación en una plataforma de hospedaje, opcionalmente con una solución como CDN para aumentar la disponibilidad y el rendimiento
  • Mantenimiento y administración de la infraestructura de hospedaje
  • Actualizaciones manuales, incluidas las revisiones de seguridad, que pueden requerir que resuelva conflictos de código al actualizar el código base

Nota

El portal autohospedado no admite controles de visibilidad y acceso disponibles en la versión administrada del portal para desarrolladores.

Si ya ha cargado o modificado archivos multimedia en el portal administrado, consulte Pasaje de administrado a autohospedado, más adelante en este artículo.

Requisitos previos

Para configurar un entorno de desarrollo local, tiene que tener:

Paso 1: Configuración del entorno local

Para configurar el entorno local, tendrá que clonar el repositorio, cambiar a la versión más reciente del portal para desarrolladores e instalar paquetes npm.

  1. Clone el repositorio api-management-developer-portal desde GitHub:

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

  2. Vaya a la copia local del repositorio:

    cd api-management-developer-portal

  3. Extraiga la versión más reciente del portal.

    Antes de ejecutar el código siguiente, compruebe la etiqueta de versión actual en la sección Releases del repositorio y reemplace el valor <current-release-tag> por la etiqueta de versión más reciente.

    git checkout <current-release-tag>

  4. Instale los paquetes npm disponibles:

    npm install

Sugerencia

Use siempre la versión más reciente del portal y mantenga actualizado el portal bifurcado. Los ingenieros de software usan la rama master de este repositorio con fines de desarrollo diario. Tiene versiones inestables del software.

Paso 2: Configuración de archivos JSON, sitio web estático y opciones de CORS

El portal para desarrolladores requiere que la API REST de API Management administre el contenido.

Archivo config.design.json

Vaya a la carpeta src y abra el archivo config.design.json.

{
  "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": "..."
      }
  }
}

Configure el archivo:

  1. En el valor managementApiUrl, reemplace <service-name> por el nombre de la instancia de API Management. Si configuró un dominio personalizado, úselo en su lugar (por ejemplo, https://management.contoso.com).

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

  2. Cree manualmente un token de SAS para habilitar el acceso directo de la API REST a la instancia de API Management.

  3. Copie el token generado y péguelo como valor managementApiAccessToken.

  4. En el valor backendUrl, reemplace <service-name> por el nombre de la instancia de API Management. Si configuró un dominio personalizado, úselo en su lugar (por ejemplo, https://portal.contoso.com).

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

  5. Si quiere habilitar CAPTCHA en el portal para desarrolladores, especifique "useHipCaptcha": true. Asegúrese de configurar las opciones de CORS para el back-end del portal para desarrolladores.

  6. En integration, en googleFonts, establezca opcionalmente apiKey en una clave de API de Google que permita el acceso a la API para desarrolladores de fuentes web. Esta clave solo es necesaria si desea agregar fuentes de Google en la sección Estilos del editor del portal para desarrolladores.

    Si aún no tiene una clave, puede configurar una mediante la consola de Google Cloud. Siga estos pasos:

    1. Abra la Consola de Google Cloud.
    2. Compruebe si la API para desarrolladores de fuentes web está habilitada. Si no lo está, habilítela.
    3. Select Crear credenciales>Clave de API.
    4. En el cuadro de diálogo que se abre, copie la clave generada y péguela como el valor de apiKey en el archivo config.design.json.
    5. Seleccione Editar clave de API para abrir el editor de claves.
    6. En el editor, en Restricciones de API, seleccione Restringir clave. En la lista desplegable, seleccione API para desarrolladores de fuentes web.
    7. Seleccione Guardar.

Archivo config.publish.json

Vaya a la carpeta src y abra el archivo config.publish.json.

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

Configure el archivo:

  1. Copie los valores managementApiUrl y managementApiAccessToken del archivo de configuración anterior y péguelos.

  2. Si quiere habilitar CAPTCHA en el portal para desarrolladores, especifique "useHipCaptcha": true. Asegúrese de configurar las opciones de CORS para el back-end del portal para desarrolladores.

Archivo config.runtime.json

Vaya a la carpeta src y abra el archivo config.runtime.json.

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

Configure el archivo:

  1. Copie el valor managementApiUrl del archivo de configuración anterior y péguelo.

  2. En el valor backendUrl, reemplace <service-name> por el nombre de la instancia de API Management. Si configuró un dominio personalizado, úselo en su lugar (por ejemplo, https://portal.contoso.com).

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

Configuración del sitio web estático

Para configurar la característica Sitio web estático en la cuenta de almacenamiento, proporcione las rutas a las páginas de índice y error:

  1. Vaya a la cuenta de almacenamiento en Azure Portal y seleccione Sitio web estático en el menú de la izquierda.

  2. En la página Sitio web estático, seleccione Habilitado.

  3. En el campo Nombre del documento de índice, escriba index.html.

  4. En el campo Ruta de acceso del documento de error, escriba 404/index.html.

  5. Seleccione Guardar.

Configuración de CORS para la cuenta de almacenamiento

Configure las opciones de uso compartido de recursos entre orígenes (CORS) para la c:

  1. Vaya a la cuenta de almacenamiento en Azure Portal y seleccione CORS en el menú de la izquierda.

  2. En la pestaña Blob service, configure las siguientes reglas:

    Regla Valor
    Orígenes permitidos *
    Métodos permitidos Seleccione todos los verbos HTTP.
    Encabezados permitidos *
    Encabezados expuestos *
    Antigüedad máxima 0

  3. Seleccione Guardar.

Configuración de CORS para el back-end del portal para desarrolladores

Configure opciones de CORS para el back-end del portal para desarrolladores para permitir solicitudes que se originen a través del portal para desarrolladores autohospedado. El portal para desarrolladores autohospedado se basa en el punto de conexión back-end del portal (establecido en los backendUrl archivos de configuración) para habilitar varias características, incluidas las siguientes:

Para agregar las opciones de CORS:

  1. Vaya a la instancia de API Management en Azure Portal y seleccionePortal para desarrolladores>Configuración del portalen el menú de la izquierda.
  2. En la pestaña Configuración del portal autohospedado, agregue uno o varios valores de dominio de origen. Por ejemplo:
    • El dominio en el que se hospeda el portal autohospedado, como https://www.contoso.com
    • localhost para el desarrollo local (si procede), como http://localhost:8080 o https://localhost:8080
  3. Seleccione Guardar.

Paso 3: Ejecución del portal

Ahora puede compilar y ejecutar una instancia local del portal en el modo de desarrollo. En el modo de desarrollo, todas las optimizaciones están desactivadas y los mapas de origen están activados.

Ejecute el siguiente comando:

npm start

Después de un breve período, el explorador predeterminado se abre automáticamente con la instancia local del portal para desarrolladores. La dirección predeterminada es http://localhost:8080, pero el puerto puede cambiar si 8080 ya está ocupado. Todo cambio en el código base del proyecto desencadena una recompilación y actualiza la ventana del explorador.

Paso 4: Edición mediante el editor visual

Use el editor visual para llevar a cabo estas tareas:

  • Personalizar el portal
  • Crear contenido
  • Organizar la estructura del sitio web
  • Estilizar el aspecto

Consulte Tutorial: Acceso y personalización del portal para desarrolladores. Trata los aspectos básicos de la interfaz de usuario administrativa y enumera los cambios recomendados en el contenido predeterminado. Guarde todos los cambios en el entorno local y presione CTRL+C para cerrar.

Paso 5: Publicación local

Los datos del portal se originan en forma de objetos de tipo seguro. El siguiente comando los traduce en archivos estáticos y coloca la salida en el directorio ./dist/website:

npm run publish

Paso 6: Carga de archivos estáticos en un blob

Use la CLI de Azure para cargar los archivos estáticos generados localmente en un blob y asegúrese de que los visitantes pueden acceder a ellos:

  1. Abra el símbolo del sistema de Windows, PowerShell u otro shell de comandos.

  2. Ejecute el siguiente comando de la CLI de Azure.

    Reemplace <account-connection-string> por la cadena de conexión de la cuenta de almacenamiento. Puede obtenerla de la sección Claves de acceso de la cuenta de almacenamiento.

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

Paso 7: Acceso al sitio web

El sitio web ahora está activo con el nombre de host especificado en las propiedades de Azure Storage (Punto de conexión principal en Sitios web estáticos).

Paso 8: Cambio de las plantillas de notificación de API Management

Reemplace la dirección URL del portal para desarrolladores en las plantillas de notificación de API Management para que apunten al portal autohospedado. Consulte Configuración de notificaciones y plantillas de correo electrónico en Azure API Management.

En concreto, lleve a cabo los siguientes cambios en las plantillas predeterminadas:

Nota

Los valores en las siguientes secciones Actualizado suponen que el portal se hospeda en https://portal.contoso.com/.

Confirmación de cambio de correo electrónico

Actualice la dirección URL del portal para desarrolladores en la plantilla de notificación Confirmación de cambio de correo electrónico:

Contenido original

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

Updated

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

Confirmación de nueva cuenta de desarrollador

Actualice la dirección URL del portal para desarrolladores en la plantilla de notificación Confirmación de nueva cuenta de desarrollador:

Contenido original

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

Updated

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

Invitación a un usuario

Actualice la dirección URL del portal para desarrolladores en la plantilla de notificación Invitar usuario:

Contenido original

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

Updated

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

Nueva suscripción activada

Actualice la dirección URL del portal para desarrolladores en la plantilla de notificación Nueva suscripción activada:

Contenido original

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!

Updated

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!

Contenido original

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

Updated

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

Contenido original

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

Updated

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

Contenido original

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

Updated

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

Confirmación de cambio de contraseña

Actualice la dirección URL del portal para desarrolladores en la plantilla de notificación Confirmación de cambio de contraseña:

Contenido original

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

Updated

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

Todas las plantillas

Actualice la dirección URL del portal para desarrolladores en cualquier plantilla que tenga un vínculo en el pie de página:

Contenido original

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

Updated

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

Pasaje del portal para desarrolladores administrado a autohospedado

Con el tiempo, es posible que los requisitos empresariales cambien. Puede acabar en una situación en la que la versión administrada del portal para desarrolladores de API Management ya no satisfaga sus necesidades. Por ejemplo, un nuevo requisito puede obligarle a crear un widget personalizado que se integre en un proveedor de datos externo. A diferencia de la versión administrada, la versión autohospedada del portal ofrece total flexibilidad y extensibilidad.

Proceso de transición

Puede realizar la transición de la versión administrada a una versión autohospedada dentro de la misma instancia de servicio de API Management. El proceso conserva las modificaciones que ha hecho en la versión administrada del portal. Asegúrese de hacer una copia de seguridad del contenido del portal de antemano. Puede encontrar el script de copia de seguridad en la carpeta scripts en el repositorio de GitHub del portal para desarrolladores de API Management.

El proceso de conversión es casi idéntico a la configuración de un portal autohospedado genérico, como se muestra en los pasos anteriores de este artículo. Hay una excepción en el paso de configuración. La cuenta de almacenamiento del archivo config.design.json debe ser la misma que la cuenta de almacenamiento de la versión administrada del portal. Consulte Tutorial: Uso de una identidad asignada por el sistema de una máquina virtual Linux para acceder a Azure Storage con las credenciales de SAS para obtener instrucciones sobre cómo recuperar la dirección URL de SAS.

Sugerencia

Se recomienda usar una cuenta de almacenamiento independiente en el archivo config.publish.json. Este enfoque le da más control y simplifica la administración del servicio de hospedaje del portal.

Pasos siguientes