Compartir a través de

Habilitación y visualización del catálogo de API de la plataforma del Azure API Center

  • Artículo

En este artículo se muestra cómo proporcionar a los desarrolladores empresariales acceso al catálogo de API de la plataforma del Azure API Center (versión preliminar) en la extensión de Visual Studio Code para Azure API Center. Con el catálogo de API de plataforma, los desarrolladores pueden detectar API en el Azure API Center, ver definiciones de API y, opcionalmente, generar clientes de API cuando no tienen acceso para administrar el propio centro de API o agregar API al inventario. El acceso al catálogo de API de la plataforma se administra mediante el Microsoft Entra ID y el control de acceso basado en rol de Azure.

Sugerencia

La extensión de Visual Studio Code proporciona más características para los desarrolladores de API que tienen permisos para administrar un centro de API de Azure. Por ejemplo, los desarrolladores de API pueden registrar las API directamente en el centro de API o mediante canalizaciones de CI/CD. Más información

Requisitos previos

Para administradores del centro de API

  • 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 desarrolladores de aplicaciones

  • Extensión del Azure API Center para Visual Studio Code

    Importante

    Actualmente, el acceso al catálogo de API de la plataforma solo está disponible en la versión preliminar de la extensión. Al instalar la extensión desde el Marketplace de Visual Studio Code, puede optar por instalar la versión de lanzamiento o una versión preliminar. Cambie entre las dos versiones en cualquier momento mediante el menú contextual del botón Administrar de la extensión en la vista Extensiones.

La siguiente extensión de Visual Studio Code es opcional:

Pasos para que los administradores del centro de API habiliten el acceso al catálogo

En las secciones siguientes se proporcionan pasos para que los administradores del centro de API permitan a los desarrolladores empresariales acceder al catálogo de API de la plataforma.

Cree un registro de aplicaciones de Microsoft Entra

En primer lugar, configure un registro de aplicaciones en el inquilino de Microsoft Entra ID. El registro de aplicaciones permite que la extensión de Visual Studio Code para Azure API Center acceda al catálogo de API de plataforma en nombre de un usuario que haya 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 platform-api-catalog
    • 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 en el URI de runtime del centro de API. Por ejemplo, https://<service name>.data.<region>.azure-apicenter.ms. Ejemplo: https://contoso-apic.data.eastus.azure-apicenter.ms.
    • Seleccione Registrar.

    Sugerencia

    Puede usar el mismo registro de aplicaciones para acceder a más centros de API. En URI de redirección, continúe agregando URI de redirección para otros centros de API que desee que aparezcan en el catálogo de API de la plataforma.

  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 más adelante al conectarse al centro de API desde la extensión de Visual Studio Code.

  5. En el menú de la izquierda, en Administrar, seleccione Autenticación>+ Agregar una plataforma.

  6. En la página Configurar plataformas, seleccione aplicaciones móviles y de escritorio.

  7. En la página Configurar escritorio y dispositivos, escriba el siguiente URI de redirección y seleccione Configurar:

    https://vscode.dev/redirect

  8. En el menú de la izquierda, en Administrar, seleccione Permisos de API>+ Agregar un permiso.

  9. En la página Solicitar permisos de API, haga lo siguiente:

    1. Seleccione la pestaña API usadas en mi organización.
    2. Busque y seleccione Centro de API deAzure. También puede buscar y seleccionar el identificador de aplicaciónc3ca1a77-7a87-4dba-b8f8-eea115ae4573.
    3. En Seleccionar permisos, seleccione user_impersonation.
    4. Selecciona 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.

Habilite el inicio de sesión en el catálogo de API de plataforma por parte de usuarios y grupos de Microsoft Entra

Los desarrolladores empresariales deben iniciar sesión con una cuenta de Microsoft para ver el catálogo de API de la plataforma para el centro de API. Si es necesario, agregue o invite a desarrolladores a su inquilino de Microsoft Entra.

Luego, para habilitar el inicio de sesión, asigne el rol Lector de datos del Azure API Center a usuarios o grupos de su inquilino, con ámbito del centro de API.

Importante

De forma predeterminada, usted y otros administradores del centro de API no tienen acceso a las API en el catálogo de API de la extensión 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.
  4. Repita los pasos anteriores para habilitar el inicio de sesión en el catálogo de API de plataforma para más centros de API.

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.

Pasos para que los desarrolladores empresariales accedan al catálogo de API de la plataforma

Los desarrolladores pueden seguir estos pasos para conectarse e iniciar sesión para ver un catálogo de API de plataforma mediante la extensión de Visual Studio Code. El administrador del centro de API debe proporcionar la configuración para conectarse al centro de API.

Conexión a un centro de API

  1. Instale la versión preliminar de la extensión Azure API Center para Visual Studio Code para Visual Studio Code.

  2. En Visual Studio Code, en la barra de actividades de la izquierda, seleccione Centro de API.

    Captura de pantalla del icono del centro de API en la barra de actividades.

  3. Utilice la combinación de teclas Ctrl+Mayús+P para abrir la paleta de comandos. Escriba Azure API Center: conectarse a un Centro de API y presione Entrar.

  4. Responda a las indicaciones para introducir la siguiente información:

    1. La dirección URL del runtime del centro de API, en el formato <service name>.data.<region>.azure-apicenter.ms (sin prefijos con https://). Ejemplo: contoso-apic.data.eastus.azure-apicenter.ms. Esta dirección URL del runtime aparece en la página información general del centro de API en Azure Portal.
    2. Identificador de aplicación (cliente) del registro de aplicaciones configurado por el administrador en la sección anterior.
    3. Identificador de directorio (inquilino) del registro de aplicaciones configurado por el administrador en la sección anterior.

    Sugerencia

    Un administrador del centro de API debe proporcionar estos detalles de conexión a los desarrolladores o proporcionar un vínculo directo en el formato siguiente:
    vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

    Después de conectarse al centro de API, el nombre del centro de API aparece en el catálogo de API de la plataforma del centro de API.

  5. Para ver las API en el centro de API, en el nombre del centro de API, seleccione Iniciar sesión en Azure. El inicio de sesión se permite con una cuenta de Microsoft que tenga asignado el rol lector de datos del Azure API Center en el centro de API.

    Captura de pantalla del catálogo de API de plataforma del centro de API en la extensión de VS Code.

  6. Después de iniciar sesión, seleccione API para enumerar las API en el centro de API. Expanda una API para explorar sus versiones y definiciones.

    Captura de pantalla del catálogo de API de plataforma del centro de API con API en la extensión de VS Code.

  7. Repita los pasos anteriores para conectarse a más centros de API, si el acceso está configurado.

Detección y consumo de API en el catálogo

El catálogo de API de plataforma ayuda a los desarrolladores empresariales a detectar detalles de API e iniciar el desarrollo de cliente de API. Los desarrolladores pueden acceder a las siguientes características haciendo clic con el botón derecho en una definición de API en el catálogo de API de plataforma:

  • Documento de especificación de API de exportación: exporte una especificación de API desde una definición y, después, descárguela como un archivo
  • Generar cliente de API: utilice la extensión Microsoft Kiota para generar un cliente API para su idioma favorito
  • Generar markdown: genere documentación de API en formato Markdown
  • Documentación de OpenAPI: vea la documentación de una definición de API y pruebe las operaciones en una interfaz de usuario de Swagger (solo está disponible para las definiciones de OpenAPI).

Solución de problemas

En determinadas condiciones, un usuario podría encontrar el siguiente mensaje de error después de iniciar sesión en el catálogo de API de la plataforma del centro de API y expandir la lista de API para un centro de API:

Error: Cannot read properties of undefined (reading 'nextLink')

Compruebe que el usuario tiene asignado el rol Lector de datos del Centro de API de Azure en el centro de API. Si es necesario, asigne el rol al usuario. A continuación, actualice el catálogo de la plataforma del centro de API en la extensión de Visual Studio Code.

No se puede iniciar sesión en Azure

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 Azure en el catálogo de API de la plataforma, puede haber un problema con la configuración de la conexión.

Compruebe la configuración del registro de la aplicación que configuró en Microsoft Entra ID. Confirme los valores del identificador de aplicación (cliente) y el identificador de directorio (inquilino) en el registro de la aplicación y la dirección URL del runtime del centro de API. A continuación, vuelva a configurar la conexión al centro de API.

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

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.

Contenido relacionado