Autohospedaje del portal para desarrolladores de API Management

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

En este tutorial se describe cómo hospedar automáticamente 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 hospedar varios portales automáticamente para la instancia de API Management, con distintas características. Al autohospedar un portal, se convierte en su mantenedor y es responsable de sus actualizaciones.

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

Prerrequisitos

Para configurar un entorno de desarrollo local, debe tener:

• Una instancia de servicio de API Management. Si no tiene una, consulte Inicio rápido: Creación de una instancia de Azure API Management.
• Una cuenta de Almacenamiento de Azure con la característica sitios web estáticos habilitada. Consulte Creación de una cuenta de almacenamiento.
• GIT en la máquina. Instálelo siguiendo este tutorial de Git.
• Node.js (versión LTS, v10.15.0 o posterior) y npm en la máquina. Consulte Descarga e instalación de Node.js y npm.
• CLI de Azure. Siga los pasos de instalación de la CLI de Azure.

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. Consulte 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 Versiones del repositorio y reemplace <current-release-tag> el valor por la etiqueta de versión más reciente.

   git checkout <current-release-tag>
   

4. Instale los paquetes npm disponibles:

   npm install
   

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

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

Archivo config.design.json

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

{
  "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 a 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, establezca "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 es así, habilite.
   3. Seleccione Crear credenciales>Clave de API.
   4. En el cuadro de diálogo abierto, copie la clave generada y péguela como 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. Haga clic en Guardar.

Archivo config.publish.json

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

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

Configure el archivo:

1. Copie y pegue los valores managementApiUrl y managementApiAccessToken del archivo de configuración anterior.

2. Si quiere habilitar CAPTCHA en el portal para desarrolladores, establezca "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 src carpeta y abra el config.runtime.json archivo.

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

Configure el archivo:

1. Copie y pegue el managementApiUrl valor del archivo de configuración anterior.

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

Configure la característica Sitio web estático en la cuenta de almacenamiento proporcionando 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. Haga clic en Guardar.

Configuración de las opciones de CORS para la cuenta de almacenamiento

Configure los valores de Uso compartido de recursos entre orígenes (CORS) para la cuenta de almacenamiento:

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 reglas siguientes:

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

3. Haga clic en Guardar.

Configurar los ajustes de CORS para el backend del portal de desarrolladores

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

• Comprobación CAPTCHA
• Autorización de OAuth 2.0 en la consola de prueba
• Delegación de la autenticación de usuario y la suscripción de producto

Para agregar la configuración de CORS:

1. Vaya a la instancia de API Management en Azure Portal y seleccioneConfiguración del portal>para desarrolladoresen 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:
   • Dominio donde 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. Haga clic en Guardar.

Paso 3: Ejecución del portal

Ahora puede compilar y ejecutar una instancia del portal local 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 tiempo, el explorador predeterminado se abre automáticamente con la instancia del portal para desarrolladores local. La dirección predeterminada es http://localhost:8080, pero el puerto puede cambiar si 8080 ya está ocupado. Cualquier cambio en el código base del proyecto desencadena una recompilación y actualización de la ventana del explorador.

Paso 4: Editar a través del editor visual

Use el editor visual para llevar a cabo estas tareas:

• Personalización del portal
• Contenido del autor
• Organización de la estructura del sitio web
• Estilizar su apariencia

Consulte Tutorial: Acceso y personalización del portal para desarrolladores. Abarca los conceptos 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 cerrarlo.

Paso 5: Publicar localmente

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 ./dist/website directorio:

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 puedan 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 por <account-connection-string> la cadena de conexión de la cuenta de almacenamiento. Puede obtenerlo en 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: Ir a su sitio web

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

Paso 8: Cambiar 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:

Confirmación del cambio de correo electrónico

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

Contenido original

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

Actualizado

<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 de confirmación nueva cuenta de desarrollador :

Contenido original

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

Actualizado

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

Invitar a usuario

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

Contenido original

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

Actualizado

<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

Actualiza la URL del portal de 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!

Actualizado

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

Actualizado

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>

Actualizado

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

Actualizado

<!--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 de confirmación de cambio de contraseña :

Contenido original

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

Actualizado

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

Actualizado

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

Traslado del portal para desarrolladores administrado a autohospedado

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

Proceso de transición

Puede pasar de la versión administrada a una versión autohospedada dentro de la misma instancia del servicio API Management. El proceso conserva las modificaciones que ha realizado 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 scripts carpeta del repositorio de GitHub del portal para desarrolladores de API Management.

El proceso de conversión es casi idéntico a configurar 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 config.design.json archivo 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 a través de una credencial de SAS para obtener instrucciones sobre cómo recuperar la dirección URL de SAS.

Contenido relacionado

• Más información sobre los enfoques alternativos para el autohospedaje