Utilice la CLI de Azure para administrar su inventario de API

En este artículo se muestra cómo utilizar los comandos az apic api de la CLI de Azure para agregar y configurar API en el inventario del centro de API. Utilice comandos en la CLI de Azure para programar operaciones para administrar su inventario de API y otros aspectos de su 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.

• Para la CLI de Azure:

  • Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.

    

  • Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.

    • Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

    • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

    • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

  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.

Registro de API, versión de API y definición

Los siguientes pasos muestran cómo crear una API y asociar una única versión y definición de API. Para obtener más información sobre el modelo de datos del Centro de API de Azure, consulte Conceptos clave.

Creación de una API

Utilice el comando az apic api create para crear una API en su centro de API.

El siguiente ejemplo crea una API denominada Petstore API en el grupo de recursos myResourceGroup y el centro de API myAPICenter. La API es una API REST.

az apic api create  --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

Crear una versión de la API

Utilice el comando az apic api version create para crear una versión para su API.

El siguiente ejemplo crea una versión de la API denominada v1-0-0 para la API petstore-api que creó en la sección anterior. La versión se establece en la fase de ciclo de vida de pruebas.

az apic api version create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

Crear definición de API y agregar archivo de especificaciones

Utilice los comandos az apic api definition para agregar una definición y un archivo de especificación adjunto para una versión de API.

Crear una definición

El siguiente ejemplo utiliza el comando az apic api definition create para crear una definición llamada openapi para la versión de la API petstore-api que creó en la sección anterior.

az apic api definition create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

Importar un fichero de especificaciones

Importe un archivo de especificación a la definición utilizando el comando az apic api definition import-specification.

El siguiente ejemplo importa un archivo de especificación OpenAPI desde una URL de acceso público a la definición openapi que creó en el paso anterior. Las name y las propiedades version del recurso de especificación se pasan como JSON.

az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

Sugerencia

Puede importar el archivo de especificación en línea estableciendo el parámetro --format a inline y pasando el contenido del archivo utilizando el parámetro --value.

Exportar un fichero de especificaciones

Para exportar una especificación de API desde su centro de API a un archivo local, utilice el comando az apic api definition export-specification.

El siguiente ejemplo exporta el archivo de especificaciones de la definición de openapi que creó en la sección anterior a un archivo local denominado specificationFile.json.

az apic api definition export-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

Registro de API a partir de un archivo de especificaciones de un solo paso

Puede registrar una API desde un archivo de especificación local en un solo paso utilizando el comando az apic api register. Con esta opción, se crean automáticamente una versión y una definición de API por defecto para la API.

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

az apic api register --resource-group myResourceGroup \
    --service-name myAPICenter --api-location "/Path/to/specificationFile.json"

• El comando establece las propiedades de la API, como el nombre y el tipo, a partir de los valores del archivo de definición.
• De forma predeterminada, el comando establece la etapa del ciclo de vidade la API en diseño.
• Crea una versión de la API denominada según la propiedad version de la definición de la API (o 1-0-0 de manera predeterminada), y una definición de la API denominada según el formato de la especificación (por ejemplo, openapi).

Actualizar las propiedades de la API

Una vez registrada una API, puede actualizar sus propiedades mediante los comandos az apic api update, az apic api version update y az apic api definition update.

En el ejemplo siguiente se actualiza el título de API petstore-api a Petstore API v2.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API v2"

En el ejemplo siguiente se establece la propiedad personalizada internabooleana de la API en false.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --set custom_properties.internal=false

Eliminar recursos de la API

Utilice el comando az apic api delete para eliminar una API y todos sus recursos de versión y definición. Por ejemplo:

az apic api delete \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api

Para eliminar versiones y definiciones individuales de la API, utilice az apic api version delete y az apic api definition delete, respectivamente.

Contenido relacionado

• Consulte la referencia a la Interfaz de la línea de comandos de Azure para el Centro de API de Azure para obtener una lista completa de comandos, incluidos los comandos para administrar entornos, implementaciones, esquemas de metadatos y servicios.
• Importe las API a su centro API desde API Management
• Utilice la extensión de Visual Studio para el Centro de API para crear y registrar API desde Visual Studio Code.
• Registro de API en el centro de API mediante Acciones de GitHub