Compartir vía

Importe las API a su centro de API desde Azure API Management

  • Artículo

En este artículo se muestra cómo importar (agregar) API desde una instancia de Azure API Management al centro de API mediante la CLI de Azure. Agregar API de API Management al inventario de API ayuda a que sean reconocibles y accesibles para desarrolladores, administradores de programas de API y otras partes interesadas de su organización.

En este artículo se muestran dos opciones para usar la CLI de Azure para agregar API al centro de API desde API Management:

  • Opción 1: Exportación de una definición de API desde una instancia de API Management mediante el comando az apim api export. A continuación, importe la definición al centro de API.

    Entre las posibles formas de importar una definición de API exportada desde API Management se incluyen las siguientes:

  • Opción 2: importación de API directamente desde API Management al centro de API mediante el comando az apic import-from-apim.

Después de importar definiciones de API o API desde API Management, puede agregar metadatos y documentación en el centro de API para ayudar a las partes interesadas a detectar, comprender y consumir la API.

Sugerencia

También puede configurar la sincronización automática de APIS desde API Management al centro de API. Para obtener más información, consulte Vinculación de una instancia de API Management para sincronizar las API con el centro de API.

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.

  • Una o varias instancias de Azure API Management, en la misma suscripción o en otra. Al importar las API directamente desde API Management, la instancia de API Management y el centro de API deben estar en el mismo directorio. Si no ha creado uno, consulte Creación de una instancia de Azure API Management.

  • Una o varias API administradas en la instancia de API Management que quiere agregar al centro de API.

  • Para la CLI de Azure:

    Nota:

    Los comandos az apic requieren la extensión apic-extension CLI de Azure. Si no ha usado comandos az apic, la extensión se puede instalar dinámicamente al ejecutar el primer comando az apic o puede instalar la extensión manualmente. Obtenga más información sobre las extensiones de la CLI de Azure.

    Consulte las notas de la versión para obtener los cambios y actualizaciones más recientes de apic-extension.

    Nota:

    Los ejemplos de comandos de la CLI de Azure de este artículo se pueden ejecutar en PowerShell o en un shell de Bash. Cuando sea necesario debido a una sintaxis de variable diferente, se proporcionan ejemplos de comandos independientes para los dos shells.

Opción 1: Exportación de una definición de API desde API Management e importarla al centro de API

En primer lugar, exporte una API desde la instancia de API Management a una definición de API mediante el comando az apim api export. En función de su escenario, puede exportar la definición de API a un archivo local o una dirección URL.

Exportación de la API a un archivo de definición de API local

El siguiente comando de ejemplo exporta la API con el identificador my-api en la instancia myAPIManagement de la API. La API se exporta en formato OpenApiJson a un archivo de definición de OpenAPI local en la ruta de acceso que se especifique.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Exportación de la API a una dirección URL

En el ejemplo siguiente, az apim api export exporta la API con el identificador my-api en formato OpenApiJson a una dirección URL en Azure Storage. La dirección URL está disponible durante aproximadamente 5 minutos. Aquí, el valor de la dirección URL se almacena en la variable $link.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Registro de la API en el centro de API desde la definición de API exportada

Puede registrar una nueva API en el centro de API desde la definición exportada mediante el comando az apic api register.

El siguiente ejemplo registra una API en el centro de API myAPICenter a partir de un archivo de definición de OpenAPI local denominado definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Importación de la definición de API a una API existente en el centro de API

En el ejemplo siguiente se usa el comando az apic api definition import-specification para importar una definición de API a una API existente en el centro de API de myAPICenter. Aquí, la definición de API se importa desde una dirección URL almacenada en la variable $link.

En este ejemplo se supone que tiene una API denominada my-api y una versión de API asociada v1-0-0 y una entidad de definición openapi en el centro de API. Si no lo hace, consulte Adición de API al centro de API.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Opción 2: Importación de API directamente desde la instancia de API Management

A continuación, se indican los pasos para importar las API desde la instancia de API Management al centro de API mediante el comando az apic import-from-apim. Este comando es útil cuando desea importar varias API de API Management al centro de API, pero también puede usarla para importar una sola API.

Al agregar las API desde una instancia de API Management al centro de API mediante az apic import-from-apim, se produce automáticamente lo siguiente:

  • Las versiones, definiciones e información de implementación de cada API se copian en el centro de API.
  • La API recibe un nombre de API generado por el sistema en el centro de API. Conserva su nombre para mostrar (título) de API Management.
  • La fase de ciclo de vida de la API se establece en Diseño.
  • Azure API Management se agrega como entorno.

Adición de una identidad administrada en el centro de API

En este escenario, el centro de API usa una identidad administrada para acceder a las API de la instancia de API Management. En función de sus necesidades, configure una identidad administrada asignada por el sistema o una o varias identidades administradas asignadas por el usuario.

En los siguientes ejemplos se muestra cómo configurar una identidad administrada asignada por el sistema mediante Azure Portal o la CLI de Azure. A un nivel alto, los pasos de configuración son similares para una identidad administrada asignada por el usuario.

  1. En el portal, vaya al centro de API.
  2. En el menú de la izquierda, en Seguridad, seleccione Identidades administradas.
  3. Seleccione Asignado por el sistema y establezca el estado en Activado.
  4. Seleccione Guardar.

Asignación de la identidad administrada al rol Lector del servicio API Management

Para permitir la importación de API, asigne la identidad administrada del centro de API al rol Lector del servicio API Management en la instancia de API Management. Puede usar el portal o la CLI de Azure.

  1. En el portal, vaya a la instancia de API Management.
  2. En el menú izquierdo, seleccione Control de acceso (IAM) .
  3. Seleccione + Agregar asignación de roles.
  4. En la página Agregar asignación de roles, establezca los valores como se indica a continuación:
    1. En la pestaña Rol: seleccione Lector del servicio API Management.
    2. En la pestaña Miembros, en Asignar acceso a, seleccione Identidad administrada> + Seleccionar miembros.
    3. En la página Seleccionar identidades administradas: seleccione la identidad administrada asignada por el sistema del centro de API que agregó en la sección anterior. Haga clic en Seleccionar.
    4. Seleccione Revisar y asignar.

Importación de API desde API Management

Use el comando az apic import-from-apim para importar una o varias API desde la instancia de API Management al centro de API.

Nota:

  • Este comando depende de una identidad administrada configurada en el centro de API que tenga permisos de lectura para la instancia de API Management. Si no ha agregado ni configurado una identidad administrada, consulte Adición de una identidad administrada en el centro de API anteriormente en este artículo.

  • Si el centro de API tiene varias identidades administradas, el comando busca primero una identidad asignada por el sistema. Si no se encuentra ninguna, elige la primera identidad asignada por el usuario en la lista.

Importación de todas las API dentro de una instancia de API Management

En el comando siguiente, sustituya los nombres del centro de API, el grupo de recursos del centro de API, la instancia de API Management y el grupo de recursos de la instancia. Use * para especificar todas las API de la instancia de API Management.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'  

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'

Nota:

Si la instancia de API Management tiene un gran número de API, la importación en el centro de API puede tardar algún tiempo.

Importación de una API específica desde una instancia de API Management

Especifique una API para importar con su nombre desde la instancia de API Management.

En el comando siguiente, sustituya los nombres del centro de API, el grupo de recursos del centro de API, la instancia de API Management y el grupo de recursos de la instancia. Pase un nombre de API como petstore-api mediante el parámetro --apim-apis.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'        

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'

Nota:

Especifique un nombre de API mediante el nombre del recurso de API en la instancia de API Management, no el nombre para mostrar. Por ejemplo, petstore-api en lugar de Petstore API.

Después de importar las API desde API Management, puede ver y administrar las API importadas en el centro de API.

Contenido relacionado