Compartir vía

Autohospede su portal del Centro de API

  • Artículo

En este artículo se presenta el portal del Centro de API, un sitio web que los desarrolladores y otras partes interesadas de la organización pueden usar para detectar las API en el centro de API. Implemente una implementación de referencia del portal desde el repositorio de inicio del portal del Centro de API.

Captura de pantalla del portal de API Center después del inicio de sesión del usuario.

Acerca del portal del Centro de API

El portal del Centro de API es un sitio web que puede compilar y hospedar para mostrar el inventario de API en el centro de API. El portal permite a los desarrolladores y a otras partes interesadas de su organización detectar API y ver los detalles de la API.

Puede compilar e implementar una implementación de referencia del portal mediante código en el repositorio de inicio del portal del Centro de API. El portal usa la API del plano de datos del Centro de API de Azure para recuperar datos del centro de API. El acceso de usuario a la información de API se basa en el control de acceso basado en roles de Azure.

La implementación de referencia del portal del Centro de API proporciona:

  • Marco para publicar y mantener un portal de API administrado por el cliente mediante Acciones de GitHub
  • Una plataforma del portal que los clientes pueden modificar o ampliar para satisfacer sus necesidades
  • Flexibilidad para hospedar en distintas infraestructuras, incluida la implementación en servicios como Azure Static Web Apps.

Requisitos previos

  • Un centro de API en la suscripción de Azure. Si aún no ha creado uno, consulte Inicio rápido: Creación del centro de API.

  • Permisos para crear un registro de aplicaciones en un inquilino de Microsoft Entra asociado a su suscripción de Azure y permisos para conceder acceso a los datos en el centro de API.

  • Para compilar e implementar el portal, necesita una cuenta de GitHub y las siguientes herramientas instaladas en el equipo local:

Cree un registro de aplicaciones de Microsoft Entra

En primer lugar, configure un registro de aplicaciones en el inquilino de Id. de Microsoft Entra. El registro de aplicaciones permite que el portal del Centro de API acceda a los datos desde el centro de API en nombre de un usuario que ha iniciado sesión.

  1. En Azure Portal, vaya a ID. de Microsoft Entra>Registros de aplicaciones.

  2. Seleccione + Nuevo registro.

  3. En la página Registrar una aplicación, establezca los valores siguientes:

    • Establezca el valor Nombre con un nombre descriptivo, como api-center-portal

    • En Tipos de cuenta admitidos, seleccione Cuentas de este directorio organizativo (inquilino único).

    • En URI de redirección, seleccione aplicación de página única (SPA) y establezca el URI.

      • Para las pruebas locales, establezca el URI en https://localhost:5173.
      • Para producción, establezca el URI en el URI de la implementación del portal del Centro de API.

    • Seleccione Registrar.

  4. En la página Información general, copie los valores de Id. de aplicación (cliente) e Id. de directorio (inquilino). Estos valores se establecen al compilar el portal.

  5. En la página Permisos de API, seleccione +Agregar un permiso.

    1. En el panel Solicitar permisos de API, seleccione API que usa mi organización. Busque y seleccione Centro de API deAzure. También puede buscar y seleccionar el identificador de aplicaciónc3ca1a77-7a87-4dba-b8f8-eea115ae4573.
    2. En la página Solicitar permisos, seleccione user_impersonation.
    3. Seleccione Agregar permisos.

    Los permisos del Centro de API de Azure aparecen en Permisos configurados.

    Captura de pantalla de los permisos necesarios en el registro de aplicaciones de Microsoft Entra ID en el portal.

Configuración del entorno local

Siga estos pasos para compilar y probar el portal del Centro de API localmente.

  1. Clone el repositorio de inicio del portal del Centro de API en la máquina local.

    git clone https://github.com/Azure/APICenter-Portal-Starter.git

  2. Cambie al directorio APICenter-Portal-Starter.

    cd APICenter-Portal-Starter

  3. Extraiga del repositorio la rama main.

    git checkout main

  4. Para configurar el servicio, copia o cambia el nombre del archivo public/config.example a public/config.json.

  5. Después, edita el archivo public/config.json para que apunte al servicio. Actualice los valores en el archivo de la siguiente manera:

    • Reemplace <service name> y <region> por el nombre del centro de API y la región donde se implementa
    • Reemplace <client ID> y <tenant ID> por el identificador de aplicación (cliente) y el identificador de directorio (inquilino) del registro de la aplicación que creó en la sección anterior.
    • Actualice el valor de title a un nombre que desea que aparezca en el portal.
    {
  "dataApiHostName": "<service name>.data.<region>.azure-apicenter.ms/workspaces/default",
  "title": "API portal",
  "authentication": {
      "clientId": "<client ID>",
      "tenantId": "<tenant ID>",
      "scopes": ["https://azure-apicenter.net/user_impersonation"],
      "authority": "https://login.microsoftonline.com/"
  }
}

  6. Instalar los paquetes requeridos.

    npm install

  7. Inicie el servidor de desarrollo. El comando siguiente iniciará el portal en modo de desarrollo que se ejecuta localmente:

    npm start

    Vaya al portal en https://localhost:5173.

Implementación en Azure

Para conocer los pasos para implementar el portal en Azure Static Web Apps, consulte el repositorio de inicio del portal del Centro de API.

Habilitación del inicio de sesión en el portal por parte de usuarios y grupos de Microsoft Entra

Los usuarios deben iniciar sesión para ver las API en el centro de API. Para habilitar el inicio de sesión, asigne el rol Lector de datos del Centro de API de Azure a usuarios o grupos de su organización, con ámbito al centro de API.

Importante

De forma predeterminada, usted y otros administradores del centro de API no tienen acceso a las API en el portal del Centro de API. Asegúrese de asignar el rol Lector de datos del Centro de API de Azure a usted mismo y a otros administradores.

Para obtener requisitos previos y pasos detallados para asignar un rol a usuarios y grupos, consulte Asignación de roles de Azure mediante Azure Portal. Siga estos pasos breves:

  1. En Azure Portal vaya al centro de API.
  2. En el menú de la izquierda, seleccione Control de acceso (IAM)>Agregar asignaciones de roles.
  3. En el panel Agregar asignación de roles, establezca los valores como se indica a continuación:
    • En la página Rol, busque y seleccione Lector de datos del Centro de API de Azure. Seleccione Siguiente.
    • En la página Miembros, en Asignar acceso a, seleccione Usuario, grupo o entidad de servicio>+ Seleccionar miembros.
    • En la página Seleccionar miembros, busque y seleccione los usuarios o grupos a los que asignar el rol. Haga clic en Seleccionar y, a continuación, en Siguiente.
    • Revise la asignación de roles y seleccione Revisar y asignar.

Nota:

Para simplificar la configuración de acceso para los nuevos usuarios, se recomienda asignar el rol a un grupo de Microsoft Entra y configurar una regla de pertenencia a grupos dinámicos. Más información: Crear o actualizar un grupo dinámico en Microsoft Entra ID.

Después de configurar el acceso al portal, los usuarios configurados pueden iniciar sesión en el portal y ver las API en el centro de API.

Nota:

Se pide al primer usuario que inicie sesión en el portal que dé su consentimiento a los permisos solicitados por el registro de la aplicación del portal del Centro de API. A partir de entonces, no se pide a otros usuarios configurados que dé su consentimiento.

Solución de problemas

Error: "No está autorizado para acceder a este portal"

En determinadas condiciones, un usuario podría encontrar el siguiente mensaje de error después de iniciar sesión en el portal del Centro de API con una cuenta de usuario configurada:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

En primer lugar, confirme que el usuario tiene asignado el rol Lector de datos del Centro de API de Azure en el centro de API.

Si al usuario se le asigna el rol, puede haber un problema con el registro del proveedor de recursos Microsoft.ApiCenter en la suscripción y es posible que tenga que volver a registrar el proveedor de recursos. Para ello, ejecute el siguiente comando en la CLI de Azure:

az provider register --namespace Microsoft.ApiCenter

No se puede iniciar sesión en el portal

Si los usuarios a los que se ha asignado el rol Lector de datos del Centro de API de Azure no pueden completar el flujo de inicio de sesión después de seleccionar Iniciar sesión en el portal del Centro de API, puede haber un problema con la configuración del proveedor de identidades de Microsoft Entra ID.

En el registro de aplicaciones de Microsoft Entra, revise y, si es necesario, actualice la configuración del URI de redirección para asegurarse de que el URI coincide con el URI de la implementación del portal del Centro de API.

No se pueden seleccionar los permisos del Centro de API de Azure en el registro de aplicaciones de Microsoft Entra

Si no puede solicitar permisos de API al Centro de API de Azure en el registro de aplicaciones de Microsoft Entra para el portal del Centro de API, compruebe que está buscando Centro de API de Azure (o identificador de aplicaciónc3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Si la aplicación no está presente, puede haber un problema con el registro del proveedor de recursos Microsoft.ApiCenter en la suscripción. Es posible que tenga que volver a registrar el proveedor de recursos. Para ello, ejecute el siguiente comando en la CLI de Azure:

az provider register --namespace Microsoft.ApiCenter

Después de volver a registrar el proveedor de recursos, vuelva a intentar solicitar permisos de API.

Directiva de soporte técnico

Proporcione comentarios, solicite características y obtenga soporte técnico para la implementación de referencia del portal del Centro de API en el repositorio de inicio del portal del Centro de API.

Contenido relacionado